Template

Jax 89f984a337 docs: clarify development and published stdio usage

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

2026-03-13 18:37:42 +08:00

5.2 KiB

Raw Blame History

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 客户端集成时的主要传输方式。

安装依赖
```
pnpm install
```
使用 MCP Inspector 运行 模板在 package.json 中提供了一个仅用于工作区开发的协议安全 mcp.stdio 启动配置，用于避免 stdout 被污染。你可以使用以下命令测试服务端：
```
pnpm dlx @modelcontextprotocol/inspector node ./node_modules/tsx/dist/cli.mjs src/stdio.ts
```
构建项目 如果你要为生产环境做准备，或使用编译后的入口文件，可以执行：
```
pnpm build
```
已发布包使用 npx 启动 如果你把这个模板产物发布到了 npm，并且保留了默认的 bin 映射，使用者可以直接通过包名启动 stdio 服务：
```
npx -y <your-package-name>
```
构建后，发布产物会直接提供扁平的 dist/stdio.js 入口，并作为 npm bin 暴露出来，适合分发后的 MCP client 集成场景。

OpenCode 配置示例

如果你想在 OpenCode 中把这个模板作为本地 MCP server 挂进去，可以在项目级 opencode.jsonc 里加入一段本地 MCP 配置。下面这个示例和当前 package.json 中仅用于开发态的 mcp.stdio 启动参数保持一致：

{
  "$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 的分发态启动方式：

{
  "$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 的接入场景。

启动 HTTP 服务
```
pnpm dev:http
```
服务默认监听 127.0.0.1:3000。你也可以通过 HTTP_PORT 环境变量自定义端口。
接口端点
- 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）：

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

3. 注册到核心模块

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

V1 限制

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

5.2 KiB Raw Blame History Unescape Escape