feat: 薄殼原則落地 + seed 下沉 API + MCP 進主庫 + 部署一致性

壓測四橫向問題修正（docs 壓測報告）： ① 薄殼原則成鐵律：能力長在 API，CLI/MCP/lib 只暴露 - seed 下沉成 API 行為：cypher-executor POST /init/seed（一次灌 API+auth recipe），種子資料移到 server src/lib/api-recipe-seeds.ts，CLI 改薄殼一次呼叫 - 解除 deployFullyOk 連坐 + init 補 seed auth recipe + update 補 seed/全 KV - registry SUBMISSIONS_KV 補進 REQUIRED_KV_NAMESPACES（修 20/21） ② MCP 統一帳號來源（單一 remote MCP + .env 切 MCP URL） - MCP 從 sibling repo 搬進 arcrun/mcp/（remote Worker，route 改 mcp.arcrun.dev） - config 加 mcp_url 三層解析 + getMcpUrl + DEFAULT_MCP_URL - 新增 acr mcp-setup：依 config 寫專案 .mcp.json（接案切資料夾自動切 MCP） - acr --version 改動態讀 package.json（根治漂移） ③ Deploy 一致性 - tests/release.feature + scripts/check-release.sh - local-deploy.sh：CLI npm publish + auto patch bump + CHANGELOG - local-deploy.sh bash 3.2 相容修正（mapfile / 空陣列 set -u） - builtins/pnpm-lock.yaml ④ README self-hosted 同步現況（移除 R2 殘留、加 flag/env、多帳號） CLI bump → 1.3.0 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-06 15:45:35 +08:00
parent 5f381a44a6
commit 3e65e22775
58 changed files with 8608 additions and 74 deletions
@@ -0,0 +1,200 @@
+# Arcrun MCP Server
+
+> Arcrun 是 **AI 優先（AI-First）** 的工作流自動化平台。
+> 跟 AI 描述你的意圖，Arcrun 幫你把它變成可重複執行、不需要 AI 的自動化工作流。
+
+Arcrun 是反過來的 n8n。n8n 從手寫程式開始，Arcrun 從 AI 描述開始——你說「去抓銀行匯率，用 Telegram 通知我」，AI 把它拆成三元組，Arcrun 查零件庫、組裝、執行。第一次需要 AI，之後自動跑，不再花 Token。
+
+本 repo 是 Arcrun 的 **MCP Server**，讓 Claude Desktop、Cursor 等 AI client 能直接呼叫 Arcrun 的工作流與零件管理功能。
+
+---
+
+## 快速上手
+
+### 取得 API Key
+
+API Key 是由邀請者提供，格式為 `pk_live_...`。
+
+### 連線設定
+
+#### Claude Desktop
+
+編輯 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）：
+
+```json
+{
+  "mcpServers": {
+    "arcrun": {
+      "type": "http",
+      "url": "https://mcp.finally.click/mcp",
+      "headers": {
+        "Authorization": "Bearer pk_live_YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+#### Cursor
+
+在 Cursor 的 MCP 設定中新增：
+
+```json
+{
+  "arcrun": {
+    "type": "http",
+    "url": "https://mcp.finally.click/mcp",
+    "headers": {
+      "Authorization": "Bearer pk_live_YOUR_API_KEY"
+    }
+  }
+}
+```
+
+> 使用 `type: http`（Streamable HTTP transport）。舊版 SSE 格式（`type: sse`）已不支援。
+
+---
+
+## MCP Tools 說明
+
+### 零件開發（WASM）
+
+零件是 Arcrun 的最小執行單元，以 TinyGo 編譯為 `.wasm`，透過 stdin/stdout JSON 通訊。
+
+| Tool | 說明 |
+|------|------|
+| `u6u_get_component_guide` | **開發新零件前必須先呼叫。** 取得 TinyGo 開發指引，包含白名單 import、禁止行為、contract YAML 範例、本地測試指令。 |
+| `u6u_search_components` | 用自然語言語意搜尋零件庫。例如：「查詢 Google Sheets 資料」、「發送 LINE 訊息」。回傳零件清單含 canonical_id、描述、評分。 |
+| `u6u_get_component` | 取得指定零件的完整合約（input_schema、output_schema、gherkin_tests、評分統計等）。 |
+| `u6u_publish_component` | 提交 TinyGo WASM 零件。需提供 `contract`（合約物件）與 `wasm_base64`（編譯後的 .wasm base64）。Registry 自動執行沙盒驗收。 |
+
+### 工作流執行
+
+| Tool | 說明 |
+|------|------|
+| `u6u_execute_workflow` | 在沙盒中執行工作流。輸入 `triplets`（三元組陣列）與 `context`，用於部署前驗證。 |
+| `u6u_deploy_workflow` | 將工作流 YAML 部署至雲端引擎。輸入 `yaml_content`。 |
+
+### 工作流管理
+
+| Tool | 說明 |
+|------|------|
+| `u6u_list_workflows` | 列出已部署的工作流。可傳入選填的 `tag` 參數篩選。 |
+| `u6u_get_workflow` | 取得指定工作流的 metadata。輸入 `workflow_id`。 |
+
+### 零件管理
+
+| Tool | 說明 |
+|------|------|
+| `u6u_list_components` | 列出已發佈的零件。可傳入選填的 `tag` 參數篩選。 |
+
+### Tag 管理
+
+| Tool | 說明 |
+|------|------|
+| `u6u_create_tag` | 建立新 tag。輸入 `name`（必填）與 `description`（選填）。 |
+| `u6u_list_tags` | 列出當前命名空間下所有 tag。 |
+| `u6u_delete_tag` | 刪除指定 tag。輸入 `tag_name`。 |
+| `u6u_tag_resource` | 為工作流或零件加上 tag。輸入 `resource_type`、`resource_id`、`tag_name`。 |
+| `u6u_untag_resource` | 移除工作流或零件的 tag。 |
+
+---
+
+## 零件開發流程（WASM）
+
+Arcrun 的零件是 TinyGo 編譯的 `.wasm`，透過 stdin/stdout JSON 通訊，可在 Cloudflare Workers（Tier 1/2）和 Wazero 邊緣環境（Tier 3）執行。
+
+### 步驟一：取得開發指引
+
+```
+u6u_get_component_guide
+```
+
+指引包含：TinyGo 白名單 import、禁止行為、`component.contract.yaml` 完整範例、本地測試指令。
+
+### 步驟二：搜尋現有零件
+
+```
+u6u_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
+```
+
+### 步驟四：提交零件
+
+```
+u6u_publish_component(
+  contract={...},  // component.contract.yaml 內容
+  wasm_base64="..."  // base64(my_component.wasm)
+)
+```
+
+Registry 自動執行沙盒驗收（體積、syscall 掃描、Gherkin 測試）。
+
+---
+
+## 工作流開發流程
+
+### 步驟一：搜尋零件
+
+```
+u6u_search_components("查詢匯率")
+u6u_search_components("發送 Telegram 訊息")
+```
+
+### 步驟二：沙盒測試
+
+```
+u6u_execute_workflow(
+  triplets=["system >> 查詢匯率 >> get-exchange-rate", ...],
+  context={"currency_pair": "USD/TWD"}
+)
+```
+
+### 步驟三：部署
+
+```
+u6u_deploy_workflow(yaml_content="...")
+```
+
+---
+
+## Inspector 測試界面
+
+開啟 [https://mcp.finally.click/inspector](https://mcp.finally.click/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)**。