ts-mcp-template/README.md

# TS MCP 模板（V1）

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

## 当前状态：V1 Alpha

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

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

## 快速开始：本地 Stdio

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

1. **安装依赖**
   ```bash
   pnpm install
   ```

2. **使用 MCP Inspector 运行**
   模板在 `package.json` 中提供了协议安全的启动配置，用于避免 stdout 被污染。你可以使用以下命令测试服务端：
   ```bash
   pnpm dlx @modelcontextprotocol/inspector node ./node_modules/tsx/dist/cli.mjs src/stdio.ts
   ```

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

## 使用方式：HTTP

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

1. **启动 HTTP 服务**
   ```bash
   pnpm dev:http
   ```
   服务默认监听 `127.0.0.1:3000`。你也可以通过 `HTTP_PORT` 环境变量自定义端口。

2. **接口端点**
   - `POST /mcp`：初始化一个新会话并处理请求。
   - `GET /mcp`：处理已有会话中的后续请求。

## 开发与测试

- **类型检查**：`pnpm typecheck`
- **测试**：`pnpm test`（运行 stdio、HTTP 和核心逻辑的 Vitest smoke tests）
- **开发模式（核心逻辑）**：`pnpm 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.19+ 进行适配。
- **非 Monorepo**：设计目标是独立项目模板，而不是多包仓库。
- **本地优先**：V1 暂未提供面向云服务商的部署指南。