# 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)**。