SuperAPI AI 工具集

mcp-server-dev

编程与开发

查看项目

更新于 10-16 08:31

技能介绍

用途

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;技能本身不提供生产稳定性保证。