monadical/opencode
14
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

docs: improve zh-cn and zh-tw documentation translations (#13942)

Browse Source
This commit is contained in:
chenmi
2026-02-17 20:06:39 +08:00
committed by GitHub
parent 8d0a303af4
commit 4fd3141ab5
68 changed files with 4624 additions and 4518 deletions
Download Patch File Download Diff File Expand all files Collapse all files

168
packages/web/src/content/docs/zh-tw/mcp-servers.mdx
View File

@@ -1,29 +1,29 @@
---
title: MCP 伺服器
description: 添加本地和遠端 MCP 工具。
description: 新增本地和遠端 MCP 工具。
---
您可以使用「模型上下文協定」或 MCP 將外部工具添加到 opencode。 opencode 支援本地和遠端伺服器。
您可以透過 _Model Context Protocol_（MCP）為 OpenCode 新增外部工具。OpenCode 同時支援本地和遠端伺服器。
添加後，MCP 工具將自動與內建工具一起供 LLM 使用。
新增後，MCP 工具會自動與內建工具一起提供給 LLM 使用。
---
#### 注意事項
當您使用 MCP 伺服器時，它會添加到上下文中。如果您有很多工具，這會很快增加。因此，我們建議您謹慎選擇使用哪些 MCP 伺服器。
使用 MCP 伺服器時，它會佔用上下文空間。如果您啟用了大量工具，上下文消耗會迅速增加。因此，我們建議謹慎選擇要使用的 MCP 伺服器。
:::tip
MCP 伺服器會添加到您的上下文中，因此您需要小心啟用哪些伺服器。
MCP 伺服器會佔用您的上下文空間，所以請謹慎選擇啟用哪些伺服器。
:::
某些 MCP 伺服器（例如 GitHub MCP 伺服器）往往會添加大量 tokens，並且很容易超出上下文限制。
某些 MCP 伺服器（例如 GitHub MCP 伺服器）往往會消耗大量 Token，很容易超出上下文限制。
---
## 啟用
您可以在 `mcp` 下的 [opencode 設定](https://opencode.ai/docs/config/) 中定義 MCP 伺服器。為每個 MCP 添加唯一的名稱。當提示 LLM 時，您可以透過名稱引用該 MCP。
您可以在 [OpenCode 設定](https://opencode.ai/docs/config/)的 `mcp` 欄位下定義 MCP 伺服器。為每個 MCP 指定一個唯一的名稱，在提示詞中可以透過該名稱來參照對應的 MCP。
```jsonc title="opencode.jsonc" {6}
{
@@ -40,15 +40,15 @@ MCP 伺服器會添加到您的上下文中，因此您需要小心啟用哪些
}
```
您還可以透過將 `enabled` 設定為 `false` 來禁用伺服器。如果您想暫時禁用伺服器而不將其從設定中刪除，這非常有用。
您也可以將 `enabled` 設定為 `false` 來停用某個伺服器。當您想臨時停用某個伺服器而不將其從設定中移除時，這個選項非常有用。
---
### 覆寫遠端預設值
組織可以透過其 `.well-known/opencode` 端點提供預設 MCP 伺服器。這些伺服器可能預設被禁用，允許使用者選擇他們需要的伺服器。
組織可以透過其 `.well-known/opencode` 端點提供預設的 MCP 伺服器。這些伺服器可能預設處於停用狀態，允許使用者按需啟用。
要從組織的遠端設定啟用特定伺服器，請使用 `enabled: true` 將其添加到本地設定：
要啟用組織遠端設定中的某個伺服器，請在本地設定中新增該伺服器並設定 `enabled: true`：
```json title="opencode.json"
{
@@ -63,13 +63,13 @@ MCP 伺服器會添加到您的上下文中，因此您需要小心啟用哪些
}
```
您的本地設定值會覆寫遠端預設值。有關更多詳細資訊，請參閱 [設定優先級](/docs/config#precedence-order)。
本地設定值會覆寫遠端預設值。詳情請參閱[設定優先順序](/docs/config#precedence-order)。
---
## 本地
使用 `type` 將本地 MCP 伺服器添加到 MCP 物件中的 `"local"`。
透過在 MCP 物件中將 `type` 設定為 `"local"` 來新增本地 MCP 伺服器。
```jsonc title="opencode.jsonc" {15}
{
@@ -88,9 +88,9 @@ MCP 伺服器會添加到您的上下文中，因此您需要小心啟用哪些
}
```
該指令是本地 MCP 伺服器的啟動方式。您還可以傳入環境變數列表。
`command` 用於指定本地 MCP 伺服器的啟動指令。您還可以傳入一組環境變數。
例如，以下是添加測試 [`@modelcontextprotocol/server-everything`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) MCP 伺服器的方法。
例如，以下是新增測試用的 [`@modelcontextprotocol/server-everything`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) MCP 伺服器的方法。
```jsonc title="opencode.jsonc"
{
@@ -104,7 +104,7 @@ MCP 伺服器會添加到您的上下文中，因此您需要小心啟用哪些
}
```
要使用它，我可以將 `use the mcp_everything tool` 添加到我的提示中。
要使用它，可以在提示詞中新增 `use the mcp_everything tool`。
```txt "mcp_everything"
use the mcp_everything tool to add the number 3 and 4
@@ -116,19 +116,19 @@ 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` | 字串 | 是 | MCP 伺服器連線類型，必須為 `"local"`。 |
| `command` | 陣列 | 是 | 執行 MCP 伺服器的指令及參數。 |
| `environment` | 物件 | | 執行伺服器時設定的環境變數。 |
| `enabled` | 布林值 | | 啟動時啟用或停用該 MCP 伺服器。 |
| `timeout` | 數字 | | 從 MCP 伺服器取得工具的逾時時間（毫秒）。預設為 5000（即 5 秒）。 |
---
## 遠端
透過將 `type` 設定為 `"remote"` 添加遠端 MCP 伺服器。
透過將 `type` 設定為 `"remote"` 來新增遠端 MCP 伺服器。
```json title="opencode.json"
{
@@ -146,36 +146,36 @@ use the mcp_everything tool to add the number 3 and 4
}
```
`url` 是遠端 MCP 伺服器的 URL，使用 `headers` 選項您可以傳入標頭列表。
`url` 是遠端 MCP 伺服器的位址，透過 `headers` 選項可以傳入一組請求標頭。
---
#### 選項
| 選項 | 類型 | 必填 | 描述 |
| --------- | ------ | ---- | ------------------------------------------------------------------ |
| `type` | 字串 | 是 | MCP 伺服器連接類型，必須是 `"remote"`。 |
| `url` | 字串 | 是 | 遠端 MCP 伺服器的 URL。 |
| `enabled` | 布林值 | | 在啟動時啟用或禁用 MCP 伺服器。 |
| `headers` | 物件 | | 隨請求一起發送的標頭。 |
| `oauth` | 物件 | | OAuth 身分驗證設定。請參閱下面的 [OAuth](#oauth) 部分。 |
| `timeout` | 數量 | | 從 MCP 伺服器獲取工具的超時（以毫秒為單位）。預設為 5000（5 秒）。 |
| 選項 | 類型 | 必填 | 描述 |
| --------- | ------ | ---- | ----------------------------------------------------------------- |
| `type` | 字串 | 是 | MCP 伺服器連線類型，必須為 `"remote"`。 |
| `url` | 字串 | 是 | 遠端 MCP 伺服器的 URL。 |
| `enabled` | 布林值 | | 啟動時啟用或停用該 MCP 伺服器。 |
| `headers` | 物件 | | 隨請求傳送的請求標頭。 |
| `oauth` | 物件 | | OAuth 身分驗證設定。詳見下方 [OAuth](#oauth) 部分。 |
| `timeout` | 數字 | | 從 MCP 伺服器取得工具的逾時時間（毫秒）。預設為 5000（即 5 秒）。 |
---
## OAuth
opencode 自動處理遠端 MCP 伺服器的 OAuth 身分驗證。當伺服器需要身分驗證時，opencode 將：
OpenCode 會自動處理遠端 MCP 伺服器的 OAuth 身分驗證。當伺服器需要身分驗證時，OpenCode 將：
1. 檢測 401 回應並啟動 OAuth 流程
2. 如果伺服器支援，請使用**動態客戶端註冊 (RFC 7591)**
3. 安全地儲存權杖以供將來的請求
1. 偵測 401 回應並啟動 OAuth 流程
2. 在伺服器支援的情況下使用**動態用戶端註冊（RFC 7591）**
3. 安全地儲存 Token 以供後續請求使用
---
### 自動
### 自動認證
對於大多數支援 OAuth 的 MCP 伺服器，不需要特殊設定。只需設定遠端伺服器：
對於大多數支援 OAuth 的 MCP 伺服器，無需特殊設定。只需設定遠端伺服器即可：
```json title="opencode.json"
{
@@ -189,13 +189,13 @@ opencode 自動處理遠端 MCP 伺服器的 OAuth 身分驗證。當伺服器
}
```
如果伺服器需要身分驗證，opencode 將在您第一次嘗試使用它時提示您進行身分驗證。如果沒有，您可以使用 `opencode mcp auth <server-name>` [手動觸發流程](#authenticating)。
如果伺服器需要身分驗證，OpenCode 會在您首次使用時提示您進行認證。您也可以使用 `opencode mcp auth <server-name>` [手動觸發認證流程](#authenticating)。
---
### 預先註冊
如果您有來自 MCP 伺服器供應商的客戶端憑證，則可以設定它們：
如果您已經從 MCP 伺服器提供商處取得了用戶端憑證，可以直接設定：
```json title="opencode.json" {7-11}
{
@@ -216,35 +216,35 @@ opencode 自動處理遠端 MCP 伺服器的 OAuth 身分驗證。當伺服器
---
### 進行身分驗證
### 身分驗證
您可以手動觸發身分驗證或管理憑證。
使用特定 MCP 伺服器進行身分驗證：
對特定 MCP 伺服器進行身分驗證：
```bash
opencode mcp auth my-oauth-server
```
列出所有 MCP 伺服器及其身分驗證狀態：
列出所有 MCP 伺服器及其認證狀態：
```bash
opencode mcp list
```
刪除儲存的憑證：
刪除已儲存的憑證：
```bash
opencode mcp logout my-oauth-server
```
`mcp auth` 指令將打開您的瀏覽器進行授權。授權後，opencode 會將權杖安全地儲存在 `~/.local/share/opencode/mcp-auth.json` 中。
`mcp auth` 指令會開啟瀏覽器進行授權。授權完成後，OpenCode 會將 Token 安全地儲存在 `~/.local/share/opencode/mcp-auth.json` 中。
---
#### 禁用 OAuth
#### 停用 OAuth
如果要禁用伺服器的自動 OAuth（例如，對於使用 API 金鑰的伺服器），請將 `oauth` 設定為 `false`：
如果您想為某個伺服器停用自動 OAuth（例如，該伺服器使用 API 金鑰而非 OAuth），可以將 `oauth` 設定為 `false`：
```json title="opencode.json" {7}
{
@@ -266,38 +266,38 @@ opencode mcp logout my-oauth-server
#### OAuth 選項
| 選項 | 類型 | 描述 |
| -------------- | --------------- | --------------------------------------------------- |
| `oauth` | Object \| false | OAuth 設定物件，或 `false` 以禁用 OAuth 自動檢測。 |
| `clientId` | String | OAuth 客戶端 ID。如果未提供，將嘗試動態客戶端註冊。 |
| `clientSecret` | String | OAuth 客戶端密鑰（如果授權伺服器需要）。 |
| `scope` | String | 授權期間請求的 OAuth 範圍。 |
| 選項 | 類型 | 描述 |
| -------------- | --------------- | ------------------------------------------------------ |
| `oauth` | 物件 \| `false` | OAuth 設定物件，或設為 `false` 以停用 OAuth 自動偵測。 |
| `clientId` | 字串 | OAuth 用戶端 ID。如果未提供，將嘗試動態用戶端註冊。 |
| `clientSecret` | 字串 | OAuth 用戶端密鑰（如果授權伺服器要求提供）。 |
| `scope` | 字串 | 授權時請求的 OAuth 作用域。 |
#### 偵錯
如果遠端 MCP 伺服器無法進行身分驗證，您可以透過以下方式診斷問題：
如果遠端 MCP 伺服器身分驗證失敗，您可以透過以下方式診斷問題：
```bash
# View auth status for all OAuth-capable servers
# 查看所有支援 OAuth 的伺服器的認證狀態
opencode mcp auth list
# Debug connection and OAuth flow for a specific server
# 偵錯特定伺服器的連線和 OAuth 流程
opencode mcp debug my-oauth-server
```
`mcp debug` 指令顯示當前身分驗證狀態、測試 HTTP 連接並嘗試 OAuth 發現流程。
`mcp debug` 指令會顯示當前認證狀態、測試 HTTP 連線，並嘗試執行 OAuth 發現流程。
---
## 管理
您的 MCP 可作為 opencode 中的工具以及內建工具使用。因此，您可以像任何其他工具一樣透過 opencode 設定來管理它們。
您的 MCP 在 OpenCode 中作為工具使用，與內建工具並列。因此，您可以像管理其他工具一樣，透過 OpenCode 設定來管理它們。
---
### 全域
這意味著您可以全域啟用或禁用它們。
您可以全域啟用或停用 MCP 工具。
```json title="opencode.json" {14}
{
@@ -318,7 +318,7 @@ opencode mcp debug my-oauth-server
}
```
我們也可以使用 glob 模式來禁用所有匹配的 MCP。
也可以使用 glob 模式來停用所有符合條件的 MCP。
```json title="opencode.json" {14}
{
@@ -339,16 +339,16 @@ opencode mcp debug my-oauth-server
}
```
這裡我們使用 glob 模式 `my-mcp*` 來禁用所有 MCP。
這裡使用 glob 模式 `my-mcp*` 來停用所有 MCP。
---
### 每個代理
### 按代理設定
如果您有大量 MCP 伺服器，您可能只想為每個代理啟用它們並全域禁用它們。為此：
如果您有大量 MCP 伺服器，可以選擇全域停用它們，然後僅在特定代理中啟用。具體做法：
1. 全局禁用它作為工具。
2. 在您的 [代理設定](/docs/agents#tools) 中，啟用 MCP 伺服器作為工具。
1. 全域停用該工具。
2. 在[代理設定](/docs/agents#tools)中，將 MCP 伺服器作為工具啟用。
```json title="opencode.json" {11, 14-18}
{
@@ -377,14 +377,14 @@ opencode mcp debug my-oauth-server
#### Glob 模式
glob 模式使用簡單的正規表示式 globbing 模式：
glob 模式使用簡單的正規表示式萬用字元規則：
- `*` 匹配零個或多個任意字元（例如，`"my-mcp*"` 匹配 `my-mcp_search`、`my-mcp_list` 等）
- `?` 恰好匹配一個字元
- 所有其他字元均按字面意思匹配
- `*` 比對零個或多個任意字元（例如，`"my-mcp*"` 比對 `my-mcp_search`、`my-mcp_list` 等）
- `?` 比對恰好一個字元
- 其他字元按字面值比對
:::note
MCP 伺服器工具以伺服器名稱作為前綴進行註冊，因此要禁用伺服器的所有工具，只需使用：
MCP 伺服器工具在註冊時以伺服器名稱作為前綴，因此要停用某個伺服器的所有工具，只需使用：
```
"mymcpservername_*": false
@@ -396,13 +396,13 @@ MCP 伺服器工具以伺服器名稱作為前綴進行註冊，因此要禁用
## 範例
以下是一些常見 MCP 伺服器的範例。如果您想記錄其他伺服器，您可以提交 PR。
以下是一些常見 MCP 伺服器的設定範例。如果您想記錄其他伺服器的用法，歡迎提交 PR。
---
### Sentry
添加 [Sentry MCP 伺服器](https://mcp.sentry.dev) 以與您的 Sentry 專案和問題進行互動。
新增 [Sentry MCP 伺服器](https://mcp.sentry.dev) 以與您的 Sentry 專案和問題進行互動。
```json title="opencode.json" {4-8}
{
@@ -417,15 +417,15 @@ MCP 伺服器工具以伺服器名稱作為前綴進行註冊，因此要禁用
}
```
添加設定後，使用 Sentry 進行身分驗證：
新增設定後，使用 Sentry 進行身分驗證：
```bash
opencode mcp auth sentry
```
這將打開一個瀏覽器視窗以完成 OAuth 流程並將 opencode 連接到您的 Sentry 帳號。
這會開啟瀏覽器視窗完成 OAuth 流程，將 OpenCode 連結到您的 Sentry 帳號。
通過身分驗證後，您可以在提示中使用 Sentry 工具來查詢問題、專案和錯誤資料。
認證完成後，您可以在提示詞中使用 Sentry 工具來查詢問題、專案和錯誤資料。
```txt "use sentry"
Show me the latest unresolved issues in my project. use sentry
@@ -435,7 +435,7 @@ Show me the latest unresolved issues in my project. use sentry
### Context7
添加 [Context7 MCP 伺服器](https://github.com/upstash/context7) 以搜尋文件。
新增 [Context7 MCP 伺服器](https://github.com/upstash/context7) 以搜尋文件。
```json title="opencode.json" {4-7}
{
@@ -449,7 +449,7 @@ Show me the latest unresolved issues in my project. use sentry
}
```
如果您註冊了免費帳號，則可以使用 API 金鑰並獲得更高的速率限制。
如果您註冊了免費帳號，可以使用 API 金鑰來取得更高的速率限制。
```json title="opencode.json" {7-9}
{
@@ -466,15 +466,15 @@ Show me the latest unresolved issues in my project. use sentry
}
```
這裡我們假設您設定了 `CONTEXT7_API_KEY` 環境變數。
這裡假設您已經設定了 `CONTEXT7_API_KEY` 環境變數。
將 `use context7` 添加到提示中以使用 Context7 MCP 伺服器。
在提示詞中新增 `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/)。
您也可以在 [AGENTS.md](/docs/rules/) 中新增類似的規則。
```md title="AGENTS.md"
When you need to search docs, use `context7` tools.
@@ -482,9 +482,9 @@ When you need to search docs, use `context7` tools.
---
### Vercel 的 Grep
### Grep by Vercel
添加 [Vercel 的 Grep](https://grep.app) MCP 伺服器以搜尋 GitHub 上的程式碼片段。
新增 [Grep by Vercel](https://grep.app) MCP 伺服器以搜尋 GitHub 上的程式碼片段。
```json title="opencode.json" {4-7}
{
@@ -498,13 +498,13 @@ When you need to search docs, use `context7` tools.
}
```
由於我們將 MCP 伺服器命名為 `gh_grep`，因此您可以將 `use the gh_grep tool` 添加到提示中以使代理使用它。
由於我們將 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/)。
您也可以在 [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.