sync: import skills/, plugins/, memory/ and shared files from origin/main

2026-10-13 12:38:52 +08:00
parent 33155181a1
commit a9b4251158
8 changed files with 1713 additions and 0 deletions
@@ -0,0 +1,200 @@
+# 03 — MCP Servers (Model Context Protocol)
+
+> 源: <https://opencode.ai/docs/zh-cn/mcp-servers/>
+> 适用: 在 `opencode.json` 的 `mcp` 段加本地/远程 MCP server,加 OAuth 配置,按代理管控
+
+## 顶层结构
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "<server-name>": {
+      "type": "local" | "remote",
+      "enabled": true,
+      // local 还需 command + 可选 environment
+      // remote 还需 url + 可选 headers/oauth
+      "timeout": 5000
+    }
+  }
+}
+```
+
+> `enabled: false` 临时禁用 (配置保留)。彻底删 → 从 `mcp` 段移除。
+
+> **上下文成本警告**: MCP 工具进 LLM 上下文,大量启用易爆上下文。Sentry / GitHub MCP 特别吃 token。
+
+## 本地 (`type: "local"`)
+
+```json
+{
+  "mcp": {
+    "playwright": {
+      "type": "local",
+      "command": ["npx", "-y", "@playwright/mcp"],
+      "enabled": true,
+      "environment": { "BROWSER": "chromium" }
+    }
+  }
+}
+```
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `type` | ✅ | 必须 `"local"` |
+| `command` | ✅ | **字符串数组**,不是单个字符串 |
+| `environment` | ❌ | object, 启动时设置环境变量 |
+| `enabled` | ❌ | 启动时启用/禁用 |
+| `timeout` | ❌ | ms, 默认 5000 |
+
+## 远程 (`type: "remote"`)
+
+```json
+{
+  "mcp": {
+    "my-remote-mcp": {
+      "type": "remote",
+      "url": "https://my-mcp-server.com",
+      "enabled": true,
+      "headers": { "Authorization": "Bearer MY_API_KEY" }
+    }
+  }
+}
+```
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `type` | ✅ | 必须 `"remote"` |
+| `url` | ✅ | 远程 MCP server 地址 |
+| `enabled` | ❌ | — |
+| `headers` | ❌ | object, 随请求发 |
+| `oauth` | ❌ | object \| `false` |
+| `timeout` | ❌ | ms, 默认 5000 |
+
+## OAuth
+
+**自动**: 远程 server 触发 401 → opencode 自动走 OAuth 流程 (支持 RFC 7591 动态注册)。Token 存 `~/.local/share/opencode/mcp-auth.json`。
+
+**预注册** (已有 client 凭据):
+
+```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"
+      }
+    }
+  }
+}
+```
+
+**禁用自动 OAuth** (用 API key 替代):
+
+```json
+{
+  "mcp": {
+    "my-api-key-server": {
+      "type": "remote",
+      "url": "https://mcp.example.com/mcp",
+      "oauth": false,
+      "headers": { "Authorization": "Bearer {env:MY_API_KEY}" }
+    }
+  }
+}
+```
+
+**手动命令**:
+
+```bash
+opencode mcp auth <server>          # 触发 OAuth (开浏览器)
+opencode mcp auth list              # 列出所有支持 OAuth 的状态
+opencode mcp list                   # 列出所有 MCP server + 状态
+opencode mcp logout <server>        # 删凭据
+opencode mcp debug <server>         # 调试: 状态/HTTP/OAuth 发现
+```
+
+## 按代理管控 (MCP 工具)
+
+MCP 工具注册时**带 server 前缀** (`<server>_<tool>`)。要用 `tools.<server>_*` glob:
+
+**全局禁用,只在特定代理开**:
+
+```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 规则**: `*` 零或多字符,`?` 恰好一个字符,其它字面值。
+
+## 覆盖组织远程默认
+
+组织可在 `.well-known/opencode` 端点发默认 MCP server,可能默认禁用。启用方法: 在本地配置**加同名字段** + `enabled: true`。
+
+## 官方示例 (照搬)
+
+**Sentry**:
+
+```json
+{ "mcp": { "sentry": { "type": "remote", "url": "https://mcp.sentry.dev/mcp", "oauth": {} } } }
+```
+
+→ `opencode mcp auth sentry` → 浏览器 OAuth。
+
+**Context7** (查文档):
+
+```json
+{ "mcp": { "context7": { "type": "remote", "url": "https://mcp.context7.com/mcp" } } }
+```
+
+带 API key 提高速率:
+
+```json
+{
+  "mcp": {
+    "context7": {
+      "type": "remote",
+      "url": "https://mcp.context7.com/mcp",
+      "headers": { "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}" }
+    }
+  }
+}
+```
+
+提示: `use context7` 让代理用。也可在 AGENTS.md 写:
+
+```markdown
+When you need to search docs, use `context7` tools.
+```
+
+**Grep by Vercel** (搜 GitHub 代码):
+
+```json
+{ "mcp": { "gh_grep": { "type": "remote", "url": "https://mcp.grep.app" } } }
+```
+
+→ 提示: `use the gh_grep tool`。
+
+## 验证清单
+
+1. `type: local|remote` 必填,`command` 是数组。
+2. 远程 URL 正确,headers/oauth 字段拼写。
+3. 退出重启 opencode。
+4. `opencode mcp list` 看 server 状态。
+5. 在 prompt 里 `use <server>` 试调,或用 `mcp debug <server>` 诊断。
+6. 上下文吃紧 → 全局 `tools.<server>*: false`,按代理开。