@neurocode-ai/web 1.18.8

package/src/content/docs/zh-cn/mcp-servers.mdx

@@ -0,0 +1,511 @@
+---
+title: MCP 服务器
+description: 添加本地和远程 MCP 工具。
+---
+
+你可以通过 _Model Context Protocol_（MCP）为 OpenCode 添加外部工具。OpenCode 同时支持本地和远程服务器。
+
+添加后，MCP 工具会自动与内置工具一起提供给 LLM 使用。
+
+---
+
+#### 注意事项
+
+使用 MCP 服务器时，它会占用上下文空间。如果你启用了大量工具，上下文消耗会迅速增加。因此，我们建议谨慎选择要使用的 MCP 服务器。
+
+:::tip
+MCP 服务器会占用你的上下文空间，所以请谨慎选择启用哪些服务器。
+:::
+
+某些 MCP 服务器（例如 GitHub MCP 服务器）往往会消耗大量 Token，很容易超出上下文限制。
+
+---
+
+## 启用
+
+你可以在 [OpenCode 配置](https://opencode.ai/docs/config/)的 `mcp` 字段下定义 MCP 服务器。为每个 MCP 指定一个唯一的名称，在提示词中可以通过该名称来引用对应的 MCP。
+
+```jsonc title="opencode.jsonc" {6}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "name-of-mcp-server": {
+      // ...
+      "enabled": true,
+    },
+    "name-of-other-mcp-server": {
+      // ...
+    },
+  },
+}
+```
+
+你也可以将 `enabled` 设置为 `false` 来禁用某个服务器。当你想临时禁用某个服务器而不将其从配置中移除时，这个选项非常有用。
+
+---
+
+### 覆盖远程默认值
+
+组织可以通过其 `.well-known/opencode` 端点提供默认的 MCP 服务器。这些服务器可能默认处于禁用状态，允许用户按需启用。
+
+要启用组织远程配置中的某个服务器，请在本地配置中添加该服务器并设置 `enabled: true`：
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "jira": {
+      "type": "remote",
+      "url": "https://jira.example.com/mcp",
+      "enabled": true
+    }
+  }
+}
+```
+
+本地配置值会覆盖远程默认值。详情请参阅[配置优先级](/docs/config#precedence-order)。
+
+---
+
+## 本地
+
+通过在 MCP 对象中将 `type` 设置为 `"local"` 来添加本地 MCP 服务器。
+
+```jsonc title="opencode.jsonc" {15}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "my-local-mcp-server": {
+      "type": "local",
+      // Or ["bun", "x", "my-mcp-command"]
+      "command": ["npx", "-y", "my-mcp-command"],
+      "enabled": true,
+      "environment": {
+        "MY_ENV_VAR": "my_env_var_value",
+      },
+    },
+  },
+}
+```
+
+`command` 用于指定本地 MCP 服务器的启动命令。你还可以传入一组环境变量。
+
+例如，以下是添加测试用的 [`@modelcontextprotocol/server-everything`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) MCP 服务器的方法。
+
+```jsonc title="opencode.jsonc"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "mcp_everything": {
+      "type": "local",
+      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
+    },
+  },
+}
+```
+
+要使用它，可以在提示词中添加 `use the mcp_everything tool`。
+
+```txt "mcp_everything"
+use the mcp_everything tool to add the number 3 and 4
+```
+
+---
+
+#### 选项
+
+以下是配置本地 MCP 服务器的所有选项。
+
+| 选项          | 类型   | 必填 | 描述                                                              |
+| ------------- | ------ | ---- | ----------------------------------------------------------------- |
+| `type`        | 字符串 | 是   | MCP 服务器连接类型，必须为 `"local"`。                            |
+| `command`     | 数组   | 是   | 运行 MCP 服务器的命令及参数。                                     |
+| `environment` | 对象   |      | 运行服务器时设置的环境变量。                                      |
+| `enabled`     | 布尔值 |      | 启动时启用或禁用该 MCP 服务器。                                   |
+| `timeout`     | 数字   |      | 从 MCP 服务器获取工具的超时时间（毫秒）。默认为 5000（即 5 秒）。 |
+
+---
+
+## 远程
+
+通过将 `type` 设置为 `"remote"` 来添加远程 MCP 服务器。
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "my-remote-mcp": {
+      "type": "remote",
+      "url": "https://my-mcp-server.com",
+      "enabled": true,
+      "headers": {
+        "Authorization": "Bearer MY_API_KEY"
+      }
+    }
+  }
+}
+```
+
+`url` 是远程 MCP 服务器的地址，通过 `headers` 选项可以传入一组请求头。
+
+---
+
+#### 选项
+
+| 选项      | 类型   | 必填 | 描述                                                              |
+| --------- | ------ | ---- | ----------------------------------------------------------------- |
+| `type`    | 字符串 | 是   | MCP 服务器连接类型，必须为 `"remote"`。                           |
+| `url`     | 字符串 | 是   | 远程 MCP 服务器的 URL。                                           |
+| `enabled` | 布尔值 |      | 启动时启用或禁用该 MCP 服务器。                                   |
+| `headers` | 对象   |      | 随请求发送的请求头。                                              |
+| `oauth`   | 对象   |      | OAuth 身份验证配置。详见下方 [OAuth](#oauth) 部分。               |
+| `timeout` | 数字   |      | 从 MCP 服务器获取工具的超时时间（毫秒）。默认为 5000（即 5 秒）。 |
+
+---
+
+## OAuth
+
+OpenCode 会自动处理远程 MCP 服务器的 OAuth 身份验证。当服务器需要身份验证时，OpenCode 将：
+
+1. 检测 401 响应并启动 OAuth 流程
+2. 在服务器支持的情况下使用**动态客户端注册（RFC 7591）**
+3. 安全地存储 Token 以供后续请求使用
+
+---
+
+### 自动认证
+
+对于大多数支持 OAuth 的 MCP 服务器，无需特殊配置。只需配置远程服务器即可：
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "my-oauth-server": {
+      "type": "remote",
+      "url": "https://mcp.example.com/mcp"
+    }
+  }
+}
+```
+
+如果服务器需要身份验证，OpenCode 会在你首次使用时提示你进行认证。你也可以使用 `opencode mcp auth <server-name>` [手动触发认证流程](#authenticating)。
+
+---
+
+### 预注册
+
+如果你已经从 MCP 服务器提供商处获得了客户端凭据，可以直接配置：
+
+```json title="opencode.json" {7-11}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "my-oauth-server": {
+      "type": "remote",
+      "url": "https://mcp.example.com/mcp",
+      "oauth": {
+        "clientId": "{env:MY_MCP_CLIENT_ID}",
+        "clientSecret": "{env:MY_MCP_CLIENT_SECRET}",
+        "scope": "tools:read tools:execute"
+      }
+    }
+  }
+}
+```
+
+---
+
+### 身份验证
+
+你可以手动触发身份验证或管理凭据。
+
+对特定 MCP 服务器进行身份验证：
+
+```bash
+opencode mcp auth my-oauth-server
+```
+
+列出所有 MCP 服务器及其认证状态：
+
+```bash
+opencode mcp list
+```
+
+删除已存储的凭据：
+
+```bash
+opencode mcp logout my-oauth-server
+```
+
+`mcp auth` 命令会打开浏览器进行授权。授权完成后，OpenCode 会将 Token 安全地存储在 `~/.local/share/opencode/mcp-auth.json` 中。
+
+---
+
+#### 禁用 OAuth
+
+如果你想为某个服务器禁用自动 OAuth（例如，该服务器使用 API 密钥而非 OAuth），可以将 `oauth` 设置为 `false`：
+
+```json title="opencode.json" {7}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "my-api-key-server": {
+      "type": "remote",
+      "url": "https://mcp.example.com/mcp",
+      "oauth": false,
+      "headers": {
+        "Authorization": "Bearer {env:MY_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+---
+
+#### OAuth 选项
+
+| 选项           | 类型            | 描述                                                   |
+| -------------- | --------------- | ------------------------------------------------------ |
+| `oauth`        | 对象 \| `false` | OAuth 配置对象，或设为 `false` 以禁用 OAuth 自动检测。 |
+| `clientId`     | 字符串          | OAuth 客户端 ID。如果未提供，将尝试动态客户端注册。    |
+| `clientSecret` | 字符串          | OAuth 客户端密钥（如果授权服务器要求提供）。           |
+| `scope`        | 字符串          | 授权时请求的 OAuth 作用域。                            |
+
+#### 调试
+
+如果远程 MCP 服务器身份验证失败，你可以通过以下方式诊断问题：
+
+```bash
+# 查看所有支持 OAuth 的服务器的认证状态
+opencode mcp auth list
+
+# 调试特定服务器的连接和 OAuth 流程
+opencode mcp debug my-oauth-server
+```
+
+`mcp debug` 命令会显示当前认证状态、测试 HTTP 连接，并尝试执行 OAuth 发现流程。
+
+---
+
+## 管理
+
+你的 MCP 在 OpenCode 中作为工具使用，与内置工具并列。因此，你可以像管理其他工具一样，通过 OpenCode 配置来管理它们。
+
+---
+
+### 全局
+
+你可以全局启用或禁用 MCP 工具。
+
+```json title="opencode.json" {14}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "my-mcp-foo": {
+      "type": "local",
+      "command": ["bun", "x", "my-mcp-command-foo"]
+    },
+    "my-mcp-bar": {
+      "type": "local",
+      "command": ["bun", "x", "my-mcp-command-bar"]
+    }
+  },
+  "tools": {
+    "my-mcp-foo": false
+  }
+}
+```
+
+也可以使用 glob 模式来禁用所有匹配的 MCP。
+
+```json title="opencode.json" {14}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "my-mcp-foo": {
+      "type": "local",
+      "command": ["bun", "x", "my-mcp-command-foo"]
+    },
+    "my-mcp-bar": {
+      "type": "local",
+      "command": ["bun", "x", "my-mcp-command-bar"]
+    }
+  },
+  "tools": {
+    "my-mcp*": false
+  }
+}
+```
+
+这里使用 glob 模式 `my-mcp*` 来禁用所有 MCP。
+
+---
+
+### 按代理配置
+
+如果你有大量 MCP 服务器，可以选择全局禁用它们，然后仅在特定代理中启用。具体做法：
+
+1. 全局禁用该工具。
+2. 在[代理配置](/docs/agents#tools)中，将 MCP 服务器作为工具启用。
+
+```json title="opencode.json" {11, 14-18}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "my-mcp": {
+      "type": "local",
+      "command": ["bun", "x", "my-mcp-command"],
+      "enabled": true
+    }
+  },
+  "tools": {
+    "my-mcp*": false
+  },
+  "agent": {
+    "my-agent": {
+      "tools": {
+        "my-mcp*": true
+      }
+    }
+  }
+}
+```
+
+---
+
+#### Glob 模式
+
+glob 模式使用简单的正则通配符规则：
+
+- `*` 匹配零个或多个任意字符（例如，`"my-mcp*"` 匹配 `my-mcp_search`、`my-mcp_list` 等）
+- `?` 匹配恰好一个字符
+- 其他字符按字面值匹配
+
+:::note
+MCP 服务器工具在注册时以服务器名称作为前缀，因此要禁用某个服务器的所有工具，只需使用：
+
+```
+"mymcpservername_*": false
+```
+
+:::
+
+---
+
+## 示例
+
+以下是一些常见 MCP 服务器的配置示例。如果你想记录其他服务器的用法，欢迎提交 PR。
+
+---
+
+### Sentry
+
+添加 [Sentry MCP 服务器](https://mcp.sentry.dev) 以与你的 Sentry 项目和问题进行交互。
+
+```json title="opencode.json" {4-8}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "sentry": {
+      "type": "remote",
+      "url": "https://mcp.sentry.dev/mcp",
+      "oauth": {}
+    }
+  }
+}
+```
+
+添加配置后，使用 Sentry 进行身份验证：
+
+```bash
+opencode mcp auth sentry
+```
+
+这会打开浏览器窗口完成 OAuth 流程，将 OpenCode 连接到你的 Sentry 账户。
+
+认证完成后，你可以在提示词中使用 Sentry 工具来查询问题、项目和错误数据。
+
+```txt "use sentry"
+Show me the latest unresolved issues in my project. use sentry
+```
+
+---
+
+### Context7
+
+添加 [Context7 MCP 服务器](https://github.com/upstash/context7) 以搜索文档。
+
+```json title="opencode.json" {4-7}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "context7": {
+      "type": "remote",
+      "url": "https://mcp.context7.com/mcp"
+    }
+  }
+}
+```
+
+如果你注册了免费账户，可以使用 API 密钥来获得更高的速率限制。
+
+```json title="opencode.json" {7-9}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "context7": {
+      "type": "remote",
+      "url": "https://mcp.context7.com/mcp",
+      "headers": {
+        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+这里假设你已经设置了 `CONTEXT7_API_KEY` 环境变量。
+
+在提示词中添加 `use context7` 即可使用 Context7 MCP 服务器。
+
+```txt "use context7"
+Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7
+```
+
+你也可以在 [AGENTS.md](/docs/rules/) 中添加类似的规则。
+
+```md title="AGENTS.md"
+When you need to search docs, use `context7` tools.
+```
+
+---
+
+### Grep by Vercel
+
+添加 [Grep by Vercel](https://grep.app) MCP 服务器以搜索 GitHub 上的代码片段。
+
+```json title="opencode.json" {4-7}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "gh_grep": {
+      "type": "remote",
+      "url": "https://mcp.grep.app"
+    }
+  }
+}
+```
+
+由于我们将 MCP 服务器命名为 `gh_grep`，你可以在提示词中添加 `use the gh_grep tool` 来让代理使用它。
+
+```txt "use the gh_grep tool"
+What's the right way to set a custom domain in an SST Astro component? use the gh_grep tool
+```
+
+你也可以在 [AGENTS.md](/docs/rules/) 中添加类似的规则。
+
+```md title="AGENTS.md"
+If you are unsure how to do something, use `gh_grep` to search code examples from GitHub.
+```