89f984a337
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
143 lines
5.2 KiB
Markdown
143 lines
5.2 KiB
Markdown
# 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` 中提供了一个仅用于工作区开发的协议安全 `mcp.stdio` 启动配置，用于避免 stdout 被污染。你可以使用以下命令测试服务端：
|
||
```bash
|
||
pnpm dlx @modelcontextprotocol/inspector node ./node_modules/tsx/dist/cli.mjs src/stdio.ts
|
||
```
|
||
|
||
3. **构建项目**
|
||
如果你要为生产环境做准备，或使用编译后的入口文件，可以执行：
|
||
```bash
|
||
pnpm build
|
||
```
|
||
|
||
4. **已发布包使用 `npx` 启动**
|
||
如果你把这个模板产物发布到了 npm，并且保留了默认的 `bin` 映射，使用者可以直接通过包名启动 stdio 服务：
|
||
```bash
|
||
npx -y <your-package-name>
|
||
```
|
||
构建后，发布产物会直接提供扁平的 `dist/stdio.js` 入口，并作为 npm `bin` 暴露出来，适合分发后的 MCP client 集成场景。
|
||
|
||
### OpenCode 配置示例
|
||
|
||
如果你想在 OpenCode 中把这个模板作为本地 MCP server 挂进去，可以在项目级 `opencode.jsonc` 里加入一段本地 MCP 配置。下面这个示例和当前 `package.json` 中仅用于开发态的 `mcp.stdio` 启动参数保持一致：
|
||
|
||
```jsonc
|
||
{
|
||
"$schema": "https://opencode.ai/config.json",
|
||
"mcp": {
|
||
"template_stdio": {
|
||
"type": "local",
|
||
"enabled": true,
|
||
"command": [
|
||
"node",
|
||
"./node_modules/tsx/dist/cli.mjs",
|
||
"src/stdio.ts"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
如果你把配置放在全局 OpenCode 配置里，需要把 `command` 里的相对路径改成这个项目的绝对路径，或者把 OpenCode 的工作目录指向仓库根目录。这样可以避免找不到 `./node_modules/tsx/dist/cli.mjs` 或 `src/stdio.ts`。
|
||
|
||
如果你是通过 npm 发布后的包来接入 OpenCode，也可以改成直接走 `npx` 的分发态启动方式：
|
||
|
||
```jsonc
|
||
{
|
||
"$schema": "https://opencode.ai/config.json",
|
||
"mcp": {
|
||
"template_stdio": {
|
||
"type": "local",
|
||
"enabled": true,
|
||
"command": ["npx", "-y", "<your-package-name>"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
这种方式更适合已经发布的包；而模板开发阶段，仍然建议优先使用上面的源码启动配置。
|
||
|
||
## 发布面验证
|
||
|
||
- **发布入口检查**：`pnpm test:publish`（打包本地 tarball，并通过包的 `bin` 名启动一次 stdio 服务）
|
||
|
||
## 使用方式：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 暂未提供面向云服务商的部署指南。
|