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/MCP

2. 核心功能

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规范的服务器，暴露数据和功能给LLM
MCP客户端开发：构建能够连接和消费MCP服务器资源的客户端应用
数据集成：将外部数据源和API集成到LLM应用中
工具开发：为LLM提供可调用的工具和功能
提示词工程：创建和管理可重用的提示词模板

4. 接入方式

4.1 服务端点

MCP TypeScript SDK 支持多种传输方式：

stdio传输：通过标准输入输出进行通信，适合本地进程间通信
Streamable HTTP：通过HTTP协议进行通信，适合网络环境
协议版本：MCP 1.0+

4.2 认证与权限

MCP SDK支持多种认证方式：

支持OAuth 2.0授权流程
支持API密钥认证
支持代理授权请求上游传递
可自定义认证和权限控制逻辑

4.3 数据格式

MCP协议使用JSON-RPC 2.0格式进行通信：

请求格式：JSON-RPC 2.0
响应格式：JSON-RPC 2.0
内容类型：application/json
数据序列化：JSON

4.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, handler	void
`registerResource`	注册动态资源（带参数）	name, ResourceTemplate, metadata, handler	void

5.3 Tools（工具）

工具让LLM能够执行操作，类似REST API的POST端点：

方法	描述	参数	返回值
`registerTool`	注册工具	name, metadata, handler	void

5.4 Prompts（提示词）

提示词定义可重用的LLM交互模板：

方法	描述	参数	返回值
`registerPrompt`	注册提示词模板	name, metadata, handler	void

5.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.js：v16.0.0或更高版本
npm/yarn/pnpm：任意包管理器
TypeScript：v4.5或更高版本（推荐）
操作系统：Windows、macOS、Linux

6.2 安装

npm install @modelcontextprotocol/sdk

6.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客户端应用
代理授权：支持将授权请求代理到上游服务

MCP TypeScript SDK 服务说明文档