7步掌握MCP TypeScript SDK实战指南：构建AI模型交互应用

2026-04-21 10:51:17作者：郁楠烈Hubert

搭建生产级开发环境

环境要求对比表

环境	最低版本	推荐版本	优势
Node.js	16.x	18.x+	更好的异步处理能力
npm	7.x	9.x+	支持workspace功能
yarn	1.22.x	3.x+	更快的依赖安装速度

安装核心依赖

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

# 安装依赖
npm install @modelcontextprotocol/core @modelcontextprotocol/client @modelcontextprotocol/server

✅ 成功标志：node_modules目录生成，package.json中 dependencies 包含安装的包

⚠️ 警告：确保Node.js版本符合要求，可使用nvm管理多版本Node.js环境

📌 本章要点：

MCP TypeScript SDK需要Node.js 16.x以上环境
核心包包括core、client和server三个独立模块
推荐使用pnpm或yarn管理工作区依赖

理解MCP协议基础概念

MCP协议核心概念

🔍 MCP协议 → 模型上下文协议，一种标准化AI交互规范，定义了客户端与AI模型服务之间的通信方式。

生活化类比：就像餐厅服务员(客户端)与厨师(AI模型)之间的点单系统，服务员记录顾客需求(上下文)并传达给厨师，厨师处理后将菜品(响应)返回给服务员。

专业定义：MCP协议是一种基于HTTP的应用层协议，通过标准化的请求/响应格式，实现客户端与AI模型服务的可靠通信，支持上下文管理和流式响应。

核心架构组件

@modelcontextprotocol/core：包含协议基础类型和工具函数
@modelcontextprotocol/client：客户端实现，负责发送请求和处理响应
@modelcontextprotocol/server：服务器实现，处理客户端请求并与AI模型交互

📌 本章要点：

MCP协议标准化了AI模型交互流程
SDK采用模块化设计，降低依赖体积
核心架构分为客户端、服务器和共享类型三大部分

构建天气查询客户端

场景说明

创建一个天气查询客户端，通过MCP协议与天气AI服务交互，获取实时天气信息并处理响应。

核心代码

import { createClient } from '@modelcontextprotocol/client';

// 创建客户端实例
const weatherClient = createClient({
  serverUrl: 'https://weather-mcp-server.example.com',
  auth: {
    apiKey: 'your-weather-api-key'
  },
  timeout: 5000
});

// 查询天气函数
async function getWeather(city: string): Promise<string> {
  try {
    const response = await weatherClient.sendMessage({
      message: `查询${city}的当前天气`,
      context: {
        location: city,
        units: 'celsius',
        details: true
      }
    });
    
    return `🌤️ ${city}当前天气: ${response.message}`;
  } catch (error) {
    console.error('天气查询失败:', error);
    return '无法获取天气信息，请稍后重试';
  }
}

// 使用示例
getWeather('北京').then(console.log);

扩展思考

如何实现地理位置自动检测？
如何添加缓存机制减少重复请求？
如何处理不同地区的天气数据格式差异？

💡 小贴士：在生产环境中，建议将API密钥存储在环境变量中，避免硬编码敏感信息。可以使用dotenv库管理环境变量。

📌 本章要点：

createClient函数是创建客户端的入口点
认证配置支持多种方式，包括API密钥和OAuth
消息发送支持上下文参数，用于传递额外信息

开发实时翻译服务

场景说明

实现一个实时翻译服务，使用MCP SDK的流式响应功能，将英文文本实时翻译成中文。

核心代码

import { createClient } from '@modelcontextprotocol/client';

// 创建翻译客户端
const translatorClient = createClient({
  serverUrl: 'https://translation-mcp-server.example.com',
  auth: {
    oauth: {
      clientId: 'your-client-id',
      clientSecret: 'your-client-secret'
    }
  }
});

// 实时翻译函数
async function translateStream(text: string): Promise<void> {
  console.log('原文:', text);
  console.log('译文:');
  
  try {
    // 发起流式翻译请求
    const stream = await translatorClient.sendMessageStream({
      message: `将以下文本翻译成中文: ${text}`,
      stream: true,
      context: {
        sourceLang: 'en',
        targetLang: 'zh'
      }
    });
    
    // 处理流式响应
    let fullTranslation = '';
    for await (const chunk of stream) {
      fullTranslation += chunk.message;
      // 实时更新显示
      process.stdout.write(chunk.message);
    }
    
    console.log('\n翻译完成:', fullTranslation);
  } catch (error) {
    console.error('翻译失败:', error);
  }
}

// 使用示例
translateStream('The quick brown fox jumps over the lazy dog.');

扩展思考

如何实现多语言互译？
如何处理长文本分段翻译？
如何添加翻译进度指示？

📌 本章要点：

sendMessageStream方法用于获取流式响应
流式响应通过for-await-of循环处理
实时应用需要考虑背压(backpressure)处理

实现MCP协议服务器

场景说明

构建一个简单的MCP服务器，处理天气查询请求并返回模拟的天气数据。

核心代码

import { createServer } from '@modelcontextprotocol/server';

// 创建服务器实例
const weatherServer = createServer({
  port: 3000,
  handlers: {
    async onMessage(request) {
      console.log('收到请求:', request);
      
      // 模拟天气数据处理
      const location = request.context.location || '北京';
      const temperature = Math.floor(Math.random() * 30) + 10;
      const conditions = ['晴朗', '多云', '小雨', '大风'][Math.floor(Math.random() * 4)];
      
      // 返回响应
      return {
        message: `${location}当前气温${temperature}°C，${conditions}`,
        context: {
          ...request.context,
          timestamp: new Date().toISOString(),
          source: 'weather-mock-service'
        }
      };
    }
  },
  middleware: [
    // 添加请求日志中间件
    (req, res, next) => {
      console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
      next();
    }
  ]
});

// 启动服务器
weatherServer.listen(() => {
  console.log('天气MCP服务器运行在 http://localhost:3000');
});

扩展思考

如何添加请求验证中间件？
如何实现服务器集群部署？
如何添加请求限流保护？

✅ 成功标志：服务器启动后，可通过客户端连接并获取响应

📌 本章要点：

createServer函数用于创建MCP服务器实例
onMessage处理函数负责业务逻辑实现
中间件系统支持请求处理流程扩展

常见错误诊断流程图

连接错误诊断流程

客户端连接失败
│
├─检查网络连接 → 网络正常？
│  ├─是 → 检查服务器URL是否正确
│  └─否 → 修复网络连接
│
├─检查服务器状态 → 服务器运行中？
│  ├─是 → 检查防火墙设置
│  └─否 → 启动服务器
│
└─检查认证信息 → 认证有效？
   ├─是 → 查看服务器日志
   └─否 → 更新认证信息

响应超时诊断流程

请求响应超时
│
├─检查网络延迟 → 延迟正常？
│  ├─是 → 检查服务器负载
│  └─否 → 优化网络连接
│
├─检查请求复杂度 → 请求是否过于复杂？
│  ├─是 → 简化请求或增加超时时间
│  └─否 → 检查服务器处理逻辑
│
└─检查服务器资源 → 资源充足？
   ├─是 → 优化服务器代码
   └─否 → 增加服务器资源

📌 本章要点：

连接错误通常与网络、URL或认证有关
响应超时可能由网络延迟或服务器负载引起
复杂请求应考虑增加超时时间或优化请求内容

性能优化实践

客户端优化策略

优化技术	实现方式	性能提升
请求批处理	将多个小请求合并为一个批量请求	减少50%网络往返
连接复用	使用keep-alive保持TCP连接	降低30%连接建立开销
响应缓存	缓存重复请求的响应结果	减少70%重复计算

服务器优化代码示例

import { createServer } from '@modelcontextprotocol/server';
import { createLRUCache } from '@modelcontextprotocol/core';

// 创建响应缓存，最大1000条记录，过期时间5分钟
const responseCache = createLRUCache({ maxSize: 1000, ttl: 5 * 60 * 1000 });

const optimizedServer = createServer({
  port: 3000,
  handlers: {
    async onMessage(request) {
      // 生成缓存键
      const cacheKey = JSON.stringify(request);
      
      // 检查缓存
      const cachedResponse = responseCache.get(cacheKey);
      if (cachedResponse) {
        console.log('使用缓存响应');
        return cachedResponse;
      }
      
      // 处理请求...
      const response = {
        message: '处理后的响应',
        context: request.context
      };
      
      // 缓存响应
      responseCache.set(cacheKey, response);
      return response;
    }
  },
  // 启用压缩
  compression: true,
  // 配置连接复用
  keepAlive: {
    timeout: 60000,
    maxRequests: 1000
  }
});

optimizedServer.listen(() => {
  console.log('优化后的MCP服务器运行在 http://localhost:3000');
});