wip(docs): i18n (#12681)
This commit is contained in:
Adam
511
packages/web/src/content/docs/zh-cn/mcp-servers.mdx
Normal file
511
packages/web/src/content/docs/zh-cn/mcp-servers.mdx
Normal file
@@ -0,0 +1,511 @@
|
||||
---
|
||||
title: MCP服务器
|
||||
description: 添加本地和远程MCP工具。
|
||||
---
|
||||
|
||||
您可以使用“模型上下文协议”或MCP将外部工具添加到OpenCode。OpenCode支持本地和远程服务器。
|
||||
|
||||
添加使用后，MCP工具将自动与内置工具一起供法学硕士。
|
||||
|
||||
---
|
||||
|
||||
#### 注意事項
|
||||
|
||||
当您使用 MCP 服务器时，它会添加到上下文中。如果您有很多工具，这会很快增加。因此，我们建议您选择使用哪些 MCP 服务器。
|
||||
|
||||
:::提示
|
||||
MCP服务器会添加到您的上下文中，因此您需要小心启用哪些服务器。
|
||||
:::
|
||||
|
||||
某些MCP服务器（例如GitHub MCP服务器）往往会添加大量代币，并且很容易超出上下文限制。
|
||||
|
||||
---
|
||||
|
||||
## 使能夠
|
||||
|
||||
您可以在`mcp`下的[开放代码配置](https://opencode.ai/docs/config/)中定义MCP服务器。为每个MCP添加唯一的名称。当提示LLM时，您可以通过名称引用该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)。
|
||||
|
||||
---
|
||||
|
||||
## 當地的
|
||||
|
||||
使用`type`将本地MCP服务器添加到MCP对像中的`"local"`。
|
||||
|
||||
```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",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
该命令是本地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`设置为ZZPH1Z添加远程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服务器的URL，使用`headers`选项您可以创建标头列表。
|
||||
|
||||
---
|
||||
|
||||
#### 選項
|
||||
|
||||
|選項|類型 |必填 |描述 |
|
||||
| --------- | ------- | -------- | ----------------------------------------------------------------------------------- |
|
||||
| `type` |字符串|是| MCP 服务器连接类型，必须是`"remote"`。
|
||||
| | `url` |字符串|是|远程MCP服务器的URL。
|
||||
| `enabled` | 布尔 | |在启动时启用或禁用MCP 服务器。
|
||||
| `headers` |对象| |随请求一起发送的标头。
|
||||
| `oauth` |对象| | OAuth 身份验证。请参阅下面的配置[开放认证](#oauth) 部分。 |
|
||||
| `timeout` | 数量 | |从MCP服务器获取工具的超时（以毫秒为单位）。默认为5000（5秒）。 |
|
||||
|
||||
---
|
||||
|
||||
## 開放認證
|
||||
|
||||
OpenCode自动处理远程MCP服务器的OAuth身份验证。当服务器需要身份验证时，OpenCode将：
|
||||
|
||||
1. 检测 401 响应并启动 OAuth 流程
|
||||
2. 如果服务器支持，请使用**动态客户端注册 (RFC 7591)**
|
||||
3. 安全地存儲令牌以供將來的請求
|
||||
|
||||
---
|
||||
|
||||
### 自動的
|
||||
|
||||
对于大多数支持 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 令牌安全地存储在 `~/.local/share/opencode/mcp-auth.json` 中。
|
||||
|
||||
---
|
||||
|
||||
#### 禁用 OAuth
|
||||
|
||||
如果要禁用服务器的自动OAuth（例如，对于使用API密钥的服务器），则`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` |对象\|假| OAuth 配置对象，或 `false` 以取消 OAuth 自动检测。
|
||||
| `clientId` |字符串| OAuth 客户端 ID。如果未提供，将尝试动态客户端注册。 |
|
||||
| `clientSecret` |字符串| OAuth客户端密钥（如果需要授权服务器）。
|
||||
| `scope` |字符串|授权期间请求的 OAuth 范围。
|
||||
|
||||
#### 偵錯
|
||||
|
||||
如果远程MCP服务器无法进行身份验证，您可以通过以下方式诊断问题：
|
||||
|
||||
```bash
|
||||
# View auth status for all OAuth-capable servers
|
||||
opencode mcp auth list
|
||||
|
||||
# Debug connection and OAuth flow for a specific server
|
||||
opencode mcp debug my-oauth-server
|
||||
```
|
||||
|
||||
`mcp debug`命令显示当前身份验证状态、测试HTTP连接并尝试OAuth发现流程。
|
||||
|
||||
---
|
||||
|
||||
## 管理
|
||||
|
||||
您的 MCP 可以作为 OpenCode 中的工具以及内置工具使用。，您可以像任何其他工具一样通过 OpenCode 配置来管理它们。
|
||||
|
||||
---
|
||||
|
||||
### 全球的
|
||||
|
||||
這意味著您可以全局啟用或禁用它們。
|
||||
|
||||
```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 模式使用简单的正则表达式 globbing 模式：
|
||||
|
||||
- `*` 匹配零个或多个任意字符（例如，`"my-mcp*"` 匹配 `my-mcp_search`、`my-mcp_list` 等）
|
||||
- `?` 恰好匹配一個字符
|
||||
- 所有其他字符均按字面意思匹配
|
||||
|
||||
:::笔记
|
||||
MCP服务器工具以名称服务器作为出口进行注册，要因此禁用服务器的所有工具，只需使用：
|
||||
|
||||
```
|
||||
"mymcpservername_*": false
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 示例
|
||||
|
||||
以下是一些常见的 MCP 服务器的示例。如果您想记录其他服务器，您可以提交 PR。
|
||||
|
||||
---
|
||||
|
||||
### 哨兵
|
||||
|
||||
添加[哨兵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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 背景7
|
||||
|
||||
添加[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
|
||||
```
|
||||
|
||||
或者，您可以将类似的内容添加到您的[代理.md](/docs/rules/)。
|
||||
|
||||
```md title="AGENTS.md"
|
||||
When you need to search docs, use `context7` tools.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Vercel 的 Grep
|
||||
|
||||
添加 [Vercel 的 Grep](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
|
||||
```
|
||||
|
||||
或者，您可以将类似的内容添加到您的[代理.md](/docs/rules/)。
|
||||
|
||||
```md title="AGENTS.md"
|
||||
If you are unsure how to do something, use `gh_grep` to search code examples from GitHub.
|
||||
```
|
||||
Reference in New Issue
Block a user