Arcrun/mcp

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 產生連線設定（推薦）

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）：

{
  "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：

import (
    "os"
    "io"
    "encoding/json"
)

編譯：

tinygo build -o my_component.wasm -target=wasi .

本地測試：

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 的人類操作介面，與 arcrun-mcp 共享同一個 KBDB 狀態：

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

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