构建自定义 MCP 服务器

1. 编码前设计能力面。列出工具（动作）、资源（读取）和提示（模板）。 工具：query_db(sql)、insert_ticket(title, body) 资源：schema://db/tables、ticket://open-list 提示："investigate-incident" 模板 2. 用 SDK 搭建并选传输： npm install @modelcontextprotocol/sdk 本地开发：stdio。共享/团队：SSE（HTTP）。 3. 实现工具，用严格 JSON Schema 和类型化错误： - inputSchema 为 AI 必须提供的每个参数加 'required'。 - 成功返回 { content: [{ type: 'text', text }] }。 - 失败返回 { isError: true, content: [...] }，绝不抛异常。 4. 实现资源供 AI 浏览只读上下文： - uri 方案：db://tables、ticket://list - handler 返回文本或 JSON；保持小（每次读取约 4KB 以内）。 5. 实现提示为带参数的可复用模板： - name: "investigate-incident"，arguments: { incident_id: string } - 返回客户端渲染的提示，预填资源数据。 6. 仅日志到 stderr。stdio 传输中 stdout 是协议通道。 console.error('[mcp] query_db', sql) // 安全 stdio 服务器中绝不 console.log。 7. 用 inspector 测试，然后注册到客户端： npx @modelcontextprotocol/inspector node dist/server.js 在 Claude Desktop 配置（claude_desktop_config.json）的 mcpServers 下添加。

生产级 MCP 服务器（工具 + 资源 + 错误处理）： import { Server } from "@modelcontextprotocol/sdk/server/Server.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; const server = new Server( { name: "ticket-server", version: "1.0.0" }, { capabilities: { tools: {}, resources: {}, prompts: {} } }, ); // 工具：类型化错误，绝不抛异常 server.setRequestHandler("tools/call", async (req) => { const { name, arguments: args } = req.params; if (name === "insert_ticket") { if (!args?.title) { return { isError: true, content: [{ type: "text", text: "title 为必填" }] }; } const id = await db.insert(args.title, args.body ?? ""); return { content: [{ type: "text", text: `已创建工单 #${id}` }] }; } return { isError: true, content: [{ type: "text", text: `未知工具 ${name}` }] }; }); // 资源：只读上下文 server.setRequestHandler("resources/read", async (req) => { if (req.params.uri === "ticket://open-list") { const open = await db.listOpen(); return { contents: [{ uri: req.params.uri, mimeType: "application/json", text: JSON.stringify(open) }] }; } }); console.error("[mcp] ticket-server ready"); // 仅 stderr await server.connect(new StdioServerTransport());