用途:该技能根据给定规格生成一个完整的 Model Context Protocol(MCP)服务器项目,使用 TypeScript 与 MCP TypeScript SDK v2。适用于需要快速搭建 MCP 服务端骨架、集成工具/资源/提示,或从 v1 迁移到 v2 的场景。
主要能力与依赖:
- 项目结构:创建新的 TypeScript/Node.js 项目与目录结构,配置 ESM(package.json 中 "type": "module"),添加 .gitignore 与开发依赖(tsx 或 ts-node)。
- 包选择:v1 单体包 @modelcontextprotocol/sdk 已退役,改用 @modelcontextprotocol/server(服务实现,stdio 通过 @modelcontextprotocol/server/stdio 子路径)、@modelcontextprotocol/node(Node HTTP 传输 NodeStreamableHTTPServerTransport)、@modelcontextprotocol/core(共享协议 schema,从该包导入 *Schema 常量,而非 sdk/types.js)。可选框架适配器 @modelcontextprotocol/express、@modelcontextprotocol/hono、@modelcontextprotocol/fastify,需同时安装对应框架(如 @modelcontextprotocol/express + express)。需 zod@^4.2(v2 要求 Zod 4.2+,不可用 zod@3)。运行时 Node.js 20+,ESM 优先。
- 服务器类型:选择 HTTP(Streamable HTTP)或 stdio。v2 已移除 SSE 与 WebSocket 传输,不应生成。HTTP 场景推荐框架适配器并处理中间件与错误。
- 工具注册:使用 registerTool() 配置对象(v1 可变参数 .tool() 已移除),inputSchema 必须为完整 Zod 对象(z.object({...})),返回 content 与 structuredContent。handler 第二参数为结构化 ctx(ctx.mcpReq.signal、ctx.mcpReq.id、ctx.mcpReq.send、ctx.mcpReq.notify)。
- 资源与提示(可选):用 registerResource() 配合 ResourceTemplate 支持动态 URI;用 registerPrompt() 与参数 schema。v2 completable() 包装顺序为 completable(z.string(), callback).optional()。
- 错误处理:使用 v2 错误层级 ProtocolError、SdkError、SdkHttpError(含 .status),不使用 v1 的 McpError/StreamableHTTPError。
- 配置:HTTP 可使用环境变量端口、CORS、会话管理(无状态/有状态)、DNS 重绑定保护;v2 严格 Content-Type,拒绝非 application/json 的 POST 体。stdio 需处理 stdin/stdout、环境变量与进程生命周期。
- 迁移:先运行 npx @modelcontextprotocol/codemod@latest v1-to-v2 .,再搜索 @mcp-codemod-error 标记处理需人工判断的部分。注意 Server.createMessage()、listRoots()、sendLoggingMessage() 及 roots/sampling/logging 能力字段在 v2 中已弃用。
- 测试:说明运行方式(npm start 或 npx tsx server.ts),提供 npx @modelcontextprotocol/inspector,HTTP 连接 URL 为 http://localhost:PORT/mcp,并包含示例调用与排错建议。
适用场景:快速生成生产就绪的 MCP 服务器、集成外部 API、文件系统操作、数据库查询、文本分析等工具类型。
限制:具体项目名、端口、工具实现细节等需按实际需求填写;上述功能与命令均来自资料,未提及收费、价格与平台信息。