MCP TypeScript SDK 服务说明文档

1. 服务概述一句话简介完整的MCP规范TypeScript实现轻松构建MCP客户端和服务器为LLM应用提供标准化的上下文管理能力。服务名称MCP TypeScript SDK版本号Latest开发者/提供方federated-alpha协议类型MCP (Model Context Protocol)包名称modelcontextprotocol/sdk官方文档https://glama.ai/mcp/servers/federated-alpha/MCP2. 核心功能MCP TypeScript SDK 提供以下主要功能MCP客户端构建构建可连接到任何MCP服务器的客户端应用MCP服务器创建创建暴露资源、提示词和工具的MCP服务器标准传输支持支持stdio和Streamable HTTP等标准传输方式协议消息处理处理所有MCP协议消息和生命周期事件资源管理通过Resources暴露数据给LLM类似GET端点工具提供通过Tools让LLM执行操作类似POST端点提示词定义通过Prompts定义可重用的LLM交互模板智能补全支持上下文感知的参数补全功能3. 使用场景MCP TypeScript SDK 适用于以下场景AI应用开发为AI应用提供标准化的上下文管理和数据访问接口MCP服务器开发快速构建符合MCP规范的服务器暴露数据和功能给LLMMCP客户端开发构建能够连接和消费MCP服务器资源的客户端应用数据集成将外部数据源和API集成到LLM应用中工具开发为LLM提供可调用的工具和功能提示词工程创建和管理可重用的提示词模板4. 接入方式4.1 服务端点MCP TypeScript SDK 支持多种传输方式stdio传输通过标准输入输出进行通信适合本地进程间通信Streamable HTTP通过HTTP协议进行通信适合网络环境协议版本MCP 1.04.2 认证与权限MCP SDK支持多种认证方式支持OAuth 2.0授权流程支持API密钥认证支持代理授权请求上游传递可自定义认证和权限控制逻辑4.3 数据格式MCP协议使用JSON-RPC 2.0格式进行通信请求格式JSON-RPC 2.0响应格式JSON-RPC 2.0内容类型application/json数据序列化JSON4.4 服务器配置在MCP客户端配置中添加服务{ mcpServers: { my-mcp-server: { command: node, args: [dist/index.js], env: { API_KEY: your-api-key } } } }5. 接口定义MCP TypeScript SDK 提供以下核心接口和概念5.1 Server服务器McpServer是MCP协议的核心接口处理连接管理、协议合规和消息路由const server new McpServer({ name: my-app, version: 1.0.0 });5.2 Resources资源资源用于向LLM暴露数据类似REST API的GET端点方法描述参数返回值registerResource注册静态资源name, uri, metadata, handlervoidregisterResource注册动态资源带参数name, ResourceTemplate, metadata, handlervoid5.3 Tools工具工具让LLM能够执行操作类似REST API的POST端点方法描述参数返回值registerTool注册工具name, metadata, handlervoid5.4 Prompts提示词提示词定义可重用的LLM交互模板方法描述参数返回值registerPrompt注册提示词模板name, metadata, handlervoid5.5 Completions补全支持上下文感知的智能参数补全new ResourceTemplate(github://repos/{owner}/{repo}, { list: undefined, complete: { repo: (value, context) { if (context?.arguments?.[owner] org1) { return [project1, project2].filter(r r.startsWith(value)); } return [default-repo].filter(r r.startsWith(value)); } } })6. 快速开始6.1 环境要求Node.jsv16.0.0或更高版本npm/yarn/pnpm任意包管理器TypeScriptv4.5或更高版本推荐操作系统Windows、macOS、Linux6.2 安装npm install modelcontextprotocol/sdk6.3 示例代码创建一个简单的MCP服务器包含计算器工具和动态资源import { McpServer, ResourceTemplate } from modelcontextprotocol/sdk/server/mcp.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { z } from zod; const server new McpServer({ name: demo-server, version: 1.0.0 }); server.registerTool(add, { title: Addition Tool, description: Add two numbers, inputSchema: { a: z.number(), b: z.number() } }, async ({ a, b }) ({ content: [{ type: text, text: String(a b) }] }) ); server.registerResource( greeting, new ResourceTemplate(greeting://{name}, { list: undefined }), { title: Greeting Resource, description: Dynamic greeting generator }, async (uri, { name }) ({ contents: [{ uri: uri.href, text: Hello, ${name}! }] }) ); const transport new StdioServerTransport(); await server.connect(transport);创建BMI计算器工具server.registerTool( calculate-bmi, { title: BMI Calculator, description: Calculate Body Mass Index, inputSchema: { weightKg: z.number(), heightM: z.number() } }, async ({ weightKg, heightM }) ({ content: [{ type: text, text: String(weightKg / (heightM * heightM)) }] }) );7. 注意事项开发注意事项协议理解MCP将提供上下文的关注点与实际LLM交互分离理解这一架构是关键资源vs工具资源用于提供数据无副作用工具用于执行操作可能有副作用传输选择stdio适合本地进程HTTP适合网络环境根据场景选择合适的传输方式类型安全使用Zod进行输入验证确保类型安全和参数正确性异步处理所有handler函数都是异步的正确处理Promise和错误生命周期管理正确处理服务器的启动、连接和关闭事件最佳实践为每个资源和工具提供清晰的描述和标题使用ResourceTemplate处理动态资源提高灵活性实现智能补全功能提升用户体验正确处理错误和异常情况在生产环境中使用构建后的代码而非开发模式测试和调试使用MCP Inspector工具测试和调试服务器参考官方提供的Echo Server和SQLite Explorer示例在开发过程中启用详细日志记录高级功能动态服务器支持运行时动态添加和移除功能低级服务器提供更细粒度的控制能力MCP客户端SDK也支持构建MCP客户端应用代理授权支持将授权请求代理到上游服务