MCP TypeScript SDK 实战指南：构建智能模型交互应用的开发秘籍

2026-04-19 08:28:47作者：裘晴惠Vivianne

在现代 AI 应用开发中，开发者常常面临三大核心痛点：首先，不同 AI 模型接口差异大，导致集成复杂且兼容性差；其次，客户端与服务器端通信逻辑繁琐，尤其在处理流式响应等场景时；最后，项目依赖体积庞大，影响应用性能和加载速度。而 MCP TypeScript SDK（模型上下文协议 TypeScript 开发工具包）正是为解决这些问题而生，它通过统一的协议规范、模块化设计和多环境支持，让开发者能够轻松构建高效、灵活的 AI 模型交互应用。

场景任务一：从零开始搭建 MCP 开发环境

核心 API：环境准备与 SDK 安装

▶️ Step 1/3：确认开发环境要求 确保你的开发环境满足以下条件：

Node.js 16.x 或更高版本
npm 或 yarn 包管理器

💡 实战小贴士：建议使用 nvm 管理 Node.js 版本，避免版本兼容性问题。

▶️ Step 2/3：安装 SDK 核心包 通过 npm 安装所需的核心包和组件：

npm install @modelcontextprotocol/core @modelcontextprotocol/client @modelcontextprotocol/server

▶️ Step 3/3：创建基础项目结构 一个典型的 MCP 应用项目结构如下：

your-project/
├── src/
│   ├── client/       # 客户端代码目录
│   └── server/       # 服务器端代码目录
├── node_modules/
└── package.json

执行上述步骤后，你将拥有一个基础的 MCP 开发环境，可开始进行客户端和服务器端的开发工作。

扩展技巧：多环境配置管理

在实际开发中，不同环境（开发、测试、生产）可能需要不同的配置。可以使用 dotenv 包来管理环境变量，创建 .env.development、.env.test 和 .env.production 文件，分别存储不同环境的配置信息。

⚠️ 常见陷阱：安装 SDK 时若出现依赖冲突，可尝试清除 npm 缓存后重新安装，命令为 npm cache clean --force && npm install。

场景任务二：构建 MCP 客户端与服务器通信

核心 API：创建客户端与服务器实例

▶️ Step 1/4：创建 MCP 客户端 使用 createClient 函数创建客户端实例，配置服务器地址和认证信息：

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

const client = createClient({
  serverUrl: 'https://your-mcp-server.com',
  auth: {
    apiKey: 'your-api-key'  // 认证方式之一：API 密钥
  }
});

▶️ Step 2/4：创建 MCP 服务器 使用 createServer 函数创建服务器实例，设置消息处理函数：

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

const server = createServer({
  handlers: {
    async onMessage(request) {
      return {
        message: `Received: ${request.message}`,
        context: request.context
      };
    }
  }
});

▶️ Step 3/4：启动服务器 调用服务器的 listen 方法启动服务，监听指定端口：

server.listen(3000, () => {
  console.log('MCP server running on port 3000');
});

▶️ Step 4/4：客户端发送消息并处理响应 通过客户端实例发送消息，并处理服务器的响应：

async function main() {
  try {
    const response = await client.sendMessage({
      message: 'Hello from MCP client!',
      context: {}
    });
    console.log('Server response:', response);
  } catch (error) {
    console.error('Error:', error);
  }
}

main();

完成以上步骤后，客户端与服务器将建立通信，能够相互发送和处理消息。

扩展技巧：处理流式响应

对于大型模型输出等场景，流式响应处理非常重要。MCP SDK 提供了 sendMessageStream 方法来处理流式响应：

async function streamExample() {
  const stream = await client.sendMessageStream({
    message: 'Generate a long text response',
    stream: true
  });

  for await (const chunk of stream) {
    process.stdout.write(chunk.message);
  }
}

⚠️ 常见陷阱：处理流式响应时，需确保正确关闭流以避免内存泄漏，可使用 try...finally 块确保流在使用后被关闭。

原理透视：MCP 协议的核心交互机制

MCP 协议（模型上下文协议）是客户端与服务器之间进行通信的规范，其核心交互机制基于请求 - 响应模式。客户端向服务器发送包含消息和上下文的请求，服务器处理后返回响应。在流式响应场景下，服务器会将响应分成多个块逐步返回，客户端通过迭代器接收并处理这些块。这种机制确保了通信的高效性和灵活性，支持各种 AI 模型交互场景。

场景任务三：MCP SDK 高级特性应用

核心 API：认证机制与中间件

▶️ Step 1/2：实现 OAuth 认证 除了 API 密钥认证外，MCP SDK 还支持 OAuth 认证：

const client = createClient({
  serverUrl: 'https://your-mcp-server.com',
  auth: {
    oauth: {
      clientId: 'your-client-id',
      clientSecret: 'your-client-secret',
      tokenEndpoint: 'https://auth-server.com/token'
    }
  }
});

▶️ Step 2/2：使用中间件扩展功能 MCP SDK 支持中间件机制，可用于日志记录、请求修改等：

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

const client = createClient({
  serverUrl: 'https://your-mcp-server.com',
  middleware: [
    middleware.logRequest(),
    middleware.modifyRequest((req) => {
      req.headers['x-custom-header'] = 'custom-value';
      return req;
    })
  ]
});

通过上述配置，客户端将在发送请求时记录日志并添加自定义头信息。

扩展技巧：自定义协议版本

对于有特殊需求的场景，可以自定义 MCP 协议版本：

const server = createServer({
  protocolVersion: '2.0-custom',
  handlers: {
    // 自定义处理逻辑
  }
});

⚠️ 常见陷阱：自定义协议版本可能导致与标准客户端或服务器的兼容性问题，除非有特殊需求，否则建议使用默认协议版本。

进阶学习路径与社区资源

进阶学习路径

深入 MCP 协议规范：了解 MCP 协议的底层细节，包括消息格式、认证流程和错误处理等，可参考项目中的 docs/protocol.md 文件。
探索高级特性：学习如何使用 MCP SDK 的实验性特性，如任务管理、高级流处理等，可查看 packages/core/src/experimental/ 目录下的源码。