# MCP (Model Context Protocol) 学习指南

1. 什么是 MCPMCP (Model Context Protocol) 是一个开放协议用于连接 LLM 应用与外部数据源和工具。┌─────────────┐ MCP ┌─────────────┐ │ Client │ ←─────────────────→ │ Server │ │ (opencode) │ JSON-RPC 消息 │ (你的服务) │ └─────────────┘ └─────────────┘MCP 提供的能力能力说明Tools供 AI 调用的函数如执行 SQLResources供 AI 访问的上下文/数据Prompts预定义的提示模板2. JSON-RPC 2.0 基础MCP 基于 JSON-RPC 2.0有三种消息类型2.1 Request请求- 需要响应{jsonrpc:2.0,id:1,method:tools/list,params:{}}规则jsonrpc必须是2.0id不能为null不能重复params可选2.2 Response响应- 返回结果成功响应{jsonrpc:2.0,id:1,result:{...}}错误响应{jsonrpc:2.0,id:1,error:{code:-32601,message:Method not found}}规则id必须与请求的id一致result和error不能同时存在2.3 Notification通知- 不需要响应{jsonrpc:2.0,method:initialized}规则不需要id2.4 标准错误码错误码含义-32700Parse error - JSON 解析失败-32600Invalid Request - 无效请求-32601Method not found - 方法不存在-32602Invalid params - 参数无效-32603Internal error - 内部错误3. MCP 消息格式请求格式{jsonrpc:2.0;id:string|number;method:string;params?:{[key:string]:unknown;};}响应格式{jsonrpc:2.0;id:string|number;result?:{[key:string]:unknown};error?:{code:number;message:string;data?:unknown;};}4. MCP 核心方法4.1 initialize - 初始化握手客户端 → 服务器{jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:opencode,version:1.0.0}}}服务器 → 客户端响应{jsonrpc:2.0,id:1,result:{protocolVersion:2024-11-05,capabilities:{tools:{}},serverInfo:{name:mysql-mcp,version:1.0.0}}}4.2 initialized - 握手完成客户端 → 服务器{jsonrpc:2.0,method:initialized}4.3 ping - 心跳检测请求{jsonrpc:2.0,id:2,method:ping}响应{jsonrpc:2.0,id:2,result:{}}5. 工具 (Tools) 定义5.1 tools/list - 列出可用工具请求{jsonrpc:2.0,id:3,method:tools/list}响应{jsonrpc:2.0,id:3,result:{tools:[{name:mysql_query,description:Execute MySQL query,inputSchema:{type:object,properties:{sql:{type:string,description:SQL statement to execute}},required:[sql]}}]}}5.2 tools/call - 调用工具请求{jsonrpc:2.0,id:4,method:tools/call,params:{name:mysql_query,arguments:{sql:SELECT * FROM users LIMIT 10}}}响应{jsonrpc:2.0,id:4,result:{content:[{type:text,text:[{\id\:1,\name\:\张三\},...]}]}}6. 你的代码解析你的mysql-mcp.js文件结构┌─────────────────────────────────────────────┐ │ 1. 创建连接池 (mysql2/promise) │ ├─────────────────────────────────────────────┤ │ 2. 创建 stdin/stdout 通信接口 │ ├─────────────────────────────────────────────┤ │ 3. 辅助函数 (sendResponse, sendError) │ ├─────────────────────────────────────────────┤ │ 4. 处理请求 (handleRequest) │ │ - initialize │ │ - tools/list │ │ - tools/call │ ├─────────────────────────────────────────────┤ │ 5. 主循环 (监听 stdin) │ ├─────────────────────────────────────────────┤ │ 6. 优雅退出 (SIGINT) │ └─────────────────────────────────────────────┘关键代码段发送成功响应constsendResponse(id,result){console.log(JSON.stringify({jsonrpc:2.0,id,result}));};发送错误响应constsendError(id,code,message){console.log(JSON.stringify({jsonrpc:2.0,id,error:{code,message}}));};处理 initialize 请求if(methodinitialize){sendResponse(id,{protocolVersion:2024-11-05,capabilities:{tools:{}},serverInfo:{name:mysql-mcp,version:1.0.0}});}处理 tools/list 请求if(methodtools/list){sendResponse(id,{tools:[{name:mysql_query,description:Execute MySQL query,inputSchema:{type:object,properties:{sql:{type:string,description:SQL statement to execute}},required:[sql]}}]});}处理 tools/call 请求if(methodtools/call){const{name,arguments:args}params;if(namemysql_query){const{sql}args;const[results]awaitpool.query(sql);sendResponse(id,{content:[{type:text,text:JSON.stringify(results)}]});}}7. 完整示例客户端发送的完整消息序列// 1. 初始化握手{jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:opencode,version:1.0.0}}}// 2. 握手完成通知{jsonrpc:2.0,method:initialized}// 3. 获取工具列表{jsonrpc:2.0,id:2,method:tools/list}// 4. 调用工具{jsonrpc:2.0,id:3,method:tools/call,params:{name:mysql_query,arguments:{sql:SELECT * FROM users}}}服务器返回的完整响应序列// 1. 初始化响应{jsonrpc:2.0,id:1,result:{protocolVersion:2024-11-05,capabilities:{tools:{}},serverInfo:{name:mysql-mcp,version:1.0.0}}}// 2. 工具列表响应{jsonrpc:2.0,id:2,result:{tools:[{name:mysql_query,description:Execute MySQL query,inputSchema:{type:object,properties:{sql:{type:string,description:SQL statement to execute}},required:[sql]}}]}}// 3. 工具调用响应{jsonrpc:2.0,id:3,result:{content:[{type:text,text:[{\id\:1,\name\:\张三\}]}]}}快速参考表必须遵循的键键值说明jsonrpc2.0版本号必须idstring/number请求标识不能为 nullmethodstring方法名resultobject成功结果errorobject错误信息可自定义的键位置键说明initialize 响应protocolVersion协议版本initialize 响应capabilities能力声明initialize 响应serverInfo服务器信息tools/list 响应tools工具数组工具定义name,description,inputSchema工具属性工具调用响应content返回内容下一步查看官方文档https://modelcontextprotocol.info查看 TypeScript Schemahttps://github.com/modelcontextprotocol/specification扩展你的 mysql-mcp.js添加更多工具如mysql_execute用于 INSERT/UPDATE添加 Resources 支持如查询数据库表结构文档生成时间2024