typescript-mcp-server-generator

生成 TypeScript MCP 服务

使用 MCP TypeScript SDK v2 以 TypeScript 创建一个完整的 Model Context Protocol (MCP) 服务，并满足以下规格：

要求

1. 项目结构：创建一个新的 TypeScript/Node.js 项目，并具有合适的目录结构
2. NPM 包：v1 的单体式 @modelcontextprotocol/sdk 包已停用。请使用专注的 v2 包：
   • @modelcontextprotocol/server — 服务实现（通过 @modelcontextprotocol/server/stdio 子路径使用 stdio 传输）
   • @modelcontextprotocol/node — Node HTTP 传输（NodeStreamableHTTPServerTransport），或框架适配器：@modelcontextprotocol/express、@modelcontextprotocol/hono、@modelcontextprotocol/fastify — 每个适配器都需要与其配套的框架一同安装（例如 @modelcontextprotocol/express + express）
   • @modelcontextprotocol/core — 共享协议 schema（从这里导入 *Schema 常量，而不是从 sdk/types.js）
   • zod@^4.2 — v2 要求 Zod 4.2+；不要使用 zod@3
3. 运行时：Node.js 20+（v2 最低要求）；以 ESM 优先，使用 "type": "module"（也提供 CommonJS 构建，因此如有需要 require() 也可用）
4. 服务类型：在 HTTP（Streamable HTTP 传输）或基于 stdio 的服务之间选择。SSE 和 WebSocket 传输已在 v2 中移除 — 不要生成它们。
5. 工具：创建至少一个有用的工具，并具有合适的 schema 校验
6. 错误处理：包含全面的错误处理和校验

实现细节

项目设置

• 使用 npm init 初始化并创建 package.json
• 安装依赖：@modelcontextprotocol/server、zod@^4.2，以及传输包 — 纯 Node HTTP 使用 @modelcontextprotocol/node，或使用框架适配器及其配套框架（例如 npm install @modelcontextprotocol/express express）
• 使用 ES modules 配置 TypeScript：在 package.json 中设置 "type": "module"
• 添加开发依赖：tsx 或 ts-node 用于开发
• 创建合适的 .gitignore 文件

服务配置

• 使用来自 @modelcontextprotocol/server 的 McpServer 类进行高层实现
• 设置服务名称和版本
• 选择合适的传输：
  • HTTP（Node）：来自 @modelcontextprotocol/node 的 NodeStreamableHTTPServerTransport
  • HTTP（Web Standard 运行时）：来自 @modelcontextprotocol/server 的 WebStandardStreamableHTTPServerTransport
  • stdio：来自 @modelcontextprotocol/server/stdio 的 StdioServerTransport
• 对于 HTTP：优先使用带合适中间件和错误处理的框架适配器（@modelcontextprotocol/express 等）
• 注意 v2 使用 Web Standard 的 Headers/Request 类型；使用 ctx.http?.req?.headers.get('x-custom') 读取请求头

工具实现

• 使用带配置对象的 registerTool() — v1 的可变参数 .tool() 签名已移除：

  server.registerTool('greet', {
    description: 'Greet user',
    inputSchema: z.object({ name: z.string() })
  }, async ({ name }, ctx) => {
    return { content: [{ type: 'text', text: `Hello, ${name}!` }] };
  });
  

• Schema 必须是完整的 Zod 对象（z.object({...})）— 原始形状对象（{ name: z.string() }）已弃用
• 提供清晰的 title 和 description 字段
• 在结果中同时返回 content 和 structuredContent
• 处理函数的第二个参数是结构化的 ctx 对象（替代 v1 的 extra）：ctx.mcpReq.signal、ctx.mcpReq.id、ctx.mcpReq.send(...)、ctx.mcpReq.notify(...)
• 使用 try-catch 块实现合适的错误处理；使用 v2 错误层级（ProtocolError、SdkError、带 .status 的 SdkHttpError）而不是 v1 的 McpError/StreamableHTTPError
• 在合适的地方支持异步操作

资源/提示词设置（可选）

• 使用 registerResource() 和 ResourceTemplate 添加资源，以支持动态 URI
• 使用 registerPrompt() 和参数 schema 添加提示词（与 registerTool() 相同的配置对象风格）
• 考虑添加补全支持以改善 UX；注意 v2 completable() 包装器的顺序：completable(z.string(), callback).optional()（optional 应用在外层）

代码质量

• 使用 TypeScript 以确保类型安全
• 一致地遵循 async/await 模式
• 在传输关闭事件上实现正确的清理
• 使用环境变量进行配置
• 为复杂逻辑添加行内注释
• 以清晰的关注点分离来组织代码

可考虑的示例工具类型

• 数据处理与转换
• 外部 API 集成
• 文件系统操作（读取、搜索、分析）
• 数据库查询
• 文本分析或摘要（通过多轮 input_required 模式由大模型辅助）
• 系统信息检索

配置选项

• 对于 HTTP 服务：

  • 通过环境变量配置端口
  • 为浏览器客户端设置 CORS
  • 会话管理（无状态与有状态）
  • 本地服务的 DNS 重绑定防护
  • 严格的 Content-Type 处理：v2 拒绝非 application/json 的 POST 请求体

• 对于 stdio 服务：

  • 正确的 stdin/stdout 处理
  • 基于环境的配置
  • 进程生命周期管理

迁移现有的 v1 服务

• 先运行官方 codemod：npx @modelcontextprotocol/codemod@latest v1-to-v2 .
• 然后搜索 @mcp-codemod-error 标记，找出需要人工判断的部分（传输方式选择、请求头读取、错误分类）
• 将 McpError + ErrorCode 检查替换为新的错误类；HTTP 状态码现在位于 error.status，而不是 error.code
• Server.createMessage()、listRoots()、sendLoggingMessage() 以及 roots/sampling/logging 能力字段在 v2 中已弃用——在新代码中避免使用它们

测试指南

• 说明如何运行服务（npm start 或 npx tsx server.ts）
• 提供 MCP Inspector 命令：npx @modelcontextprotocol/inspector
• 对于 HTTP 服务，包含连接 URL：http://localhost:PORT/mcp
• 包含示例工具调用
• 为常见问题添加故障排除提示

可考虑的其他功能

• 使用多轮 input_required 模式的大模型驱动工具（这是 v2 中用于替代已弃用的 sampling 子系统的方案）
• 用于交互式工作流的用户输入引导
• 支持启用/禁用的动态工具注册
• 针对批量更新的通知防抖
• 用于高效数据引用的资源链接

生成一个完整、生产就绪的 MCP 服务，具备全面的文档、类型安全和错误处理。