OpenCode MCP集成实战教程：配置文件系统与GitHub服务器

📚 分类: AI 工具集成 ⏱️ 预计耗时: 45 分钟 🎯 难度: 中级 🔧 环境要求: 已安装并配置好 OpenCode、Node.js 环境

你将学到什么

完成本教程后，你将能够：

[ ] 理解 MCP (模型上下文协议) 的核心概念及其在 OpenCode 中的作用
[ ] 在 OpenCode 中配置并使用 stdio 和 sse 两种类型的 MCP 服务器
[ ] 集成文件系统、GitHub 等外部工具，扩展 AI 助手的能力
[ ] 掌握 MCP 工具的权限模型和安全最佳实践

最终效果

你将能够在 OpenCode 的对话中，直接让 AI 助手执行以下操作，就像使用内置工具一样自然：

用户: “帮我把项目根目录下的 README.md 文件内容读给我听。”
AI: (调用 filesystem_read_file 工具) “好的，文件内容如下：...”
用户: “为这个仓库创建一个 issue，标题是 ‘修复登录页面的样式问题’。”
AI: (调用 github_create_issue 工具) “已成功创建 issue #123。”

前置准备

在开始前，请确认你的环境满足以下条件：

检查项	要求版本	验证命令
OpenCode	最新版	`opencode --version`
Node.js	≥ 18.0	`node -v`
npm	≥ 9.0	`npm -v`

1. 准备 OpenCode 配置文件

MCP 服务器的配置信息都存放在 OpenCode 的根目录配置文件 opencode.json 中。如果你还没有这个文件，请手动创建一个。

bash

# 进入你的项目目录（或任意你希望作为 OpenCode 工作目录的地方）
$ cd /path/to/your/project

# 创建一个空的配置文件
$ touch opencode.json

✅ 验证：确认文件已创建。

bash

$ ls -la opencode.json
# 预期输出：-rw-r--r--  1 user  staff  0 Jun  2 10:00 opencode.json

第 1 步：理解 MCP 的两种连接类型

🎯 目标：了解 stdio 和 sse 两种连接方式的区别，以便后续根据场景选择正确的配置。

在配置之前，你需要知道 OpenCode 支持两种连接 MCP 服务器的方式：

stdio (标准输入/输出)：适合本地运行的工具或脚本。OpenCode 会启动一个本地进程，并通过其标准输入/输出流进行通信。这就像你直接在终端里运行一个程序。
sse (服务器发送事件)：适合远程的 API 或云服务。OpenCode 会通过 HTTP/HTTPS 协议连接到一个远程服务器，并通过 SSE 技术接收实时数据流。

💡 提示：对于大多数初学者，建议从 stdio 类型的本地工具开始，例如文件系统服务器，因为它不需要任何网络配置。

第 2 步：配置一个 `stdio` 类型的 MCP 服务器（以文件系统为例）

🎯 目标：配置一个名为 filesystem 的 MCP 服务器，让 AI 助手能够安全地读写你电脑上的指定文件夹。

🤔 为什么要这样做？ 这是最基础也是最实用的 MCP 应用场景。配置成功后，AI 助手将能直接读取文件内容、列出目录结构，甚至根据你的指令修改代码文件。

📝 操作：

打开你之前创建的 opencode.json 文件。
将以下 JSON 配置复制进去。请务必将 /path/to/allowed/files 替换为你希望 AI 助手能够访问的实际文件夹路径。

json

// opencode.json
{
  "mcpServers": {
    "filesystem": {                          // 服务器名称，将用于工具命名
      "type": "stdio",                       // 连接类型：标准输入/输出
      "command": "npx",                      // 执行的命令
      "args": [                              // 命令的参数
        "-y",                                // 自动回答 "yes"，避免交互式提示
        "@modelcontextprotocol/server-filesystem", // MCP 文件系统服务器的包名
        "/path/to/allowed/files"             // [!code --] // 旧路径，请替换
        "/Users/your-username/my-project"    // [!code ++] // 新路径，请替换为你自己的路径
      ],
      "env": []                              // 可选：环境变量，这里不需要
    }
  }
}

⚠️ 常见错误：

路径错误：如果指定的文件夹路径不存在，服务器将启动失败。
权限问题：确保 OpenCode 有权限读取该文件夹。如果遇到 EACCES 错误，可以尝试使用一个你完全控制的文件夹，比如你用户目录下的 Documents 或 Projects 文件夹。

✅ 验证：保存文件后，重启 OpenCode。在对话中输入以下指令：

text

列出当前工作目录下的所有文件。

如果配置成功，AI 助手会尝试调用 filesystem_list_directory 工具并返回结果。你会看到类似以下的输出：

text

[使用工具: filesystem_list_directory]
[结果: 成功]
当前目录下的文件有：
1. src/
2. package.json
3. README.md

第 3 步：配置一个需要环境变量的 `stdio` 服务器（以 GitHub 为例）

🎯 目标：配置一个名为 github 的 MCP 服务器，让 AI 助手能够操作你的 GitHub 仓库（如创建 Issue、管理 PR 等）。

🤔 为什么要这样做？ 文件系统操作只是第一步。集成 GitHub 后，你的 AI 助手就能直接从代码分析跳转到创建 Issue，实现开发工作流的自动化。

📝 操作：

首先，你需要一个 GitHub 个人访问令牌 (Personal Access Token)。
- 访问 GitHub 设置页面：Settings > Developer settings > Personal access tokens > Tokens (classic)。
- 点击 Generate new token。
- 为令牌命名，并勾选 repo 权限（完整控制私人仓库）或 public_repo（仅控制公开仓库）。
- 生成并复制令牌字符串（例如：ghp_xxxxxxxxxxxxxxxxxxxx）。请务必安全保管，不要泄露。
打开 opencode.json 文件，在 mcpServers 对象中添加一个新的配置项：

json

// opencode.json
{
  "mcpServers": {
    "filesystem": {                         // 上一步的配置
      // ... (保持不变)
    },
    "github": {                              // 新增：GitHub 服务器
      "type": "stdio",                       // 同样是 stdio 类型
      "command": "npx",                      // 通过 npx 运行
      "args": [
        "-y",
        "@modelcontextprotocol/server-github" // GitHub MCP 服务器包
      ],
      "env": [                               // 关键：环境变量
        "GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx" // [!code --] // 旧令牌，请替换
        "GITHUB_TOKEN=ghp_your_actual_token_here" // [!code ++] // 新令牌，请替换为你的真实令牌
      ]
    }
  }
}

⚠️ 常见错误：

令牌无效或过期：确保你复制的令牌是正确的，并且没有过期。你可以通过 curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user 来测试令牌是否有效。
令牌权限不足：如果 AI 尝试创建 Issue 但失败了，检查你的令牌是否勾选了 repo 权限。

✅ 验证：保存文件并重启 OpenCode。在对话中输入：

text

给我创建一个名为 "Test Issue from MCP" 的 Issue，内容为 "这是一个测试。"

AI 助手会尝试调用 github_create_issue 工具。如果成功，你会看到类似输出：

text

[使用工具: github_create_issue]
[结果: 成功]
已成功创建 Issue #1，链接: https://github.com/your-username/your-repo/issues/1

第 4 步：理解 MCP 工具的命名规则和权限模型

🎯 目标：理解工具名是如何生成的，并掌握如何批准或拒绝工具的执行请求。

🤔 为什么要这样做？ 当你看到 AI 使用一个名为 github_create_issue 的工具时，你知道它来自 github 服务器，提供的 create_issue 工具。理解命名规则和权限模型，能让你更安全、更有效地控制 AI 的行为。

工具命名规则

MCP 工具的命名遵循 {server-name}_{tool-name} 的格式。

server-name：你在 opencode.json 中配置的服务器名称（如 filesystem、github）。
tool-name：该 MCP 服务器自身提供的工具名称（如 read_file、create_issue）。

示例：如果你配置了一个名为 database-prod 的 PostgreSQL 服务器，它提供了一个名为 query 的工具，那么最终在 OpenCode 中可用的工具名就是 database-prod_query。

权限模型

每次 AI 想要执行一个 MCP 工具时，OpenCode 都会弹出一个权限确认对话框，让你审核将要执行的操作和参数。

对话框内容：会清晰显示工具名称、操作类型以及将要传入的参数。例如：

┌─ Permission Required ──────────────────────┐
│ Tool: github_create_issue                  │
│ Action: execute                            │
│                                             │
│ Parameters:                                │
│ {                                          │
│   "title": "Bug in user auth",             │
│   "body": "Description...",                │
│   "labels": ["bug"]                        │
│ }                                          │
│                                             │
│  [Allow]  [Allow for Session]  [Deny]      │
└─────────────────────────────────────────────┘

操作选项：
- Allow (允许)：仅允许执行这一次。
- Allow for Session (本次会话允许)：在当前 OpenCode 会话中，后续再调用该工具将不再询问。
- Deny (拒绝)：拒绝本次执行。

💡 提示：对于你信任且频繁使用的工具（如文件系统读取），选择“Allow for Session”可以大大提高效率。

进阶技巧（可选）

1. 配置 `sse` 类型的远程服务器

如果有一个远程的 MCP 服务（例如一个云端的数据库查询代理），你可以这样配置：

json

// opencode.json
{
  "mcpServers": {
    "remote-db": {
      "type": "sse",
      "url": "https://your-mcp-server.com/endpoint",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

2. 构建你自己的 MCP 服务器

你可以用 Python 或 Node.js 轻松创建自定义的 MCP 服务器。以下是一个 Python 示例，它创建了一个用于分析日志的工具：

python

# my_log_analyzer.py
from mcp.server import MCPServer, Tool
from mcp.types import TextContent

server = MCPServer("my-log-analyzer")   // 服务器名称

@server.tool(
    name="analyze_logs",                // 工具名称
    description="分析应用日志中的错误",   // 工具描述
    parameters={                        // 参数定义
        "log_path": {
            "type": "string",
            "description": "日志文件路径"
        },
        "severity": {
            "type": "string",
            "enum": ["error", "warning", "info"]
        }
    }
)
def analyze_logs(log_path: str, severity: str) -> list[TextContent]:
    # 你的实现逻辑
    with open(log_path) as f:
        logs = f.read()
    # ... 分析日志 ...
    count = logs.count(severity)
    return [TextContent(text=f"发现 {count} 条 {severity} 级别的消息")]

if __name__ == "__main__":
    server.run()

然后，在 opencode.json 中配置它：

json

{
  "mcpServers": {
    "custom": {
      "type": "stdio",
      "command": "python",
      "args": ["/path/to/my_log_analyzer.py"],
      "env": []
    }
  }
}

常见问题 (FAQ)

Q1: 配置后，AI 助手说找不到这个工具，怎么办？A: 这通常意味着服务器没有成功启动。请检查：

opencode.json 的 JSON 格式是否正确（可以使用 JSON 在线校验工具检查）。
服务器启动命令是否正确。例如，对于 filesystem 服务器，可以在终端单独运行 npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/files 看看是否有错误输出。
重启 OpenCode 使配置生效。

Q2: 执行工具时报错 Permission denied，但我的令牌是对的。A: 对于 stdio 类型的服务器，可能是 OpenCode 进程没有执行该命令的权限。尝试在配置的 command 前加上完整路径，例如 /usr/local/bin/npx。对于 sse 服务器，检查 headers 中的认证信息是否正确。

Q3: 如何调试 MCP 服务器？A: 你可以在 OpenCode 配置中启用调试模式。在 opencode.json 的对应服务器配置中添加 "debug": true 即可看到更详细的日志输出。

总结

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

MCP 协议：是一种让 AI 助手与外部工具和服务交互的标准化方式。
两种连接类型：stdio 用于本地工具，sse 用于远程服务。
工具命名规则：{服务器名}_{工具名}，便于识别来源。
权限模型：每次工具调用都需要你的显式批准，保障安全。

OpenCode MCP集成实战教程：配置文件系统与GitHub服务器 ​

你将学到什么 ​

最终效果 ​

前置准备 ​

1. 准备 OpenCode 配置文件 ​

第 1 步：理解 MCP 的两种连接类型 ​

第 2 步：配置一个 stdio 类型的 MCP 服务器（以文件系统为例） ​

第 3 步：配置一个需要环境变量的 stdio 服务器（以 GitHub 为例） ​

第 4 步：理解 MCP 工具的命名规则和权限模型 ​

工具命名规则 ​

权限模型 ​

进阶技巧（可选） ​

1. 配置 sse 类型的远程服务器 ​

2. 构建你自己的 MCP 服务器 ​

常见问题 (FAQ) ​

总结 ​

OpenCode MCP集成实战教程：配置文件系统与GitHub服务器

你将学到什么

最终效果

前置准备

1. 准备 OpenCode 配置文件

第 1 步：理解 MCP 的两种连接类型

第 2 步：配置一个 `stdio` 类型的 MCP 服务器（以文件系统为例）

第 3 步：配置一个需要环境变量的 `stdio` 服务器（以 GitHub 为例）

第 4 步：理解 MCP 工具的命名规则和权限模型

工具命名规则

权限模型

进阶技巧（可选）

1. 配置 `sse` 类型的远程服务器

2. 构建你自己的 MCP 服务器

常见问题 (FAQ)

总结