构建智能上下文服务：MCP TypeScript SDK全栈开发指南

在AI应用开发中，如何为大语言模型(LLM)提供标准化的上下文服务？如何高效构建既能连接模型又能整合工具的桥梁系统？MCP协议（Model Context Protocol）与TypeScript SDK为这些挑战提供了优雅的解决方案。本文将系统讲解如何利用MCP TypeScript SDK构建生产级AI上下文服务，帮助开发者解决LLM应用中的上下文管理、工具集成和多模态交互难题。

问题导入：LLM应用开发的上下文困境

当你构建基于大语言模型的应用时，是否遇到过这些问题：如何让模型获取动态数据？怎样安全地让AI调用外部工具？不同模型供应商的接口差异如何统一？传统开发模式中，这些问题往往需要从零开始构建解决方案，导致系统耦合度高、可维护性差。MCP TypeScript SDK通过标准化协议和模块化设计，将上下文提供与模型交互解耦，让开发者专注于业务逻辑而非通信细节。

核心价值：为什么选择MCP TypeScript SDK

MCP TypeScript SDK的核心价值在于提供了一套完整的模型上下文服务架构，它包含三个关键优势：

• 协议标准化：定义统一的通信规范，解决不同AI模型接口差异问题
• 模块化设计：工具、资源、提示分离，支持独立开发与复用
• 多传输支持：兼容Streamable HTTP、Stdio等多种通信方式，适应不同部署场景

通过这套SDK，开发者可以快速构建从简单工具调用到复杂多模态交互的各类AI应用，同时保持系统的可扩展性和可维护性。

实践路径：从零构建MCP服务

环境准备与项目初始化

要开始使用MCP TypeScript SDK，首先需要准备基础开发环境：

# 克隆项目仓库
git clone https://gitcode.com/GitHub_Trending/ty/typescript-sdk
cd typescript-sdk

# 安装依赖
npm install

# 构建项目
npm run build

项目核心结构说明：

• packages/core/：协议核心实现
• packages/server/：服务器端组件
• packages/client/：客户端实现
• examples/：各类使用示例

基础组件：构建MCP服务的核心模块

McpServer：服务中枢

McpServer是整个服务的核心，负责管理工具、资源和提示，处理客户端请求。创建服务器的基本代码：

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

// 创建服务器实例，配置基本信息
const server = new McpServer({
  name: 'weather-assistant',  // 服务名称
  version: '1.0.0',           // 版本号
  description: '提供天气查询和生活建议的智能助手' // 服务描述
});

核心功能包括：服务元数据管理、组件注册、会话处理和协议合规性验证。

工具系统：让AI拥有行动力

工具是MCP服务的核心能力，允许AI执行特定操作。以下是一个天气查询工具的实现：

import { z } from 'zod';

// 注册天气查询工具
server.registerTool(
  'get-weather',  // 工具唯一标识
  {
    title: '天气查询',
    description: '获取指定城市的当前天气信息',
    inputSchema: z.object({
      city: z.string().describe('城市名称，如"北京"'),
      date: z.string().optional().describe('日期，格式YYYY-MM-DD，默认今天')
    }),
    outputSchema: z.object({
      temperature: z.number().describe('温度，单位摄氏度'),
      condition: z.string().describe('天气状况，如"晴朗"、"多云"'),
      humidity: z.number().describe('湿度，百分比')
    })
  },
  async ({ city, date }) => {
    // 实际天气API调用逻辑
    const weatherData = await fetchWeatherData(city, date);
    
    return {
      content: [{ 
        type: 'text', 
        text: `${city}${date ? date + '的' : '当前'}天气：${weatherData.condition}，温度${weatherData.temperature}°C` 
      }],
      structuredContent: weatherData
    };
  }
);

工具系统的设计遵循"模型控制"原则，即由AI决定何时以及如何调用工具。

资源系统：为AI提供上下文数据

资源是向AI提供结构化或非结构化数据的机制，不同于工具，资源不执行计算或产生副作用：

// 注册城市信息资源
server.registerResource(
  'city-info',  // 资源标识
  new ResourceTemplate('cities://{cityId}', { list: 'cities://' }),
  {
    title: '城市基本信息',
    description: '提供城市的人口、面积、气候等基本信息'
  },
  async (uri, { cityId }) => {
    // 从数据库获取城市信息
    const cityInfo = await cityDatabase.getCityInfo(cityId);
    
    return {
      contents: [{
        uri: uri.href,
        text: JSON.stringify(cityInfo),
        mimeType: 'application/json'
      }]
    };
  }
);

资源采用URI模式匹配，支持参数化路径，便于组织和访问层次化数据。

提示系统：引导AI交互

提示是预定义的对话模板，帮助用户高效与AI交互：

// 注册旅行建议提示
server.registerPrompt(
  'travel-suggestion',
  {
    title: '旅行建议',
    description: '根据天气和城市特点提供旅行建议',
    argsSchema: z.object({
      city: z.string().describe('目标城市'),
      days: z.number().int().min(1).describe('旅行天数')
    })
  },
  ({ city, days }) => ({
    messages: [
      {
        role: 'system',
        content: {
          type: 'text',
          text: `你是一位旅行顾问，需要根据以下信息为用户提供详细旅行建议：
- 城市：${city}
- 旅行天数：${days}天
请考虑当地天气、景点特色和文化活动，提供行程安排和注意事项。`
        }
      }
    ]
  })
);

提示可以在客户端以斜杠命令等形式提供给用户，降低使用门槛。

工作原理：MCP服务的内部运作机制

MCP服务的工作流程可以分为四个阶段：

1. 连接建立：客户端通过选定的传输方式与服务器建立连接
2. 能力协商：服务器向客户端宣告可用的工具、资源和提示
3. 交互处理：服务器接收并处理客户端请求（工具调用、资源获取等）
4. 响应生成：服务器返回结构化响应，包括文本内容和元数据

核心协议实现位于packages/core/src/shared/protocol.ts，定义了消息格式、交互流程和错误处理机制。

架构设计：从传输到部署的完整方案

传输方式选择

MCP支持多种传输方式，适用于不同场景：

Streamable HTTP传输：适用于网络服务，支持双向通信

import express from 'express';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';

const app = express();
app.use(express.json());

// 配置Streamable HTTP传输
app.post('/mcp', async (req, res) => {
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined, // 禁用会话管理，适合无状态服务
    enableJsonResponse: true      // 支持JSON响应
  });
  
  // 连接服务器和传输层
  await server.connect(transport);
  
  // 处理请求
  await transport.handleRequest(req, res, req.body);
});

app.listen(3000, () => {
  console.log('MCP服务器运行在 http://localhost:3000/mcp');
});

Stdio传输：适用于本地进程间通信

import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

// 创建Stdio传输
const transport = new StdioServerTransport();
await server.connect(transport);
console.log('Stdio MCP服务器已启动');

部署策略

根据应用规模和需求，MCP服务可以采用不同的部署策略：

单节点部署：适合开发和小型应用

# 启动简单Streamable HTTP服务器示例
npx tsx examples/server/simpleStreamableHttp.ts

多节点部署：适合高可用生产环境

对于需要水平扩展的场景，MCP支持两种模式：

1. 无状态模式：每个请求独立处理，适合纯计算型服务
2. 持久存储模式：使用数据库存储会话状态，支持会话恢复

// 带持久化存储的传输配置
const transport = new StreamableHTTPServerTransport({
  sessionIdGenerator: () => crypto.randomUUID(),
  eventStore: new DatabaseEventStore() // 自定义数据库事件存储
});

客户端实现：与MCP服务交互

MCP SDK提供了客户端库，方便与MCP服务器交互：

import { McpClient } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHttpClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

async function main() {
  // 创建客户端传输
  const transport = new StreamableHttpClientTransport({
    url: 'http://localhost:3000/mcp'
  });
  
  // 创建客户端实例
  const client = new McpClient(transport);
  await client.connect();
  
  try {
    // 获取服务器能力描述
    const capabilities = await client.getCapabilities();
    console.log('服务器能力:', capabilities);
    
    // 调用天气查询工具
    const result = await client.callTool('get-weather', { 
      city: '上海', 
      date: '2023-10-01' 
    });
    
    console.log('天气查询结果:', result.structuredContent);
    
  } finally {
    // 断开连接
    await client.disconnect();
  }
}

main().catch(console.error);

常见问题诊断：解决MCP开发中的挑战

连接问题排查

当客户端无法连接到服务器时，可以按以下步骤排查：

1. 检查传输配置：确认URL、端口和传输类型是否匹配
2. 验证服务器状态：通过curl测试基本连接

   curl -X POST http://localhost:3000/mcp -d '{"type":"capabilities"}'
   

3. 查看日志输出：服务器日志通常会显示连接尝试和错误信息

工具调用失败处理

工具调用失败的常见原因及解决方法：

• 参数验证错误：检查输入是否符合Zod schema定义
• 权限问题：确认客户端有调用该工具的权限
• 超时问题：考虑增加工具实现的超时处理或优化性能

性能优化建议

对于高并发场景，可以采取以下优化措施：

• 工具结果缓存：对相同参数的工具调用结果进行缓存
• 批量处理：合并多个资源请求，减少往返次数
• 异步处理：对于耗时操作，使用异步工具调用模式

进阶拓展：构建企业级MCP应用

高级功能探索

动态能力管理：根据用户权限动态启用或禁用工具和资源

// 基于用户角色的动态能力过滤
server.setCapabilityFilter(async (capabilities, context) => {
  const userRole = await getUserRole(context.userId);
  
  // 管理员可见所有能力
  if (userRole === 'admin') return capabilities;
  
  // 普通用户过滤敏感工具
  return capabilities.filter(cap => 
    !cap.id.includes('admin-')
  );
});

多模态支持：扩展MCP服务以处理图像、音频等多模态数据

// 注册图像分析工具
server.registerTool(
  'analyze-image',
  {
    title: '图像分析',
    description: '分析图像内容并返回描述',
    inputSchema: z.object({
      imageUrl: z.string().url().describe('图像URL')
    }),
    outputSchema: z.object({
      description: z.string().describe('图像内容描述'),
      objects: z.array(z.string()).describe('识别到的物体列表')
    })
  },
  async ({ imageUrl }) => {
    // 调用计算机视觉API分析图像
    const analysis = await imageAnalysisService.analyze(imageUrl);
    
    return {
      content: [{ type: 'text', text: analysis.description }],
      structuredContent: analysis
    };
  }
);

社区资源与生态系统

MCP TypeScript SDK拥有丰富的社区资源：

• 官方文档：docs/目录包含完整的API文档和使用指南
• 示例代码：examples/目录提供各类场景的实现示例
• 测试工具：test/目录包含完整的测试套件和辅助工具

总结：构建下一代AI应用的基石

MCP TypeScript SDK为构建智能上下文服务提供了标准化、模块化的解决方案。通过本文介绍的基础组件、工作原理和架构设计，开发者可以快速构建从简单工具调用到复杂多模态交互的各类AI应用。无论是创业公司的创新产品还是企业级的AI系统，MCP协议和TypeScript SDK都能提供坚实的技术基础，帮助开发者专注于创造真正的业务价值。

随着AI技术的不断发展，MCP协议将持续进化，为LLM应用开发提供更加完善的上下文服务解决方案。现在就开始探索MCP TypeScript SDK，构建你的下一代AI应用吧！