Leo
5491409003
- acr update：self-hosted 重跑部署、只部署變動 Worker、未變動略過（--force 全部重部）。 - 說明「新裝 vs 更新」差不多同一套流程，拿新零件(如 code)/新版就跑更新。 - 標待核佔位：下載源正從 GitHub codeload 改指 Gitea（Arcrun#4），確切行為待該 PR 定案。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
253 lines
12 KiB
Markdown
253 lines
12 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.ai、Claude Code、Claude Desktop 等 AI client 直接呼叫 Arcrun 的工作流與零件功能。它是「薄殼」——連哪台 cypher / 哪個帳號由設定決定，與 CLI 共用同一份身份來源。
|
||
|
||
**這份文件教你怎麼把這個 MCP 裝到你的前端來用。** 想貢獻新零件（投稿 WASM 元件）請見文末的 [貢獻新零件](#貢獻新零件)。
|
||
|
||
---
|
||
|
||
## MCP 連線 URL（先搞懂這個）
|
||
|
||
MCP 的 Streamable HTTP 端點路徑是 **`/mcp`**（worker 根路徑 `/` 會 404）。無論哪種前端，你要填的 URL 都是：
|
||
|
||
| 部署 | MCP URL |
|
||
|------|---------|
|
||
| **官方託管 SaaS** | `https://mcp.arcrun.dev/mcp` |
|
||
| **自架 / 接案（self-hosted）** | `https://arcrun-mcp.<你的CF子域>.workers.dev/mcp` |
|
||
|
||
> `<你的CF子域>` 是你 Cloudflare 帳號的 workers.dev 子域（`acr init --self-hosted` 部署後由 `workers_dev` 產生）。**請依你的實際部署子域調整。**
|
||
> 若你自己綁了 custom domain（如 `mcp.example.com`），URL 就是 `https://mcp.example.com/mcp`。
|
||
|
||
Transport 一律用 **`type: http`（Streamable HTTP）**。舊版 SSE（`type: sse`）已不支援。
|
||
|
||
---
|
||
|
||
## 安裝方式
|
||
|
||
### 1. claude.ai 雲端 connector（遠端）
|
||
|
||
claude.ai 走 **OAuth 2.1 + PKCE** 認證（見下方[認證](#認證)），適合自架部署的 owner 遠端使用。
|
||
|
||
1. claude.ai → **Settings → Connectors → Add custom connector（新增自訂 connector）**。
|
||
2. **MCP Server URL** 貼上你的 MCP URL（例：`https://arcrun-mcp.<你的CF子域>.workers.dev/mcp`）。
|
||
3. 儲存後點 **Connect**，claude.ai 會自動發現 OAuth（透過 `/.well-known/oauth-protected-resource`）並跳到同意頁 `/authorize`。
|
||
4. 在同意頁**輸入 owner secret**——就是你部署時用 `wrangler secret put MCP_OWNER_SECRET` 設的那組祕密（只有 owner 知道）。祕密正確才發 token，之後 claude.ai 用該 token 呼叫工具。
|
||
5. token 有效期預設 30 天（`MCP_TOKEN_TTL`）；到期後 claude.ai 會自動重走 OAuth，再輸一次 owner secret 即可。
|
||
|
||
> 官方 SaaS（`mcp.arcrun.dev`）走的是 partner-key 驗證，不是 owner-secret 同意頁；一般接案／自架用戶用的是上面這條 OAuth 路徑。
|
||
|
||
### 2. Claude Code（CC / IDE）
|
||
|
||
Claude Code 用專案層 `.mcp.json`（HTTP transport）掛同一個 URL，auth 走 OAuth（首次連線時在瀏覽器完成 owner-secret 同意頁）。
|
||
|
||
**推薦：用 CLI 自動產生**（依你的 arcrun 設定寫對的 URL，接案切資料夾自動切帳號）：
|
||
|
||
```bash
|
||
acr mcp-setup
|
||
```
|
||
|
||
`acr mcp-setup` 依「env > 專案 `.arcrun.yaml` > 全域」解析出的 `mcp_url` 在當前資料夾寫 `.mcp.json`；沒設 `mcp_url` 就 fallback 平台預設 `https://mcp.arcrun.dev/mcp`。`acr init` 也會自動順帶跑這步。
|
||
|
||
**手動：** 在專案根建 `.mcp.json`：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"arcrun": {
|
||
"type": "http",
|
||
"url": "https://arcrun-mcp.<你的CF子域>.workers.dev/mcp"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
官方 SaaS 版本把 `url` 換成 `https://mcp.arcrun.dev/mcp` 即可。
|
||
|
||
也可用 CLI 直接加（HTTP transport）：
|
||
|
||
```bash
|
||
claude mcp add --transport http arcrun https://arcrun-mcp.<你的CF子域>.workers.dev/mcp
|
||
```
|
||
|
||
### 3. 本機 Claude Desktop
|
||
|
||
Claude Desktop 的 `claude_desktop_config.json`（macOS：`~/Library/Application Support/Claude/`；Windows：`%APPDATA%\Claude\`）加一組 remote HTTP MCP：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"arcrun": {
|
||
"type": "http",
|
||
"url": "https://arcrun-mcp.<你的CF子域>.workers.dev/mcp"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
> **若你的 Claude Desktop 版本尚不支援 remote HTTP MCP**，改用 `mcp-remote` proxy 把 remote MCP 橋成本機 stdio：
|
||
>
|
||
> ```json
|
||
> {
|
||
> "mcpServers": {
|
||
> "arcrun": {
|
||
> "command": "npx",
|
||
> "args": ["-y", "mcp-remote", "https://arcrun-mcp.<你的CF子域>.workers.dev/mcp"]
|
||
> }
|
||
> }
|
||
> }
|
||
> ```
|
||
>
|
||
> `mcp-remote` 會自動處理 OAuth 流程（跳瀏覽器完成 owner-secret 同意頁）。
|
||
|
||
---
|
||
|
||
## 更新（取得新零件 / 新版）
|
||
|
||
**更新流程 ≈ 重跑一次部署，已安裝的自動略過。** self-hosted 用戶要拿新零件（例如新增的 `code` 零件）或新版引擎時：
|
||
|
||
```bash
|
||
acr update
|
||
```
|
||
|
||
`acr update` 會下載最新的 Arcrun 部署物，只**部署新增 / 變更的 Worker，未變動的自動跳過**（終端會顯示「N 個未變動已跳過」）。它與 `acr init --self-hosted` 走同一條路（下載 → 注入 KV id → `wrangler deploy`），差別只在：`init` 是首次（建 KV / R2 + 寫 config），`update` 是沿用既有 config 重部署有變動的 Worker。所以「新裝 arcrun」和「更新」其實**差不多同一套流程**——想拿新零件 / 新版就跑更新。
|
||
|
||
- 只在 **self-hosted 模式**可用（部署在你自己的 Cloudflare）；官方 SaaS 用戶由平台自動更新，不需要跑。
|
||
- 要強制把**全部** Worker 重部署一遍：`acr update --force`。
|
||
- 冪等：KV namespace / D1 等基礎設施已存在則重用，不會重建。
|
||
|
||
> ⚠️ **更新源現況（待核佔位）**：`acr update` 的下載源正從 GitHub codeload 改指 **Gitea 自有真身**（修復追蹤 Arcrun#4）。上面描述以「修好後的 Gitea 版」為準；確切指令與來源行為**待該修復 PR 定案**，屆時再回來校正。
|
||
|
||
---
|
||
|
||
## 認證
|
||
|
||
MCP 打進 arcrun ＝ 觸及該租戶 **KBDB 全量讀寫**，必須有真認證。中介層（`src/middleware/partner-auth.ts`）依序嘗試：
|
||
|
||
1. **OAuth 2.1 access_token**（自架部署的遠端正規路徑）
|
||
- claude.ai / Claude Code / Claude Desktop 遠端連線都走這條。
|
||
- 唯一的人類祕密閘在 `/authorize` 同意頁：輸入 **`MCP_OWNER_SECRET`**（部署時以 CF Secret 設定，只有 owner 知道）。祕密正確才發 authorization code → 換 access_token。
|
||
- 只知道「網址」的人打得開同意頁、能跑 DCR，但**沒有 owner secret 就換不到 token**，打 `/mcp` 一律 401。
|
||
2. **`MCP_STATIC_TOKEN`（CF Secret，本機 / CLI 相容路徑）**
|
||
- 本機 Claude Code / GUI 若不想每次走 OAuth，可設 `MCP_STATIC_TOKEN`（真祕密），把它當 `Authorization: Bearer <此值>` 帶進 `.mcp.json`。
|
||
- 這是取代**已廢除的「明碼 namespace 當 bearer」**舊路徑的安全做法——用真祕密 token，而非把 namespace 明碼放行。
|
||
3. **官方 SaaS（`MULTI_TENANT` 未設 / `true`）** → KBDB partner-key（`pk_live…`）驗證，行為不變。
|
||
|
||
> ⚠️ **舊的「明碼 namespace bearer」路徑已從預設移除**（送 `Bearer leo` 就能讀 leo 全部資料的洞已補）。只有明確設 `ALLOW_PLAINTEXT_NAMESPACE="true"`（遷移期逃生門，預設關、將 SUNSET）才會恢復，正式環境勿用。
|
||
|
||
完整安全模型（PKCE、audience 綁定、KV 儲存鐵律、redirect 白名單）見 **[OAUTH.md](./OAUTH.md)**。
|
||
|
||
---
|
||
|
||
## 部署前置（self-hosted 用戶）
|
||
|
||
自架前，先把 OAuth 需要的 KV 與 Secret 就緒（完整清單見 **[OAUTH.md](./OAUTH.md) §7**，此處只摘要）：
|
||
|
||
1. `acr init --self-hosted` 部署 arcrun-mcp worker。
|
||
- **CLI 路徑**：`OAUTH_KV` namespace 由 `deploy.ts` 自動建立並填入真 id（零手動）。
|
||
- **手動直推**：`wrangler kv namespace create OAUTH_MCP` → 把 id 貼進 `mcp/wrangler.toml` 的 `[[kv_namespaces]] OAUTH_KV`。
|
||
2. **設 owner secret**：`wrangler secret put MCP_OWNER_SECRET`（輸入只有你知道的強祕密）。
|
||
3. （選配）**設本機相容 static token**：`wrangler secret put MCP_STATIC_TOKEN`。
|
||
4. （選配）`[vars]` 調整 `MCP_OWNER_NAMESPACE`（預設 `leo`）/ `MCP_TOKEN_TTL`（預設 2592000＝30 天）/ `MCP_ALLOWED_REDIRECT_HOSTS`。
|
||
5. 驗收：`curl <origin>/.well-known/oauth-protected-resource` → 200；未帶 token 打 `/mcp` → 401 帶 `WWW-Authenticate`；claude.ai 加 connector 走完 OAuth 能連上。
|
||
|
||
> KV / secret 未就緒時，OAuth 端點誠實回 503、`/mcp` 回 401（不假綠），既有官方 SaaS partner-key 路徑不受影響。
|
||
|
||
---
|
||
|
||
## MCP Tools 總覽
|
||
|
||
連上後，前端會看到兩組工具：`arcrun_*`（平台功能）與 `kbdb_*`（資料層）。
|
||
|
||
### `arcrun_*`
|
||
|
||
**工作流（Workflow）**
|
||
|
||
| Tool | 一句話 |
|
||
|------|--------|
|
||
| `arcrun_validate_yaml` | 部署前驗證工作流 YAML schema。 |
|
||
| `arcrun_push_workflow` | 把工作流 YAML 部署到雲端引擎。 |
|
||
| `arcrun_run_workflow` | 觸發已部署的工作流執行（可帶 `input`）。 |
|
||
| `arcrun_list_workflows` / `arcrun_get_workflow` / `arcrun_delete_workflow` | 列出 / 取得 / 刪除工作流（直問 cypher-executor 真實狀態）。 |
|
||
| `arcrun_search_workflows` | 語意搜尋工作流。 |
|
||
| `arcrun_list_recent_executions` / `arcrun_list_paused_executions` / `arcrun_get_execution_trace` | 查最近 / 暫停中的執行、取單次執行 trace。 |
|
||
|
||
**零件（Component）**
|
||
|
||
| Tool | 一句話 |
|
||
|------|--------|
|
||
| `arcrun_search_components` | 用自然語言語意搜尋零件庫。 |
|
||
| `arcrun_list_components` / `arcrun_get_component` | 列出零件、取單一零件完整合約。 |
|
||
| `arcrun_get_component_guide` | 取得 TinyGo 開發指引（**開發新零件前必先呼叫**）。 |
|
||
| `arcrun_publish_component` | 提交 WASM 零件（見[貢獻新零件](#貢獻新零件)）。 |
|
||
|
||
**Recipe（配方 · 公庫 / 私庫）**
|
||
|
||
| Tool | 一句話 |
|
||
|------|--------|
|
||
| `arcrun_recipe_search` / `arcrun_recipe_list` | 搜尋 / 列出配方。 |
|
||
| `arcrun_recipe_pull` / `arcrun_recipe_push` / `arcrun_recipe_delete` | 拉取 / 推送 / 刪除私庫配方。 |
|
||
| `arcrun_recipe_submit_p` | 投稿配方到公庫。 |
|
||
|
||
**Skill / Example**
|
||
|
||
| Tool | 一句話 |
|
||
|------|--------|
|
||
| `arcrun_list_skills` / `arcrun_get_skill` | 列出 / 取得技能。 |
|
||
| `arcrun_list_examples` / `arcrun_get_example` / `arcrun_search_examples` | 列出 / 取得 / 搜尋範例。 |
|
||
|
||
**Tag**
|
||
|
||
| Tool | 一句話 |
|
||
|------|--------|
|
||
| `arcrun_create_tag` / `arcrun_list_tags` / `arcrun_delete_tag` | 建立 / 列出 / 刪除 tag。 |
|
||
| `arcrun_tag_resource` / `arcrun_untag_resource` | 為工作流或零件加上 / 移除 tag。 |
|
||
|
||
**其他**
|
||
|
||
| Tool | 一句話 |
|
||
|------|--------|
|
||
| `arcrun_whoami` | 回報當前身份 / namespace（與 `acr whoami` 對齊）。 |
|
||
| `arcrun_report_feedback` | 回報使用回饋。 |
|
||
| `arcrun_get_gui_context` | 取 arcrun-gui 畫布上下文。 |
|
||
|
||
### `kbdb_*`（資料層薄殼）
|
||
|
||
類 Supabase 萬用表：AI 只有 template + slot 可用，**不提供建表 / SQL tool**（儲存鐵律）。
|
||
|
||
| Tool | 一句話 |
|
||
|------|--------|
|
||
| `kbdb_search` | 語意搜尋 KBDB 記錄。 |
|
||
| `kbdb_query` | 依條件查詢記錄。 |
|
||
| `kbdb_get_record` | 取單一記錄。 |
|
||
| `kbdb_create_record` | 建立記錄（依 template + slots）。 |
|
||
| `kbdb_list_templates` / `kbdb_create_template` | 列出 / 建立 template。 |
|
||
|
||
---
|
||
|
||
## Inspector 測試界面
|
||
|
||
開啟 `<你的 MCP origin>/mcp/inspector`（官方＝`https://mcp.arcrun.dev/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)**。
|
||
|
||
---
|
||
|
||
## 貢獻新零件
|
||
|
||
想投稿 WASM 零件（TinyGo 開發、本地測試、`arcrun_publish_component` 提交、沙盒驗收）？完整流程見 **[CONTRIBUTING-components.md](./CONTRIBUTING-components.md)**。
|