docs(mcp): README 改為安裝+使用導向，零件投稿拆成 CONTRIBUTING-components.md

- README 補三種前端安裝（claude.ai connector / Claude Code / Claude Desktop）， MCP URL 以源碼為準 = <origin>/mcp（DEFAULT_MCP_URL、resourceUri）。 - 認證段講 OAuth owner secret 閘 + MCP_STATIC_TOKEN 真祕密路徑，明講明碼-namespace 已移除。 - 工具總覽全用 arcrun_* 現役名（#20 rename）+ kbdb_* 資料層。 - 修正舊 README 兩處連結：.mcp.json url 補 /mcp、inspector 改 /mcp/inspector。 - 零件開發/投稿流程搬到 mcp/CONTRIBUTING-components.md，README 末留連結。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-07 06:39:04 +00:00
parent b13b4dfe49
commit 0617dab70a
2 changed files with 241 additions and 130 deletions
@@ -0,0 +1,71 @@
+# 貢獻新零件（WASM Component Authoring）
+
+> 這份文件寫給**貢獻者**——想開發並投稿新零件到 Arcrun 零件庫的人。
+> 只想「把 MCP 裝來用」的用戶請回 **[README.md](./README.md)**。
+
+零件是 Arcrun 的最小執行單元，以 **TinyGo** 編譯為 `.wasm`，透過 stdin/stdout JSON 通訊，可在 Cloudflare Workers（Tier 1/2）和 Wazero 邊緣環境（Tier 3）執行。提交後 Registry 會自動跑沙盒驗收（體積、syscall 掃描、Gherkin 測試）。
+
+---
+
+## 步驟一：取得開發指引（必做）
+
+```
+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_publish_component` 的沙盒驗收會檢查：
+
+- **體積上限**：超過限制拒收。
+- **syscall 掃描**：只允許白名單 import；踩到禁止行為（網路直連、檔案系統逃逸等）拒收。
+- **Gherkin 測試**：合約裡的 `gherkin_tests` 必須全綠。
+
+投稿前請自行用步驟三的本地測試把 Gherkin 情境跑過一遍，減少來回。
@@ -5,181 +5,215 @@

 Arcrun 是反過來的 n8n。n8n 從手寫程式開始，Arcrun 從 AI 描述開始——你說「去抓銀行匯率，用 Telegram 通知我」，AI 把它拆成三元組，Arcrun 查零件庫、組裝、執行。第一次需要 AI，之後自動跑，不再花 Token。

-本目錄是 Arcrun 的 **MCP Server**（已併入 arcrun 主庫 `arcrun/mcp/`），讓 Claude Code 等 AI client 直接呼叫 Arcrun 的工作流與零件功能。它是「薄殼」——連哪台 cypher / 哪個帳號由設定決定，與 CLI 共用同一份身份來源。
+本目錄是 Arcrun 的 **MCP Server**（已併入 arcrun 主庫 `arcrun/mcp/`），讓 claude.ai、Claude Code、Claude Desktop 等 AI client 直接呼叫 Arcrun 的工作流與零件功能。它是「薄殼」——連哪台 cypher / 哪個帳號由設定決定，與 CLI 共用同一份身份來源。
+
+**這份文件教你怎麼把這個 MCP 裝到你的前端來用。** 想貢獻新零件（投稿 WASM 元件）請見文末的 [貢獻新零件](#貢獻新零件)。

 ---

-## 快速上手
+## MCP 連線 URL（先搞懂這個）

-### 最簡單：用 CLI 產生連線設定（推薦）
+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` 依你的 arcrun 設定（env > 專案 `.arcrun.yaml` > 全域）在當前資料夾寫 `.mcp.json`，
-Claude Code 進此資料夾就連對的 MCP。`acr init` 也會自動順帶跑這步。
+`acr mcp-setup` 依「env > 專案 `.arcrun.yaml` > 全域」解析出的 `mcp_url` 在當前資料夾寫 `.mcp.json`；沒設 `mcp_url` 就 fallback 平台預設 `https://mcp.arcrun.dev/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）：
+**手動：** 在專案根建 `.mcp.json`：

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

-> 平台託管的 MCP 需要 arcrun API Key 授權；自架的 MCP 綁你自己的 cypher。
-> 連線 URL 以 `acr mcp-setup` 產出的為準。
+官方 SaaS 版本把 `url` 換成 `https://mcp.arcrun.dev/mcp` 即可。

-> 使用 `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"
-)
-```
-
-編譯：
+也可用 CLI 直接加（HTTP transport）：

 ```bash
-tinygo build -o my_component.wasm -target=wasi .
+claude mcp add --transport http arcrun https://arcrun-mcp.<你的CF子域>.workers.dev/mcp
 ```

-本地測試：
+### 3. 本機 Claude Desktop

-```bash
-echo '{"input_field":"value"}' | wasmtime my_component.wasm
+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"
+    }
+  }
+}
 ```

-### 步驟四：提交零件
-
-```
-arcrun_publish_component(
-  contract={...},  // component.contract.yaml 內容
-  wasm_base64="..."  // base64(my_component.wasm)
-)
-```
-
-Registry 自動執行沙盒驗收（體積、syscall 掃描、Gherkin 測試）。
+> **若你的 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 同意頁）。

 ---

-## 工作流開發流程
+## 認證

-### 步驟一：搜尋零件
+MCP 打進 arcrun ＝ 觸及該租戶 **KBDB 全量讀寫**，必須有真認證。中介層（`src/middleware/partner-auth.ts`）依序嘗試：

-```
-arcrun_search_components("查詢匯率")
-arcrun_search_components("發送 Telegram 訊息")
-```
+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）才會恢復，正式環境勿用。

-```
-arcrun_validate_yaml(yaml_content="...")
-```
+完整安全模型（PKCE、audience 綁定、KV 儲存鐵律、redirect 白名單）見 **[OAUTH.md](./OAUTH.md)**。

-### 步驟三：部署
+---

-```
-arcrun_push_workflow(api_key="ak_xxx", yaml_content="...")
-```
+## 部署前置（self-hosted 用戶）

-### 步驟四：觸發執行
+自架前，先把 OAuth 需要的 KV 與 Secret 就緒（完整清單見 **[OAUTH.md](./OAUTH.md) §7**，此處只摘要）：

-```
-arcrun_run_workflow(api_key="ak_xxx", name="exchange-rate-notify", input={"currency_pair": "USD/TWD"})
-```
+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 測試界面

-開啟 `https://mcp.arcrun.dev/inspector`（或自架 MCP 的 `/inspector`）即可在瀏覽器中互動式測試所有 MCP tools。
+開啟 `<你的 MCP origin>/mcp/inspector`（官方＝`https://mcp.arcrun.dev/mcp/inspector`）即可在瀏覽器互動式測試所有 MCP tools。

 ---

@@ -192,3 +226,9 @@ arcrun_run_workflow(api_key="ak_xxx", name="exchange-rate-notify", input={"curre
 - AI 的操作結果即時反映在 arcrun-gui 的畫布上

 詳細開發指南請參閱 **[GUIDE.md](./GUIDE.md)**。
+
+---
+
+## 貢獻新零件
+
+想投稿 WASM 零件（TinyGo 開發、本地測試、`arcrun_publish_component` 提交、沙盒驗收）？完整流程見 **[CONTRIBUTING-components.md](./CONTRIBUTING-components.md)**。