用途
mcp-server-dev 用于指导开发者使用官方 TypeScript SDK v2(当前 main 分支)构建 MCP 服务器。它面向的包是 @modelcontextprotocol/server;如果代码仍从 @modelcontextprotocol/sdk 导入,需要先阅读 v1 到 v2 的迁移文档。
需要特别说明的是:这里的 v2 指导属于“当前 SDK 指导”,并非生产稳定性承诺。上游 TypeScript SDK README 目前将 main 分支上的 v2 标记为 pre-alpha,在稳定版 v2 发布前仍推荐使用 v1.x 用于生产环境。
主要能力
技能按决策树组织内容,覆盖以下方向:
- 从零新建服务器:项目脚手架、传输方式选择
- 注册原语:工具(Tools)、资源(Resources)、提示词(Prompts)
- 高级特性:收集用户输入(elicitation)、从工具调用 LLM(sampling)、长时间运行操作(tasks,实验性)
- 从 v1 迁移到 v2
- 部署:Claude Desktop(stdio)与生产 HTTP
使用方式
安装命令:
npm init -y
npm install @modelcontextprotocol/server zod
npm install -D typescript tsx @types/node
需要在 package.json 中设置 "type": "module"。
如果需要在 Node.js 上使用 Streamable HTTP,按实际使用情况添加适配器:
npm install @modelcontextprotocol/node
npm install @modelcontextprotocol/express express
最小 stdio 服务器示例:
import { McpServer } from '@modelcontextprotocol/server';
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
import { z } from 'zod/v4';
const server = new McpServer({ name: 'my-server', version: '1.0.0' });
server.registerTool(
'greet',
{
title: 'Greet',
description: 'Greet a user by name',
inputSchema: z.object({
name: z.string().describe('Name to greet'),
}),
},
async ({ name }) => ({
content: [{ type: 'text', text: `Hello, ${name}!` }],
})
);
const transport = new StdioServerTransport();
await server.connect(transport);
可立即测试:
npx @modelcontextprotocol/inspector tsx src/index.ts
关键模式
带结构化输出的工具:声明 outputSchema 时,需同时返回 content 和 structuredContent。
错误处理:将错误作为 content 返回,不要在工具回调中抛出未处理异常,应返回 { isError: true }。
动态资源:使用 ResourceTemplate,并始终提供 list 回调,以便客户端发现资源。
传输方式选择
- stdio:适用于 Claude Desktop、CLI 工具;单客户端,由进程启动
- Streamable HTTP(无状态):适用于生产 API、serverless;多客户端,可扩展
- Streamable HTTP(有状态):适用于会话、可恢复性;多客户端,会话持久化
- SSE 传输:自 2025 年 3 月起已弃用,应迁移到 Streamable HTTP
在 Node.js 上做 localhost HTTP,可使用 @modelcontextprotocol/express 的 createMcpExpressApp() 或 @modelcontextprotocol/hono 的 createMcpHonoApp()。Express 需搭配 @modelcontextprotocol/node 的 NodeStreamableHTTPServerTransport。
常见错误
- 使用 v1 API:v2 中不存在 server.tool(),应使用 server.registerTool()
- 传入原始形状 { name: z.string() },而非 z.object({ name: z.string() })
- 使用 SSE 传输(2025 年 3 月已弃用)
- 从工具回调抛出异常,应返回 { isError: true }
- package.json 缺少 "type": "module"
- 在 args 中硬编码密钥,应通过 Claude Desktop 配置的 env 传入
- Zod 字段省略 .describe(),LLM 依赖这些描述获取上下文
- 返回无界响应大小,Claude 有上下文窗口限制
参考文件
- references/project-setup.md:从零搭建新服务器项目
- references/tools.md:注册工具、schema、注解、ResourceLinks
- references/resources.md:静态与动态资源、URI 模板、补全
- references/prompts.md:带参数 schema 和补全的提示词模板
- references/transports.md:传输选择、stdio 与 Streamable HTTP、配置
- references/elicitation.md:通过表单或 URL 模式请求用户输入
- references/sampling.md:服务端 LLM sampling 与工具调用
- references/tasks.md:面向长时间运行操作的实验性任务执行
- references/migration-v1-to-v2.md:从 SDK v1 迁移到 v2
适用场景与限制
适用于正在构建 MCP 服务器、需要参考官方 TypeScript SDK v2 用法与迁移路径的开发者。限制在于:v2 目前为 pre-alpha,生产环境仍建议使用 v1.x;技能本身不提供生产稳定性保证。