03-Open code MCP 与工具调用

03-MCP 与工具调用

掌握 OpenCode 中 MCP（Model Context Protocol）服务器的配置和使用，扩展 AI 的工具能力。

一、MCP 概述

1.1 什么是 MCP

MCP（Model Context Protocol）是一种标准化协议，允许 AI 模型与外部工具和服务进行交互。通过 MCP，OpenCode 可以：

• 读取和操作本地文件
• 搜索网络信息
• 调用外部 API 和服务
• 运行自定义脚本和工具
• 连接数据库等后端服务

1.2 MCP 架构

┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ OpenCode │──────│ MCP 协议层 │──────│ 工具服务器 │ │ Client │ │ 中间件 │ │ Server │ └─────────────┘ └─────────────┘ └─────────────┘ │ ┌────────────────────────┼────────────────────────┐ │ │ │ ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐ │ File System │ │ Web Search │ │ Custom │ │ Server │ │ Server │ │ Servers │ └─────────────┘ └─────────────┘ └─────────────┘

1.3 常用 MCP 服务器

二、配置 MCP 服务器

2.1 全局配置

MCP 服务器配置在~/.opencode/config.json文件的"mcp"键下。标准格式使用 stdio 传输，通过command和args启动 MCP 服务器进程：

{"mcp":{"servers":{"filesystem":{"type":"stdio","command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/home/user/projects"]},"web-search":{"type":"stdio","command":"npx","args":["-y","@modelcontextprotocol/server-web-search"]}}}}

每个服务器配置包含：

2.2 使用 CLI 管理 MCP 服务器

OpenCode 提供了opencode mcp子命令来管理 MCP 服务器：

# 添加 MCP 服务器opencode mcpadd<name><command>[args...]# 列出所有 MCP 服务器及其状态opencode mcp list# 或简写opencode mcpls# 认证 OAuth 启用的 MCP 服务器opencode mcp auth[name]# 移除 OAuth 凭据opencode mcplogout[name]# 调试 OAuth 连接opencode mcp debug<name>

2.3 添加常用服务器示例

# 添加文件系统服务器，允许访问指定目录opencode mcpaddfilesystem npx-y@modelcontextprotocol/server-filesystem /path/to/allowed/dir# 添加自定义 Python MCP 服务器opencode mcpaddmy-server python /path/to/my_mcp_server.py# 查看当前配置的所有服务器opencode mcp list

三、File System MCP

3.1 配置示例

{"mcp":{"servers":{"filesystem":{"type":"stdio","command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/home/user/projects"]}}}}

可以通过在args中指定多个路径来允许访问多个目录：

{"mcp":{"servers":{"filesystem":{"type":"stdio","command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/home/user/projects","/home/user/docs"]}}}}

3.2 基本文件操作

配置后，AI 可以通过自然语言请求文件操作：

读取 app/main.py 创建文件 config.yaml，内容为： database: host: localhost port: 5432 列出 app/routers/ 目录下的所有文件 查找所有包含 "User" 的 Python 文件

3.3 安全注意事项

• File System 服务器只能访问在args中明确指定的目录
• 未列出的目录无法访问，确保敏感文件不会被意外暴露
• 建议仅添加项目所需的目录，遵循最小权限原则

四、Web Search MCP

4.1 配置示例

{"mcp":{"servers":{"web-search":{"type":"stdio","command":"npx","args":["-y","@modelcontextprotocol/server-web-search"]}}}}

4.2 使用搜索

配置后，AI 可以通过自然语言执行搜索：

搜索 FastAPI 最佳实践 在 docs.python.org 搜索 asyncio 教程 搜索最新的 Python 3.12 特性，并总结主要更新 搜索 SQLAlchemy 2.0 迁移指南，应用到当前项目

五、社区 MCP 服务器示例

MCP 生态中有大量社区开发的服务器，可以通过opencode mcp add添加。以下是一些常见类型：

5.1 浏览器自动化

社区提供了基于 Puppeteer 或 Playwright 的 MCP 服务器，用于网页截图、表单填写、页面交互等自动化操作：

# 添加浏览器自动化服务器（示例命令，具体包名以社区实际发布为准）opencode mcpaddbrowser npx-y@anthropic-ai/mcp-server-puppeteer

配置后可以通过自然语言让 AI 执行浏览器操作，如打开页面、截图、填写表单等。

5.2 数据库访问

社区提供了多种数据库 MCP 服务器（如 SQLite、PostgreSQL、MySQL 等），支持通过环境变量传递连接字符串：

# 添加数据库服务器（示例命令，具体包名以社区实际发布为准）opencode mcpadddatabase npx-y@anthropic-ai/mcp-server-sqlite ./mydb.sqlite

敏感的连接信息应通过env字段在配置中管理，而非硬编码。

5.3 查找更多 MCP 服务器

• 访问 MCP 服务器市场 浏览官方和社区服务器
• 使用opencode mcp list查看当前已配置的服务器
• 任何支持 stdio 传输的 MCP 服务器都可以通过opencode mcp add添加

六、数据库 MCP

6.1 配置示例

通过环境变量传递敏感的连接信息：

{"mcp":{"servers":{"database":{"type":"stdio","command":"npx","args":["-y","@modelcontextprotocol/server-sqlite","./mydb.sqlite"],"env":{"DATABASE_URL":"postgresql://localhost:5432/mydb"}}}}}

6.2 使用数据库工具

执行 SQL: SELECT * FROM users LIMIT 5 显示 users 表的字段结构 统计每个表的记录数 查询最近一周注册的用户，按注册时间排序

七、自定义 MCP 服务器

7.1 创建自定义服务器

可以使用任何语言编写 MCP 服务器。以下是一个 Python 示例：

# my_mcp_server.pyimportasynciofrommcp.serverimportServerfrommcp.typesimportTool,TextContent app=Server("my-server")@app.list_tools()asyncdeflist_tools():return[Tool(name="get_weather",description="获取指定城市的天气",inputSchema={"type":"object","properties":{"city":{"type":"string"}},"required":["city"]})]@app.call_tool()asyncdefcall_tool(name,arguments):ifname=="get_weather":city=arguments["city"]return[TextContent(type="text",text=f"{city}的天气是晴朗，25°C")]raiseValueError(f"Unknown tool:{name}")if__name__=="__main__":frommcp.server.stdioimportstdio_server asyncio.run(stdio_server(app))

7.2 配置自定义服务器

{"mcp":{"servers":{"my-server":{"type":"stdio","command":"python","args":["/path/to/my_mcp_server.py"]}}}}

也可以使用环境变量：

{"mcp":{"servers":{"my-server":{"type":"stdio","command":"python","args":["/path/to/my_mcp_server.py"],"env":{"API_KEY":"your-api-key","DEBUG":"false"}}}}}

7.3 使用自定义工具

配置后，AI 可以调用自定义工具：

使用 get_weather 查询北京天气

八、MCP 最佳实践

8.1 工具选择

8.2 组合使用

读取当前实现，搜索更好的方案，然后重构 测试 API，发现问题，修改代码，重新测试 查看表结构，生成对应的 SQLAlchemy 模型

8.3 安全建议

• 仅在args中指定必要的目录路径，遵循最小权限原则
• 使用环境变量管理 API 密钥等敏感信息，不要硬编码在配置中
• 定期审查~/.opencode/config.json中配置的服务器
• 不再使用的服务器及时从配置中移除

九、故障排除

9.1 连接问题

# 列出所有 MCP 服务器及其状态opencode mcp list# 调试 OAuth 连接（如果服务器需要认证）opencode mcp debug<name># 认证 OAuth 服务器opencode mcp auth[name]

9.2 常见问题

9.3 移除服务器

# 从配置中移除不再需要的服务器# 直接编辑 ~/.opencode/config.json，删除对应的服务器配置# 移除 OAuth 凭据opencode mcplogout[name]

十、实战示例

10.1 Web 应用开发流程

# 1. 创建项目 创建 FastAPI 项目结构 # 2. 设计数据库 查看数据库设计模式 生成 SQLAlchemy 模型 # 3. 开发 API 生成 CRUD 路由 # 4. 测试 API 打开 http://localhost:8000/docs 测试所有端点 截图保存测试结果 # 5. 验证数据 验证数据已正确写入

10.2 代码重构流程

# 1. 分析现有代码 读取所有相关文件 分析代码结构 # 2. 搜索最佳实践 搜索 SQLAlchemy 2.0 最佳实践 对比当前实现 # 3. 执行重构 批量修改所有模型 更新所有查询语句 # 4. 验证重构 运行测试 检查数据库兼容性

十一、下一步

掌握 MCP 后，建议学习：

1. 04-SubAgent任务分发.md - 并行处理任务
2. 06-Skills复用.md - 创建可复用技能
3. 09-实战：PythonWebAPI开发.md - 完整项目实战

文档版本: 1.1 | 建议学习时长: 45分钟