Claude
53080ffa53
死文件治理：GUIDE.md（25 處）與 README.md（21 處）仍在教 u6u_* 工具名， 含本 PR 已刪的 4 個 tool（deploy/execute/get/list_workflows），下個 CC 照著走會撞牆。 - 全部 u6u_* → 現役 arcrun_*（component/tag/gui 那批用新名） - 已刪 tool 改指現役：execute→run、deploy→push、get/list_workflows→crud 版 - 修正因換工具而失真的流程與參數：沙盒測試段改為 arcrun_validate_yaml（部署前 schema 驗證）→ arcrun_push_workflow（部署）→ arcrun_run_workflow（觸發，帶 api_key/name/input）；get_workflow 參數 workflow_id→name - 順帶把兩處品牌 prose "u6u" 改 "Arcrun" - grep 確認兩檔零 u6u brand.ts：釐清 ARCRUN_TOOL_PREFIX 覆蓋僅內部 rebrand 過渡 / 測試鉤子， Workers runtime 無 process 全域基本不生效、勿當對外特性。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015d5jDbuqT5Htwv3Q88XXKk
195 lines
6.0 KiB
Markdown
195 lines
6.0 KiB
Markdown
# Arcrun MCP Server
|
||
|
||
> Arcrun 是 **AI 優先（AI-First）** 的工作流自動化平台。
|
||
> 跟 AI 描述你的意圖，Arcrun 幫你把它變成可重複執行、不需要 AI 的自動化工作流。
|
||
|
||
Arcrun 是反過來的 n8n。n8n 從手寫程式開始，Arcrun 從 AI 描述開始——你說「去抓銀行匯率，用 Telegram 通知我」，AI 把它拆成三元組，Arcrun 查零件庫、組裝、執行。第一次需要 AI，之後自動跑，不再花 Token。
|
||
|
||
本目錄是 Arcrun 的 **MCP Server**（已併入 arcrun 主庫 `arcrun/mcp/`），讓 Claude Code 等 AI client 直接呼叫 Arcrun 的工作流與零件功能。它是「薄殼」——連哪台 cypher / 哪個帳號由設定決定，與 CLI 共用同一份身份來源。
|
||
|
||
---
|
||
|
||
## 快速上手
|
||
|
||
### 最簡單：用 CLI 產生連線設定（推薦）
|
||
|
||
```bash
|
||
acr mcp-setup
|
||
```
|
||
|
||
`acr mcp-setup` 依你的 arcrun 設定（env > 專案 `.arcrun.yaml` > 全域）在當前資料夾寫 `.mcp.json`，
|
||
Claude Code 進此資料夾就連對的 MCP。`acr init` 也會自動順帶跑這步。
|
||
|
||
- 沒設 `mcp_url` → 連平台預設 `https://mcp.arcrun.dev`。
|
||
- 自架 / 接案：在 `.arcrun.yaml` 設 `mcp_url`（或 `ARCRUN_MCP_URL` env）指向自己 / 客戶的 MCP，再 `acr mcp-setup`。
|
||
|
||
### 手動設定（Claude Desktop / Cursor）
|
||
|
||
`.mcp.json` / client MCP 設定內容（remote HTTP MCP）：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"arcrun": {
|
||
"type": "http",
|
||
"url": "https://mcp.arcrun.dev"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
> 平台託管的 MCP 需要 arcrun API Key 授權；自架的 MCP 綁你自己的 cypher。
|
||
> 連線 URL 以 `acr mcp-setup` 產出的為準。
|
||
|
||
> 使用 `type: http`（Streamable HTTP transport）。舊版 SSE 格式（`type: sse`）已不支援。
|
||
|
||
---
|
||
|
||
## MCP Tools 說明
|
||
|
||
### 零件開發（WASM）
|
||
|
||
零件是 Arcrun 的最小執行單元，以 TinyGo 編譯為 `.wasm`，透過 stdin/stdout JSON 通訊。
|
||
|
||
| Tool | 說明 |
|
||
|------|------|
|
||
| `arcrun_get_component_guide` | **開發新零件前必須先呼叫。** 取得 TinyGo 開發指引，包含白名單 import、禁止行為、contract YAML 範例、本地測試指令。 |
|
||
| `arcrun_search_components` | 用自然語言語意搜尋零件庫。例如：「查詢 Google Sheets 資料」、「發送 LINE 訊息」。回傳零件清單含 canonical_id、描述、評分。 |
|
||
| `arcrun_get_component` | 取得指定零件的完整合約（input_schema、output_schema、gherkin_tests、評分統計等）。 |
|
||
| `arcrun_publish_component` | 提交 TinyGo WASM 零件。需提供 `contract`（合約物件）與 `wasm_base64`（編譯後的 .wasm base64）。Registry 自動執行沙盒驗收。 |
|
||
|
||
### 工作流執行
|
||
|
||
| Tool | 說明 |
|
||
|------|------|
|
||
| `arcrun_validate_yaml` | 部署前驗證工作流 YAML 的 schema。輸入 `yaml_content`。 |
|
||
| `arcrun_push_workflow` | 將工作流 YAML 部署至雲端引擎。輸入 `api_key` 與 `yaml_content`。 |
|
||
| `arcrun_run_workflow` | 觸發已部署的工作流執行。輸入 `api_key`、`name`，選填 `input`（帶進 trigger context）。 |
|
||
|
||
### 工作流管理
|
||
|
||
| Tool | 說明 |
|
||
|------|------|
|
||
| `arcrun_list_workflows` | 列出已部署的工作流。可傳入選填的 `tag` 參數篩選。 |
|
||
| `arcrun_get_workflow` | 取得指定工作流的 metadata。輸入 `name`。 |
|
||
|
||
### 零件管理
|
||
|
||
| Tool | 說明 |
|
||
|------|------|
|
||
| `arcrun_list_components` | 列出已發佈的零件。可傳入選填的 `tag` 參數篩選。 |
|
||
|
||
### Tag 管理
|
||
|
||
| Tool | 說明 |
|
||
|------|------|
|
||
| `arcrun_create_tag` | 建立新 tag。輸入 `name`（必填）與 `description`（選填）。 |
|
||
| `arcrun_list_tags` | 列出當前命名空間下所有 tag。 |
|
||
| `arcrun_delete_tag` | 刪除指定 tag。輸入 `tag_name`。 |
|
||
| `arcrun_tag_resource` | 為工作流或零件加上 tag。輸入 `resource_type`、`resource_id`、`tag_name`。 |
|
||
| `arcrun_untag_resource` | 移除工作流或零件的 tag。 |
|
||
|
||
---
|
||
|
||
## 零件開發流程（WASM）
|
||
|
||
Arcrun 的零件是 TinyGo 編譯的 `.wasm`，透過 stdin/stdout JSON 通訊，可在 Cloudflare Workers（Tier 1/2）和 Wazero 邊緣環境（Tier 3）執行。
|
||
|
||
### 步驟一：取得開發指引
|
||
|
||
```
|
||
arcrun_get_component_guide
|
||
```
|
||
|
||
指引包含：TinyGo 白名單 import、禁止行為、`component.contract.yaml` 完整範例、本地測試指令。
|
||
|
||
### 步驟二：搜尋現有零件
|
||
|
||
```
|
||
arcrun_search_components("查詢 Google Sheets 資料")
|
||
```
|
||
|
||
若已有符合的零件，直接使用，不需要重新開發。
|
||
|
||
### 步驟三：開發零件（若缺件）
|
||
|
||
依指引用 TinyGo 撰寫零件，只使用白名單 import：
|
||
|
||
```go
|
||
import (
|
||
"os"
|
||
"io"
|
||
"encoding/json"
|
||
)
|
||
```
|
||
|
||
編譯：
|
||
|
||
```bash
|
||
tinygo build -o my_component.wasm -target=wasi .
|
||
```
|
||
|
||
本地測試：
|
||
|
||
```bash
|
||
echo '{"input_field":"value"}' | wasmtime my_component.wasm
|
||
```
|
||
|
||
### 步驟四：提交零件
|
||
|
||
```
|
||
arcrun_publish_component(
|
||
contract={...}, // component.contract.yaml 內容
|
||
wasm_base64="..." // base64(my_component.wasm)
|
||
)
|
||
```
|
||
|
||
Registry 自動執行沙盒驗收（體積、syscall 掃描、Gherkin 測試）。
|
||
|
||
---
|
||
|
||
## 工作流開發流程
|
||
|
||
### 步驟一：搜尋零件
|
||
|
||
```
|
||
arcrun_search_components("查詢匯率")
|
||
arcrun_search_components("發送 Telegram 訊息")
|
||
```
|
||
|
||
### 步驟二：部署前驗證
|
||
|
||
```
|
||
arcrun_validate_yaml(yaml_content="...")
|
||
```
|
||
|
||
### 步驟三：部署
|
||
|
||
```
|
||
arcrun_push_workflow(api_key="ak_xxx", yaml_content="...")
|
||
```
|
||
|
||
### 步驟四：觸發執行
|
||
|
||
```
|
||
arcrun_run_workflow(api_key="ak_xxx", name="exchange-rate-notify", input={"currency_pair": "USD/TWD"})
|
||
```
|
||
|
||
---
|
||
|
||
## Inspector 測試界面
|
||
|
||
開啟 `https://mcp.arcrun.dev/inspector`（或自架 MCP 的 `/inspector`）即可在瀏覽器中互動式測試所有 MCP tools。
|
||
|
||
---
|
||
|
||
## 搭配 arcrun-gui 使用
|
||
|
||
[arcrun-gui](../arcrun-gui) 是 Arcrun 的人類操作介面，與 arcrun-mcp 共享同一個 KBDB 狀態：
|
||
|
||
- AI 透過 arcrun-mcp 操作（搜尋零件、執行 Workflow）
|
||
- 人類透過 arcrun-gui 操作（拖拉畫布、查看零件庫）
|
||
- AI 的操作結果即時反映在 arcrun-gui 的畫布上
|
||
|
||
詳細開發指南請參閱 **[GUIDE.md](./GUIDE.md)**。
|