Arcrun/mcp/README.md

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，接案切資料夾自動切帳號）：

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：

{
  "mcpServers": {
    "arcrun": {
      "type": "http",
      "url": "https://arcrun-mcp.<你的CF子域>.workers.dev/mcp"
    }
  }
}

官方 SaaS 版本把 url 換成 https://mcp.arcrun.dev/mcp 即可。

也可用 CLI 直接加（HTTP transport）：

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：

{
  "mcpServers": {
    "arcrun": {
      "type": "http",
      "url": "https://arcrun-mcp.<你的CF子域>.workers.dev/mcp"
    }
  }
}

若你的 Claude Desktop 版本尚不支援 remote HTTP MCP，改用 mcp-remote proxy 把 remote MCP 橋成本機 stdio：

{
  "mcpServers": {
    "arcrun": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://arcrun-mcp.<你的CF子域>.workers.dev/mcp"]
    }
  }
}

mcp-remote 會自動處理 OAuth 流程（跳瀏覽器完成 owner-secret 同意頁）。

---

更新（取得新零件 / 新版）

更新流程 ≈ 重跑一次部署，已安裝的自動略過。 self-hosted 用戶要拿新零件（例如新增的 code 零件）或新版引擎時：

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。

---

部署前置（self-hosted 用戶）

自架前，先把 OAuth 需要的 KV 與 Secret 就緒（完整清單見 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 的人類操作介面，與 arcrun-mcp 共享同一個 KBDB 狀態：

• AI 透過 arcrun-mcp 操作（搜尋零件、執行 Workflow）
• 人類透過 arcrun-gui 操作（拖拉畫布、查看零件庫）
• AI 的操作結果即時反映在 arcrun-gui 的畫布上

詳細開發指南請參閱 GUIDE.md。

---

貢獻新零件

想投稿 WASM 零件（TinyGo 開發、本地測試、arcrun_publish_component 提交、沙盒驗收）？完整流程見 CONTRIBUTING-components.md。