@agent-native/core 0.79.2 → 0.79.5

package/docs/content/locales/zh-TW/mcp-clients.md

@@ -0,0 +1,330 @@
+---
+title: "MCP用戶端"
+description: "將您的代理本機應用程式連線到本機 MCP 伺服器（claude-in-chrome、檔案系統、Playwright等），以便代理獲得其工具。"
+---
+
+# MCP用戶端
+
+**此頁面：為您的代理提供更多工具。** 將代理本機應用程式指向 MCP 伺服器（本機或遠端），以便他們的工具顯示在代理聊天中。這是 _client_ 方向，[MCP Protocol](/docs/mcp-protocol) 的鏡像（這使您的應用成為 MCP _server_）。
+
+| 如果你想……                                        | 閱讀                                     |
+| ------------------------------------------------- | ---------------------------------------- |
+| 將外部代理/主機連線到您的應用                     | [External Agents](/docs/external-agents) |
+| 為您的代理提供更多工具（使用其他 MCP 伺服器）     | **此頁面** — MCP 用戶端                  |
+| 建置在 Claude/ChatGPT 中渲染的內聯 UI             | [MCP Apps](/docs/mcp-apps)               |
+| 較低級別的 MCP 伺服器參考（驗證、工具、自訂掛載） | [MCP Protocol](/docs/mcp-protocol)       |
+
+通過一個設定檔案，工作區中的每個代理本機應用都可以存取計算機上的 MCP 伺服器提供的工具：用於瀏覽器自動化的 `claude-in-chrome`、用於讀取檔案的 `@modelcontextprotocol/server-filesystem`、用於瀏覽器測試的 `@playwright/mcp` 以及任何使用 MCP 的其他工具。
+
+您還可以 [connect remote (HTTP) MCP servers at runtime](#remote-via-ui)（個人使用者或整個組織），而無需編輯設定檔案。
+
+每個來源都會解析為一個執行時 **MCP 管理器**，並且它學習的每個工具都會以防碰撞 `mcp__<server-id>__<tool>` 前綴登入到代理的工具註冊表中 - 可通過 `tool-search` 進行意圖搜尋。
+
+```an-diagram title="用戶端方向：多種來源，一種工具註冊表" summary="設定檔案、環境和執行時 UI 全部合並到 MCP 管理器中；它的工具與您的應用程式的操作一起顯示為前綴並且可通過工具搜尋。這是伺服器方向的鏡像。"
+{
+  "html": "<div class=\"mcp-merge\"><div class=\"diagram-col sources\"><div class=\"diagram-box\" data-rough>Workspace <code>mcp.config.json</code><br><small class=\"diagram-muted\">跨應用共用</small></div><div class=\"diagram-box\" data-rough>應用根 <code>mcp.config.json</code><br><small class=\"diagram-muted\">每個應用覆蓋</small></div><div class=\"diagram-box\" data-rough><code>MCP_SERVERS</code> env<br><small class=\"diagram-muted\">CI / 正式環境</small></div><div class=\"diagram-box\" data-rough>通過設定介面遠端設定<br><small class=\"diagram-muted\">personal &amp; org scope</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">MCP 管理器</span><small class=\"diagram-muted\">merge &middot; hot-reload</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col out\"><div class=\"diagram-node\">Agent 工具 registry<br><small class=\"diagram-muted\"><code>mcp__&lt;server-id&gt;__&lt;tool&gt;</code></small></div><div class=\"diagram-node\"><code>tool-search</code><br><small class=\"diagram-muted\">按意圖發現</small></div></div></div>",
+  "css": ".mcp-merge{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.mcp-merge .diagram-col{display:flex;flex-direction:column;gap:8px}.mcp-merge .center{display:flex;flex-direction:column;align-items:center;gap:4px}.mcp-merge .diagram-arrow{font-size:22px;line-height:1}.mcp-merge code{font-size:.85em}"
+}
+```
+
+> 相反的方向 - 使 _your_ 應用程式成為其他主機使用的 MCP 伺服器 - 位於 [MCP Protocol](/docs/mcp-protocol) 和 [External Agents](/docs/external-agents) 中。
+
+## 內置瀏覽器和計算機使用功能 {#built-in-capabilities}
+
+Agent-native 包括常見 stdio MCP 伺服器的本機開發切換。
+預設情況下它們處於關閉狀態，並且只能針對每個使用者或每個組織啟用
+當應用程式在本機執行時。跳過正式環境和託管無伺服器執行時
+即使舊設定行存在，這些內置函數和工作區資源
+樹不會將它們顯示為預設的 `mcp-servers/*.json` 資源。
+
+| 能力             | 伺服器 ID         | 指令                                                                    |
+| ---------------- | ----------------- | ----------------------------------------------------------------------- |
+| Chrome 開發工具  | `chrome-devtools` | `npx -y chrome-devtools-mcp@latest --autoConnect --no-usage-statistics` |
+| Playwright瀏覽器 | `playwright`      | `npx -y @playwright/mcp@latest`                                         |
+| 計算機使用       | `computer-use`    | `npx -y computer-use-mcp@latest`                                        |
+
+一次只能在一個範圍內啟用一種瀏覽器功能。啟用 Chrome DevTools 會停用同一使用者或組織的 Playwright，啟用 Playwright 會停用 Chrome DevTools。
+
+計算機使用僅限 macOS。在其他平台上，它被列為不可用，並且即使舊設定行包含它也會被跳過。
+
+Chrome DevTools 預設使用 `--autoConnect`。它附加到符合條件的正在執行的 Chrome 執行個體；它不會為您建立獨立的瀏覽器設定檔案或登入使用者的常規設定檔案。它需要啟用遠端偵錯的 Chrome 144+。當部署需要特定的偵錯端點時，可以稍後新增手動 `browser-url` 設定。
+
+內置程序保留在框架的 `settings` 表中，位於用於個人切換的 `u:<email>:mcp-builtin-capabilities` 和用於團隊切換的 `o:<orgId>:mcp-builtin-capabilities` 下。啟用後，它們會合並到執行時 MCP 管理器中，其範圍可見性格式與遠端伺服器相同，例如 `mcp__user_<emailhash>_playwright__*` 或 `mcp__org_<orgId>_chrome-devtools__*`。
+
+### 面向使用者的設定說明
+
+對敏感的內置程序使用簡潔、明確的設定副本：
+
+- **Chrome DevTools** 附加到正在執行的 Chrome 偵錯目標。告訴使用者
+  它用於瀏覽器測試和登入驗證，並且它
+  可能需要在工具出現之前啟用 Chrome 遠端偵錯。
+- **Playwright** 啟動一個獨立的瀏覽器。推薦它用於確定性
+  當不需要使用者的實時 Chrome 個人資料時進行品質檢查。
+- **計算機使用**可以操作本機應用程式。預設關閉，解釋一下
+  macOS 螢幕錄製和輔助功能提示，並在拍攝前詢問
+  敏感的 actions，例如購買、財務變化或帳戶更改。
+
+### 內置端點
+
+| 方法 | 路線                         | 目的                                                                  |
+| ---- | ---------------------------- | --------------------------------------------------------------------- |
+| GET  | `/_agent-native/mcp/builtin` | 列出內置功能、啟用的範圍、合並的 ID 和實時狀態。                      |
+| POST | `/_agent-native/mcp/builtin` | 更新範圍。主體：`{ scope, enabledIds }` 或 `{ scope, id, enabled }`。 |
+
+## 新增本機MCP伺服器 {#adding-a-server}
+
+在您的工作區根目錄（或單個應用程式根目錄 - 當兩者都存在時，工作區根目錄獲勝）建立 `mcp.config.json`：
+
+```jsonc
+{
+  "$schema": "https://agent-native.com/schema/mcp.config.json",
+  "servers": {
+    "claude-in-chrome": {
+      "command": "claude-in-chrome-mcp",
+      "args": [],
+      "env": { "LOG_LEVEL": "info" },
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"],
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem@latest",
+        "/Users/me/projects",
+      ],
+    },
+  },
+}
+```
+
+形狀很小：由伺服器 ID 鍵入的 `servers` 對應，其中每個條目都是 stdio 啟動器（`command` + `args` + 可選的 `env`）或遠端 `{ "type": "http", "url", "headers" }` 條目。
+
+```an-annotated-code title="mcp.config.json，帶注釋"
+{
+  "filename": "mcp.config.json",
+  "language": "jsonc",
+  "code": "{\n  \"$schema\": \"https://agent-native.com/schema/mcp.config.json\",\n  \"servers\": {\n    \"claude-in-chrome\": {\n      \"command\": \"claude-in-chrome-mcp\",\n      \"args\": [],\n      \"env\": { \"LOG_LEVEL\": \"info\" }\n    },\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem@latest\", \"/Users/me/projects\"]\n    }\n  }\n}",
+  "annotations": [
+    { "lines": "3", "label": "伺服器ID", "note": "鍵成為工具前綴：該伺服器的工具在代理的註冊表中顯示為 `mcp__claude-in-chrome__*`，因此它們不會與範本的操作發生衝突。" },
+    { "lines": "4-6", "label": "stdio launcher", "note": "`command` + `args` 生成本機二進制檔案。 Stdio 伺服器旨在用於**本機開發**- 它們在邊缘執行時中是無操作的。" },
+    { "lines": "6", "label": "進程環境", "note": "Optional `env` is passed to the spawned process. Keep secrets out of committed config; prefer `MCP_SERVERS` or the settings UI for tokens." }
+  ]
+}
+```
+
+在下一次應用程式啟動時，您將看到：
+
+```
+[mcp-client] loaded config from /path/to/mcp.config.json (3 server(s))
+[mcp-client] connected to claude-in-chrome: 12 tools
+[mcp-client] connected to playwright: 9 tools
+[mcp-client] connected to filesystem: 4 tools
+```
+
+這些工具在代理的工具註冊表中註冊，前綴為 `mcp__<server-id>__<tool-name>`，因此它們不會與範本的 actions 發生衝突。它們也包含在 `tool-search` 中，因此代理可以通過意圖發現新連線的 MCP 功能，而不需要預先提供確切的前綴名稱。
+
+## 設定優先級 {#precedence}
+
+MCP 設定按此順序解析，第一個匹配獲勝：
+
+1. **工作空間根 `mcp.config.json`** — 通過 `package.json` 中的 `agent-native.workspaceCore` 檢測到。在工作區中的每個應用程式之間共用。
+2. **應用程式根 `mcp.config.json`** — 如果您不希望每個應用程式中都提供 MCP 伺服器，則按應用程式覆蓋。
+3. **`MCP_SERVERS` env var** — 具有相同形狀的 JSON 字串，適用於檔案沒有意義的 CI/正式環境。
+
+## 正式環境部署：`MCP_SERVERS` {#mcp-servers-env}
+
+對於正式環境部署，首選遠端 HTTP MCP 伺服器並設定完整設定
+形狀（或內部伺服器對應）作為環境變數：
+
+```bash
+MCP_SERVERS='{"servers":{"zapier":{"type":"http","url":"https://mcp.example.com/mcp","headers":{"Authorization":"Bearer paste-token-value-here"}}}}'
+```
+
+`MCP_SERVERS` 被解析為 JSON，因此 `${...}` 預留位置不會擴充功能
+在字串內。如果您將權杖存儲在另一個秘密中，請先將其展開
+寫入最終的 JSON 值。
+
+Stdio MCP 伺服器生成本機二進制檔案，用於本機開發。
+MCP 工具僅在 Node 執行時激活 - Cloudflare Workers 和其他邊缘
+目標默默地跳過 MCP 並繼續應用程式的其餘部分工作
+通常。
+
+## 自動檢測：`claude-in-chrome` {#autodetect}
+
+如果您**沒有** `mcp.config.json` 並且 `claude-in-chrome-mcp` 二進制檔案位於 `PATH`（或眾所週知的安裝位置 `~/.claude-in-chrome/bin/claude-in-chrome-mcp`）上，則本機代理會將其自動註冊為預設 MCP 伺服器。將 `AGENT_NATIVE_DISABLE_MCP_AUTODETECT=1` 設定為選取退出。
+
+這意味著安裝了 claude-in-chrome 擴充功能的使用者無需更改設定即可獲得對他們開啟的每個代理本機應用程式的瀏覽器控制。
+
+## 通過設定 UI 遠端 MCP 伺服器 {#remote-via-ui}
+
+MCP（模型上下文協議）伺服器為您的代理提供新的能力 - 例如連線到 Zapier、Cloudflare、Composio 或您公司的內部工具。連線後，代理可以像使用內置工具一樣使用這些工具。
+
+### 如何連線遠端MCP伺服器
+
+1. **伺服器名稱** - 供您自己參考的簡短標籤（例如“zapier”、“slack-tools”）。
+2. **URL** — MCP 伺服器提供者為您提供的 HTTPS 端點（例如 `https://mcp.zapier.com/s/abc123/mcp`）。這通常可以在提供者的儀表板或整合檔案中找到。
+3. **描述**（可選）- 關於此伺服器功能的注釋。
+4. **標頭** — 伺服器所需的驗證憑證，每行一個。大多數伺服器需要 `Authorization` 標頭。範例：`Authorization: Bearer sk-your-key-here`。提供者的檔案會告訴您在此處放置什么內容。
+
+點選“**測試**”以在儲存之前驗證連線。如果成功，您將看到可用工具的數量。點選“**連線**”進行新增。
+
+### 個人與組織範圍
+
+支持兩個範圍：
+
+- **個人** — 只有登入使用者才能獲得工具。存儲為使用者範圍設定。
+- **團隊** — 活躍組織中的每個人都可以獲得工具。所有者和管理員可以新增；成員只能看到該列表。存儲為組織範圍設定。
+
+在正在執行的 MCP 管理器中新增和刪除熱重載 — 無需重新啟動進程，也無需重新啟動伺服器。新的 `mcp__<scope>-<name>__*` 工具將在下一條訊息中向客服人員顯示，並且可通過 `tool-search` 進行搜尋。
+
+HTTPS URL 在任何地方都被接受； plain `http://` 在開發過程中僅允許用於 `localhost`。可選的驗證作為不記名權杖在每個請求上通過 `Authorization: Bearer …` 發送。
+
+在底層，這些伺服器以 `u:<email>:mcp-servers-remote`（個人）或 `o:<orgId>:mcp-servers-remote`（團隊）鍵儲存在框架的 `settings` 表中，並在啟動時與 `mcp.config.json` 合並。
+
+### HTTP端點
+
+| 方法   | 路線                                                  | 目的                                                               |
+| ------ | ----------------------------------------------------- | ------------------------------------------------------------------ |
+| GET    | `/_agent-native/mcp/servers`                          | 列出目前使用者的個人+組織伺服器的實時狀態。                        |
+| POST   | `/_agent-native/mcp/servers`                          | 新增伺服器。身體：`{ scope, name, url, headers?, description? }`。 |
+| DELETE | `/_agent-native/mcp/servers/:id?scope=user\|org`      | Remove a server and reconfigure the manager.                       |
+| POST   | `/_agent-native/mcp/servers/:id/test?scope=user\|org` | Dry-run the existing server's connect + list-tools.                |
+| POST   | `/_agent-native/mcp/servers/test`                     | 在持久化之前試執行任意 URL。機身：`{ url, headers? }`。            |
+
+Stdio 伺服器在 Node 執行時之外仍然是無操作的，但遠端 HTTP MCP 伺服器可以在任何具有 `fetch` 的環境中工作 - 包括桌面正式環境版本。
+
+## 通過集線器共用 MCP 伺服器 {#hub}
+
+如果您的工作區執行多個代理本機應用程式（例如調度+郵件+剪輯），您可以將**一個**應用程式設定為中心，並讓其他應用程式自動拉取其組織範圍的MCP伺服器。沒有每個應用程式複製貼上 URL 和不記名權杖。請參閱 [Multi-App Workspace](/docs/multi-app-workspace) 了解使用 Dispatch 工作區 MCP 資源的規範方法。
+
+Dispatch 是傳統的中心 - 它已經跨應用進行協調。
+
+```an-diagram title="中心模型：一個應用程式為組織範圍的 MCP 伺服器提供服務" summary="Dispatch 擁有組織範圍 MCP 伺服器；消費者應用程式將它們拉取並合並為 mcp__hub_<orgId>_<name>__*。僅共用組織範圍的行 - 個人憑證保持不變。"
+{
+  "html": "<div class=\"mcp-hub\"><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">Dispatch hub</span><small class=\"diagram-muted\">組織範圍 MCP 伺服器</small><small class=\"diagram-muted\"><code>GET /mcp/hub/servers</code></small></div><div class=\"diagram-col arrows\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div></div><div class=\"diagram-col consumers\"><div class=\"diagram-box\" data-rough>Mail<br><small class=\"diagram-muted\"><code>mcp__hub_&lt;orgId&gt;_&lt;name&gt;__*</code></small></div><div class=\"diagram-box\" data-rough>Clips<br><small class=\"diagram-muted\">約每 60 秒 pull + merge</small></div></div></div><p class=\"diagram-muted note\">Bearer-gated by <code>AGENT_NATIVE_MCP_HUB_TOKEN</code>. Personal (user-scope) servers are never re-exposed.</p>",
+  "css": ".mcp-hub{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.mcp-hub .center{display:flex;flex-direction:column;align-items:center;gap:4px}.mcp-hub .diagram-col{display:flex;flex-direction:column;gap:10px}.mcp-hub .arrows .diagram-arrow{font-size:22px;line-height:1}.mcp-hub .note{margin:8px 0 0;font-size:.85em}.mcp-hub code{font-size:.85em}"
+}
+```
+
+對於新的工作區設定，首選\*\*在您
+想要工作區 skills 使用相同的全應用與選定應用授權模型，
+說明和參考資源。新增工作區資源：
+
+```json
+{
+  "type": "http",
+  "url": "https://example.com/mcp",
+  "headers": {
+    "Authorization": "Bearer ${keys.MCP_SERVER_TOKEN}"
+  },
+  "description": "Shared MCP 工具s for workspace apps"
+}
+```
+
+將其儲存在 `mcp-servers/<name>.json` 下，型別為 `mcp-server`。所有應用
+資源由每個工作區應用程式載入；選定的資源僅載入
+具有有效調度授權的應用程式。從應用程式解析秘密預留位置
+秘密存儲，因此將原始不記名權杖放入 Dispatch Vault 並引用它們
+使用 `${keys.NAME}`，而不是將它們存儲在資源主體中。
+
+應用程式大約每分鐘刷新一次合並的 MCP 設定，因此是中央資源
+編輯、授予更改和刪除無需部署即可生效。設定
+`AGENT_NATIVE_MCP_CONFIG_REFRESH_MS=0` 停用後台刷新，或
+將其設定為至少 `5000` 毫秒的值以調整間隔。
+
+下面的舊集線器模式對於粗略的“共用每個組織範圍 MCP”仍然有用
+來自 Dispatch 的伺服器”設定以及已使用 MCP 的部署
+將 UI 設定為事實來源。
+
+### 1。在集線器應用程式上啟用集線器服務（調度）
+
+在調度的部署中設定環境變數：
+
+```bash
+AGENT_NATIVE_MCP_HUB_TOKEN=<a-long-random-secret>
+```
+
+Dispatch 現在掛載 `GET /_agent-native/mcp/hub/servers`，它返回存儲在其 `settings` 表中的每個組織範圍 MCP 伺服器，以及完整的 URL + 標頭，並通過權杖進行驗證。
+
+### 2。將消費應用程式指向中心
+
+對每個消費者進行設定（郵件、剪輯等）：
+
+```bash
+AGENT_NATIVE_MCP_HUB_URL=https://dispatch.acme.com
+AGENT_NATIVE_MCP_HUB_TOKEN=<the-same-secret>
+```
+
+啟動時，每個消費者都會拉取集線器的伺服器列表並將其合並到自己的 MCP 管理器中。這些工具對代理來說顯示為 `mcp__hub_<orgId>_<name>__*` — 與消費者自己的本機 `mcp__org_…` 不同，因此不會發生衝突。
+
+### 3。分享什么內容
+
+僅共用**組織範圍**伺服器。使用者範圍（個人）伺服器由新增它們的使用者保留 - 中心絕不會跨應用程式重新公開個人憑證。
+
+集線器回應包括完整的驗證標頭（承載權杖等）。傳輸是 HTTPS，端點需要共用金鑰，並且它僅返回組織範圍行 - 將中心 URL + 權杖視為資料庫憑證。
+
+### 4。熱重載與重啟
+
+本機 UI 通過 `McpClientManager.reconfigure()` 在每個應用程式中新增熱重載 - 無需重新啟動。集線器來源的伺服器由工作區資源路徑使用的相同定期後台刷新（大約 60 秒，可通過 `AGENT_NATIVE_MCP_CONFIG_REFRESH_MS` 調整或停用）來獲取，因此在 Dispatch 中所做的更改會在大約一分鐘內傳播到所有消費者應用程式，而無需重新啟動。此外，消費者應用程式中的任何本機突變都會立即觸發該應用程式的重新設定。
+
+### 端點摘要
+
+| 方法 | 路線                             | 目的                                                                                               |
+| ---- | -------------------------------- | -------------------------------------------------------------------------------------------------- |
+| GET  | `/_agent-native/mcp/hub/servers` | 為所有組織範圍的伺服器提供完整的信用（不記名門控，僅在設定 `AGENT_NATIVE_MCP_HUB_TOKEN` 時安裝）。 |
+| GET  | `/_agent-native/mcp/hub/status`  | 返回設定UI卡的`{ serving, consuming, hubUrl }`。                                                   |
+
+## 狀態路線 {#status-route}
+
+每個應用程式都公開 `GET /_agent-native/mcp/status` 用於工具和入門：
+
+```an-api
+{
+  "method": "GET",
+  "path": "/_agent-native/mcp/status",
+  "summary": "MCP 工具和入門的用戶端狀態",
+  "description": "Reports which configured servers connected, the total live tool count, the merged prefixed tool list, and any per-server connection errors. Use it to build \"detected — your agent can now drive X\" hints or to debug connection problems.",
+  "responses": [
+    {
+      "status": "200",
+      "description": "Configured vs connected servers, tool inventory, and per-server errors.",
+      "example": "{\n  \"configuredServers\": [\"claude-in-chrome\", \"playwright\"],\n  \"connectedServers\": [\"claude-in-chrome\", \"playwright\"],\n  \"totalTools\": 21,\n  \"tools\": [\n    {\n      \"source\": \"claude-in-chrome\",\n      \"name\": \"mcp__claude-in-chrome__navigate\",\n      \"description\": \"Navigate the browser to a URL\"\n    }\n  ],\n  \"errors\": {}\n}"
+    }
+  ]
+}
+```
+
+```json
+{
+  "configuredServers": ["claude-in-chrome", "playwright"],
+  "connectedServers": ["claude-in-chrome", "playwright"],
+  "totalTools": 21,
+  "tools": [
+    {
+      "source": "claude-in-chrome",
+      "name": "mcp__claude-in-chrome__navigate",
+      "description": "Navigate the browser to a URL"
+    }
+  ],
+  "errors": {}
+}
+```
+
+使用它來建置“檢測到 claude-in-chrome - 您的代理現在可以驅動 Chrome”入門提示，或偵錯 MCP 連線問題。
+
+## 故障模式 {#failures}
+
+個別 MCP 伺服器故障永遠不會導致代理關閉：
+
+- 設定錯誤的 `command` → 伺服器被跳過，其錯誤出現在 `errors.<server-id>` 下的 `/mcp/status` 中，而其他所有伺服器繼續工作。
+- `node_modules` 中缺少 MCP SDK → 所有 MCP 功能都會被跳過並出現警告；代理聊天可以使用零 MCP 工具繼續工作。
+- 在邊缘執行時中執行 → MCP 用戶端是無操作的。
+
+代理本機將始終啟動；損壞的 MCP 設定僅意味著工具更少。
+
+## 安全 {#security}
+
+MCP 工具在您的計算機上執行，具有生成的進程具有的任何權限。像對待您願意讓代理驅動的任何其他可執行檔案列表一樣對待 `mcp.config.json`。來自 MCP 伺服器的工具出現在代理的工具使用循環中，就像您範本自己的 actions 一樣，因此請確保您信任您設定的每個伺服器。

package/docs/content/locales/zh-TW/mcp-protocol.md

@@ -0,0 +1,279 @@
+---
+title: "MCP協議"
+description: "將您的代理原生應用公開為遠端 MCP 伺服器，以便 Claude、ChatGPT、Claude 程式碼、光標和其他 AI 工具可以直接調用您應用的 actions。"
+---
+
+# MCP協議
+
+**此頁面：較低級別的 MCP 伺服器參考。** 每個代理本機應用程式如何通過 MCP 公開其 actions — 自動安裝的端點、驗證模式、`tools/call` / `ask-agent` 表面和自訂安裝。當您需要伺服器內部結構時，可以使用它；要連線主機，請從 [External Agents](/docs/external-agents) 開始。
+
+| 如果你想……                                        | 閱讀                                     |
+| ------------------------------------------------- | ---------------------------------------- |
+| 將外部代理/主機連線到您的應用                     | [External Agents](/docs/external-agents) |
+| 為您的代理提供更多工具（使用其他 MCP 伺服器）     | [MCP Clients](/docs/mcp-clients)         |
+| 建置在 Claude/ChatGPT 中渲染的內聯 UI             | [MCP Apps](/docs/mcp-apps)               |
+| 較低級別的 MCP 伺服器參考（驗證、工具、自訂掛載） | **此頁面** — MCP 協議                    |
+
+每個代理本機應用程式都會自動公開遠端 MCP（模型上下文協議）伺服器，因此 Claude、ChatGPT 自訂 MCP 應用程式、Claude Code、Cursor、Codex 和 VS Code GitHub Copilot 等外部 AI 工具可以直接發現並調用應用程式的 actions - 無需額外程式碼需要。如果您的目標是將其中一台主機連線到託管應用程式，[External Agents](/docs/external-agents) 涵蓋建議的單個調度連線器、每個應用程式 URL、OAuth、MCP 應用內聯 UI 和深層連結。此頁面紀錄了其下方的內容。
+
+## 概述 {#overview}
+
+MCP 是用於將 AI 工具連線到外部功能的標準協議。當您部署代理本機應用程式時，它會自動安裝 MCP 端點以及現有的 A2A 端點。任何與 MCP 兼容的用戶端都可以連線並使用您應用的工具。
+
+關鍵概念：
+
+- **自動安裝** — 每個應用都免費獲得 `/_agent-native/mcp`，無需設定
+- **Streamable HTTP** — 在標準 HTTP (POST + SSE) 上使用現代 MCP 傳輸
+- **相同的 actions** — 為代理聊天和 A2A 提供支持的完全相同的操作註冊表
+- **`ask-agent` 工具** — 一種元工具，可委托給完整代理循環來執行複雜工作
+- **MCP 應用程式** — actions 可以通過官方 `io.modelcontextprotocol/ui` 擴充功能來宣傳互動式 UI 資源
+- **標準遠端 MCP OAuth** — OAuth 2.1 發現、動態用戶端註冊、授權程式碼 + PKCE、刷新權杖輪換
+- **承載驗證回退** - 對於無法執行 OAuth 的用戶端使用 `ACCESS_TOKEN`、`ACCESS_TOKENS` 或 connect-minted JWT
+
+```an-diagram title="您的應用程式作為 MCP 伺服器" summary="外部主機通過 Streamable HTTP 連線。每個動作都是一個工具； Ask-agent 委托給完整的代理循環。"
+{
+  "html": "<div class=\"diagram-mcp\"><div class=\"diagram-col\"><div class=\"diagram-node\">Claude</div><div class=\"diagram-node\">ChatGPT</div><div class=\"diagram-node\">Cursor · Codex</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel\"><span class=\"diagram-pill accent\">POST /_agent-native/mcp</span><small class=\"diagram-muted\">Streamable HTTP</small><small class=\"diagram-muted\">initialize &rarr; tools/list &rarr; tools/call</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\" data-rough>each action<br><small class=\"diagram-muted\">= one tool</small></div><div class=\"diagram-box\" data-rough>ask-agent<br><small class=\"diagram-muted\">&rarr; full agent loop</small></div></div></div>",
+  "css": ".diagram-mcp{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.diagram-mcp .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-mcp .diagram-panel{display:flex;flex-direction:column;align-items:center;gap:4px}.diagram-mcp .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+## MCP vs A2A {#mcp-vs-a2a}
+
+兩種協議都是自動安裝的。使用適合您的用例的選項：
+
+|              | MCP                                                                 | A2A                                    |
+| ------------ | ------------------------------------------------------------------- | -------------------------------------- |
+| **最適合**   | 調用您的應用的外部工具                                              | 代理間通信                             |
+| **協議**     | MCP 可流式傳輸 HTTP                                                 | JSON-RPC 2.0                           |
+| **工具發現** | `tools/list`                                                        | `/.well-known/agent-card.json`的代理卡 |
+| **端點**     | `/_agent-native/mcp`                                                | `/_agent-native/a2a`                   |
+| **支持**     | Claude、ChatGPT、Claude Code、Cursor、Codex、Cowork 和其他 MCP 主機 | 其他代理本機應用                       |
+| **執行**     | 直接工具調用（無需額外的LLM）                                       | 完整代理循環（LLM 推理）               |
+
+您還可以使用 `ask-agent` MCP 工具來獲得兩全其美的效果 - 從 Claude 程式碼中調用它，並讓您的應用的代理通過複雜的工作進行推理。
+
+## 手動 MCP 用戶端設定 {#manual-config}
+
+對於建議的單指令設定，請使用 [External Agents](/docs/external-agents)。如果您為支持 OAuth 的用戶端手寫 MCP 設定，請將您的應用新增為不帶靜態標頭的遠端 MCP 伺服器：
+
+```bash
+claude mcp add --transport http mail https://mail.example.com/_agent-native/mcp
+```
+
+或者在 `.mcp.json`（專案範圍）或 `~/.claude.json`（使用者範圍）中手動寫入條目：
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "mail": {
+      "type": "http",
+      "url": "https://mail.example.com/_agent-native/mcp",
+    },
+  },
+}
+```
+
+然後在Claude程式碼中執行`/mcp`並選取**驗證**。對於無法執行遠端 MCP OAuth 的用戶端，請使用“連線”頁面或帶有 `headers.Authorization` 的靜態承載權杖條目。經過驗證後，您可以自然地使用應用程式的工具：
+
+```
+> draft an email to John about the Q3 report
+
+Claude Code calls: draft-email(to: "john@example.com", subject: "Q3 Report", body: "...")
+```
+
+## 從其他MCP用戶端連線 {#other-clients}
+
+任何支持 Streamable HTTP 傳輸的 MCP 用戶端都可以連線。端點是：
+
+```
+POST https://your-app.example.com/_agent-native/mcp
+```
+
+伺服器支持標準MCP握手：`initialize`→`initialized`→`tools/list`→`tools/call`。
+
+```an-api title="MCP端點" summary="每個代理本機應用程式都會公開自動安裝的 Streamable HTTP 端點。"
+{
+  "method": "POST",
+  "path": "/_agent-native/mcp",
+  "summary": "MCP 可流式 HTTP 端點",
+  "description": "Auto-mounted on every app. Speaks the standard MCP handshake (`initialize` → `initialized` → `tools/list` → `tools/call`) plus `resources/list`, `resources/templates/list`, and `resources/read` when an action declares `mcpApp`. Each action maps to one tool; `ask-agent` delegates to the full agent loop.",
+  "auth": "Standard remote MCP OAuth (Bearer access token), connect-minted JWT, or static ACCESS_TOKEN/ACCESS_TOKENS",
+  "params": [
+    { "name": "Authorization", "in": "header", "type": "string", "required": false, "description": "Bearer access token. Required except for loopback local-dev probes." },
+    { "name": "method", "in": "body", "type": "string", "required": true, "description": "MCP method, e.g. initialize, tools/list, tools/call." }
+  ],
+  "request": {
+    "contentType": "application/json",
+    "example": "{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"ask-agent\",\n    \"arguments\": { \"message\": \"Summarize Q3 signups by source\" }\n  }\n}"
+  },
+  "responses": [
+    { "status": "200", "description": "MCP result (POST + SSE)." },
+    { "status": "401", "description": "Unauthenticated — responds with a WWW-Authenticate header pointing at OAuth discovery." }
+  ]
+}
+```
+
+如果操作聲明 `mcpApp`，伺服器還會通告官方 MCP 應用擴充功能 (`io.modelcontextprotocol/ui`)，並支持應用資源的 `resources/list`、`resources/templates/list` 和 `resources/read`。渲染 MCP 應用程式的主機可以內聯顯示 UI；不這樣做的主機仍然可以調用該工具並使用深層連結後備。產品 UI 應使用 `embedApp()`，因此內聯表面是真正的 React 應用程式路由，或者呈現共用 React 元件（例如 Analytics 圖表）的集中路由，而不是單獨的普通 HTML 實現。伺服器發出標準 MCP 應用元資料和 ChatGPT 應用 SDK 兼容性元資料，以便支持應用程式的主機可以找到相同的 `ui://` 資源。目前官方擴充功能矩陣包括Claude、Claude Desktop、VS Code GitHub Copilot、Goose、Postman、MCPJam、ChatGPT、Cursor；主機支持因版本和計畫而異，因此請使用 [External Agents MCP Apps notes](/docs/external-agents#mcp-apps-compatibility) 來獲取面向使用者的指導。
+
+### MCP 應用嵌入橋 {#mcp-app-embed-bridge}
+
+`embedApp()` 是低級 URL-first MCP 應用程式助手：它啟動簽名的應用程式
+通過移植 (Claude)、受控幀 (ChatGPT) 或直接進行內聯路由
+導覽，通過 `ui/*` JSON-RPC 橋（以及
+`agentNative.mcpHost.*` postMessage 中繼用於受控幀路徑），以及
+限制資源外殼高度，因此完整應用程式路由不會呈現為
+超大的聊天神器。
+
+有關完整嵌入橋的詳細資訊，請參閱 [MCP Apps](/docs/mcp-apps#mcp-app-bridge) - 移植與受控框架、`ui/*` 和 postMessage 表、`create_embed_session` / `embedStartUrl`、CSP 和域規則、擴充功能 `srcDoc` 嵌入、高度限制和主橋用戶端 API。
+
+## 工具 {#tools}
+
+每個調用者預設都會獲得一個**緊湊目錄**（範本聲明的應用程式 actions 加上跨應用程式內置），完整的操作介面僅在明確選取加入時提供，並且 `tool-search` 始終可用於到達其餘部分。完整解釋請參見 [External Agents → Catalog tiers](/docs/external-agents#catalog-tiers)。
+
+每個操作都直接對應到一個 MCP 工具：
+
+| 操作屬性           | MCP工具屬性   |
+| ------------------ | ------------- |
+| `tool.description` | `description` |
+| `tool.parameters`  | `inputSchema` |
+| 操作名稱           | 工具名稱      |
+
+當存在`mcpApp`時，工具條目還包括`_meta.ui.resourceUri`、`_meta["ui/resourceUri"]`和`_meta["openai/outputTemplate"]`，並且相應的`ui://`資源返回為`text/html;profile=mcp-app`。
+
+### `ask-agent` 工具 {#ask-agent}
+
+除了單獨的操作工具外，每個 MCP 伺服器還包含一個 `ask-agent` 元工具。這會向應用程式的 AI 代理發送一條自然語言訊息並返回回應。
+
+使用 `ask-agent` 執行複雜工作，受益於代理的推理和上下文：
+
+```json
+{
+  "name": "ask-agent",
+  "arguments": {
+    "message": "Draft a follow-up email to the Q3 planning thread with John, summarizing the action items we discussed"
+  }
+}
+```
+
+代理執行與互動式聊天相同的循環 - 它可以調用多個工具、推理上下文並生成深思熟慮的回應。
+
+## 驗證 {#authentication}
+
+MCP 端點支持標準遠端 MCP OAuth 以及現有的不記名權杖後備：
+
+| 模式                 | 它是如何工作的                                                                                   |
+| -------------------- | ------------------------------------------------------------------------------------------------ |
+| 標準MCP OAuth        | 用戶端從`WWW-Authenticate`發現驗證，註冊，執行PKCE，並發送`Authorization: Bearer <access-token>` |
+| 連線鑄造JWT          | `npx @agent-native/core@latest connect` / Connect 頁面鑄造一個每使用者、可撤銷的 JWT             |
+| `ACCESS_TOKEN`       | 靜態不記名權杖 - 用戶端發送 `Authorization: Bearer <token>`                                      |
+| `ACCESS_TOKENS`      | 以逗號分隔的有效靜態不記名權杖列表                                                               |
+| `A2A_SECRET`         | 基於 JWT 的驗證 - 權杖通過加密方式進行驗證                                                       |
+| _（未設定，僅環回）_ | 本機開發探針不需要驗證                                                                           |
+
+對於支持 OAuth 的 MCP 主機，設定不帶靜態標頭的遠端伺服器 URL：
+
+```bash
+claude mcp add --transport http agent-native https://dispatch.agent-native.com/_agent-native/mcp
+```
+
+第一個未經驗證的 MCP 請求收到：
+
+```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer resource_metadata="https://dispatch.agent-native.com/.well-known/oauth-protected-resource", scope="mcp:read mcp:write mcp:apps"
+```
+
+發現端點：
+
+| 端點                                      | 目的                      |
+| ----------------------------------------- | ------------------------- |
+| `/.well-known/oauth-protected-resource`   | RFC 9728 受保護資源元資料 |
+| `/.well-known/oauth-authorization-server` | OAuth 授權伺服器元資料    |
+| `/_agent-native/mcp/oauth/register`       | 動態公開用戶端註冊        |
+| `/_agent-native/mcp/oauth/authorize`      | 瀏覽器授權+同意           |
+| `/_agent-native/mcp/oauth/token`          | 授權程式碼和刷新權杖授予  |
+
+```an-diagram title="OAuth 發現流程" summary="401 啟動發現、註冊和 PKCE 授權 → 權杖交換。不記名權杖是受受眾限制和範圍的。"
+{
+  "html": "<div class=\"diagram-oauth\"><div class=\"diagram-box\" data-rough>first request<br><small class=\"diagram-muted\">no token</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill warn\">401 · WWW-Authenticate</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel\"><span class=\"diagram-pill\">/.well-known/oauth-protected-resource</span><span class=\"diagram-pill\">/.well-known/oauth-authorization-server</span><small class=\"diagram-muted\">discover</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-pill\">register</div><div class=\"diagram-pill\">authorize (PKCE)</div><div class=\"diagram-pill\">token</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Bearer access token<br><small class=\"diagram-muted\">綁定 audience · mcp:read / write / apps</small></div></div>",
+  "css": ".diagram-oauth{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-oauth .diagram-panel{display:flex;flex-direction:column;align-items:center;gap:4px}.diagram-oauth .diagram-col{display:flex;flex-direction:column;gap:6px}.diagram-oauth .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+存取權杖是經過簽名的 JWT，其受眾是確切的 MCP 資源 URL。伺服器僅接受為其自身頒發的權杖，並在列出/調用工具之前應用範圍：
+
+| 範圍        | 允許                              |
+| ----------- | --------------------------------- |
+| `mcp:read`  | 唯讀 actions                      |
+| `mcp:write` | 突變 actions 和 `ask-agent`       |
+| `mcp:apps`  | MCP 應用資源（`ui://` HTML 資源） |
+
+刷新權杖僅存儲為哈希值，並在每次刷新時輪換。預設情況下，`npx @agent-native/core@latest connect` 為 Claude 程式碼用戶端寫入僅 URL 的 OAuth 條目；保留連線頁面、`npx @agent-native/core@latest connect --token <token>` 和靜態承載設定以用於本機 stdio 代理、舊用戶端和緊急/偵錯流程。
+
+## 自訂 MCP 設定 {#custom-setup}
+
+MCP 伺服器由代理聊天外掛自動安裝。對於大多數應用程式，無需設定。如果您需要自訂行為，您可以在伺服器外掛中手動安裝它：
+
+```ts
+// server/plugins/mcp.ts
+import { mountMCP } from "@agent-native/core/mcp";
+import { autoDiscoverActions } from "@agent-native/core/server";
+
+export default defineNitroPlugin(async (nitro) => {
+  const actions = await autoDiscoverActions(import.meta.url);
+
+  mountMCP(nitro, {
+    name: "My App",
+    description: "Custom MCP server",
+    actions,
+    // Optional: provide ask-agent handler
+    askAgent: async (message) => {
+      // Your custom agent logic
+      return "Response";
+    },
+    // Optional: override the route prefix (default "/_agent-native")
+    // routePrefix: "/_agent-native",
+  });
+});
+```
+
+## 範例：來自 Claude 程式碼的分析 {#example}
+
+您在 `analytics.example.com` 部署了分析應用程式。來自Claude程式碼：
+
+```bash
+claude mcp add --transport http analytics https://analytics.example.com/_agent-native/mcp
+```
+
+或者在`.mcp.json`中手動新增：
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "analytics": {
+      "type": "http",
+      "url": "https://analytics.example.com/_agent-native/mcp",
+    },
+  },
+}
+```
+
+現在在 Claude 程式碼中：
+
+```
+> How many signups did we get last week?
+
+Claude Code calls: run-query(sql: "SELECT count(*) FROM signups WHERE created_at > now() - interval '7 days'")
+→ "1,247 signups last week"
+```
+
+對於更複雜的分析：
+
+```
+> Ask the analytics agent to prepare a full breakdown of Q3 signups by source, with trends
+
+Claude Code calls: ask-agent(message: "Prepare a full breakdown of Q3 signups by source, with trends")
+→ The analytics agent runs multiple queries, reasons about the data, and returns a formatted report
+```