ts-mcp-template/README.md

TS MCP 模板（V1）

这是一个用于构建 Model Context Protocol（MCP）服务端的 Node.js + TypeScript 模板。该模板重点关注本地优先的开发体验、协议安全的 stdio 执行方式，以及显式的能力注册模式。

当前状态：V1 Alpha

当前模板支持：

• Node.js 20+ 运行时
• 单包架构
• 协议安全的本地 Stdio 传输（主要方式）
• Streamable HTTP 传输（次要方式）
• 显式的、基于函数的 tool、resource 和 prompt 注册方式
• 基于 Vitest 的传输层与核心逻辑测试

当前尚不支持 Bun、Deno、边缘运行时、内置鉴权或遥测能力。

快速开始：本地 Stdio

Stdio 是本模板在本地开发以及与 Claude 等桌面 LLM 客户端集成时的主要传输方式。

1. 安装依赖

   npm install
   

2. 使用 MCP Inspector 运行 模板在 package.json 中提供了协议安全的启动配置，用于避免 stdout 被污染。你可以使用以下命令测试服务端：

   npx @modelcontextprotocol/inspector node ./node_modules/tsx/dist/cli.mjs src/stdio.ts
   

3. 构建项目 如果你要为生产环境做准备，或使用编译后的入口文件，可以执行：

   npm run build
   

使用方式：HTTP

HTTP 传输基于 Node 原生的 StreamableHTTPServerTransport，适用于远程连接或基于 Web 的接入场景。

1. 启动 HTTP 服务

   npm run dev:http
   

   服务默认监听 127.0.0.1:3000。你也可以通过 HTTP_PORT 环境变量自定义端口。

2. 接口端点

   • POST /mcp：初始化一个新会话并处理请求。
   • GET /mcp：处理已有会话中的后续请求。

开发与测试

• 类型检查：npm run typecheck
• 测试：npm test（运行 stdio、HTTP 和核心逻辑的 Vitest smoke tests）
• 开发模式（核心逻辑）：npm run dev（执行 src/index.ts）

仓库结构

• src/core/：共享的 MCP 核心工厂 createMcpCore，负责构建服务端与注册表。
• src/capabilities/：tools、resources 与 prompts 的定义及处理逻辑。
• src/stdio.ts：stdio 入口文件及其传输层配置。
• src/http.ts：HTTP 入口文件与会话管理逻辑。
• src/config/：运行时配置与环境变量解析。
• src/lib/：内部工具函数、stderr 安全日志以及错误处理。

扩展指引

该模板使用显式的、基于函数的注册模式，而不是装饰器或反射机制。

1. 定义契约

在 src/capabilities/contracts.ts 中新增 tool 或 prompt 的 schema，以便在处理逻辑和测试之间共享类型。

2. 实现处理器

在 src/capabilities/ 中创建或更新文件（例如 tools.ts）：

1. 定义处理器逻辑。
2. 更新 register...Capabilities 函数，将描述信息加入注册表。
3. 更新 register...Handlers 函数，将逻辑挂接到 McpServer 实例上。

3. 注册到核心模块

如果你创建了新的 capability 模块，请确保它们已在 src/capabilities/index.ts 的 registerCoreCapabilities 和 registerCoreMcpCapabilities 函数中被调用。

V1 限制

• 无鉴权：HTTP 传输不包含内置鉴权能力。
• 仅支持 Node：当前专门针对 Node.js 20+ 进行适配。
• 非 Monorepo：设计目标是独立项目模板，而不是多包仓库。
• 本地优先：V1 暂未提供面向云服务商的部署指南。