03-MCP 与工具调用掌握 OpenCode 中 MCPModel Context Protocol服务器的配置和使用扩展 AI 的工具能力。一、MCP 概述1.1 什么是 MCPMCPModel Context Protocol是一种标准化协议允许 AI 模型与外部工具和服务进行交互。通过 MCPOpenCode 可以读取和操作本地文件搜索网络信息调用外部 API 和服务运行自定义脚本和工具连接数据库等后端服务1.2 MCP 架构┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ OpenCode │──────│ MCP 协议层 │──────│ 工具服务器 │ │ Client │ │ 中间件 │ │ Server │ └─────────────┘ └─────────────┘ └─────────────┘ │ ┌────────────────────────┼────────────────────────┐ │ │ │ ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐ │ File System │ │ Web Search │ │ Custom │ │ Server │ │ Server │ │ Servers │ └─────────────┘ └─────────────┘ └─────────────┘1.3 常用 MCP 服务器服务器功能典型应用File System本地文件操作读取、修改项目文件Web Search网络搜索查询文档、搜索代码Puppeteer/Playwright浏览器自动化测试 Web 应用自定义服务器任意工具根据需求扩展二、配置 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]}}}}每个服务器配置包含字段说明type传输类型目前支持stdiocommand启动服务器的命令args命令的参数列表env环境变量可选2.2 使用 CLI 管理 MCP 服务器OpenCode 提供了opencode mcp子命令来管理 MCP 服务器# 添加 MCP 服务器opencode mcpaddnamecommand[args...]# 列出所有 MCP 服务器及其状态opencode mcp list# 或简写opencode mcpls# 认证 OAuth 启用的 MCP 服务器opencode mcp auth[name]# 移除 OAuth 凭据opencode mcplogout[name]# 调试 OAuth 连接opencode mcp debugname2.3 添加常用服务器示例# 添加文件系统服务器允许访问指定目录opencode mcpaddfilesystem npx-ymodelcontextprotocol/server-filesystem /path/to/allowed/dir# 添加自定义 Python MCP 服务器opencode mcpaddmy-server python /path/to/my_mcp_server.py# 查看当前配置的所有服务器opencode mcp list三、File System MCP3.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 MCP4.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-yanthropic-ai/mcp-server-puppeteer配置后可以通过自然语言让 AI 执行浏览器操作如打开页面、截图、填写表单等。5.2 数据库访问社区提供了多种数据库 MCP 服务器如 SQLite、PostgreSQL、MySQL 等支持通过环境变量传递连接字符串# 添加数据库服务器示例命令具体包名以社区实际发布为准opencode mcpadddatabase npx-yanthropic-ai/mcp-server-sqlite ./mydb.sqlite敏感的连接信息应通过env字段在配置中管理而非硬编码。5.3 查找更多 MCP 服务器访问 MCP 服务器市场 浏览官方和社区服务器使用opencode mcp list查看当前已配置的服务器任何支持 stdio 传输的 MCP 服务器都可以通过opencode mcp add添加六、数据库 MCP6.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 appServer(my-server)app.list_tools()asyncdeflist_tools():return[Tool(nameget_weather,description获取指定城市的天气,inputSchema{type:object,properties:{city:{type:string}},required:[city]})]app.call_tool()asyncdefcall_tool(name,arguments):ifnameget_weather:cityarguments[city]return[TextContent(typetext,textf{city}的天气是晴朗25°C)]raiseValueError(fUnknown 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 工具选择任务类型推荐工具原因文件读写File System直接操作效率高搜索信息Web Search覆盖范围广Web 测试Browser (Puppeteer)可视化验证数据查询Database (SQLite/PostgreSQL)实时数据验证特定需求自定义服务器灵活扩展8.2 组合使用读取当前实现搜索更好的方案然后重构 测试 API发现问题修改代码重新测试 查看表结构生成对应的 SQLAlchemy 模型8.3 安全建议仅在args中指定必要的目录路径遵循最小权限原则使用环境变量管理 API 密钥等敏感信息不要硬编码在配置中定期审查~/.opencode/config.json中配置的服务器不再使用的服务器及时从配置中移除九、故障排除9.1 连接问题# 列出所有 MCP 服务器及其状态opencode mcp list# 调试 OAuth 连接如果服务器需要认证opencode mcp debugname# 认证 OAuth 服务器opencode mcp auth[name]9.2 常见问题问题解决方法服务器无法启动检查command和args是否正确确保命令已安装权限错误确认文件系统服务器配置的路径存在且有访问权限OAuth 认证失败使用opencode mcp debug name查看详细错误环境变量未生效检查env字段的格式是否正确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 后建议学习04-SubAgent任务分发.md - 并行处理任务06-Skills复用.md - 创建可复用技能09-实战PythonWebAPI开发.md - 完整项目实战文档版本: 1.1 | 建议学习时长: 45分钟