前言：打破 AI 的孤岛效应

我们经常面临一个尴尬的局面：AI 聪明绝顶，却被困在了一个没有窗户的房间里。它知道如何写诗、如何编程，却无法直接读取你本地的配置文件，也无法实时查询你公司内部的数据库。这就是所谓的“孤岛效应”。为了打破这堵墙，Model Context Protocol 应运而生，而 TypeScript SDK 则是我们手中Zui锋利的凿子。

今天我们不谈枯燥的理论，而是要像拆解一台精密的发动机一样，深入剖析如何使用 @modelcontextprotocol/sdk。无论你是想构建一个Neng读取本地文件的服务器，还是想打造一个Neng与外部 API 交互的客户端，这篇指南dou将为你提供从架构理解到代码实现的全方位视角。准备好让你的 AI 应用“长出手脚”了吗？让我们开始吧。

一、 架构透视：MCP 的生态图谱

在敲击键盘之前，我们需要先在脑海中构建一张地图。MCP 并不是一个简单的工具库，它是一套完整的通信协议，连接着 LLM 的“大脑”与外部世界的“感官”。

想象一下整个系统就像是一个繁忙的物流中心。

LLM 这是Zui终的决策者，它发出指令，并消费结果。

MCP Client这是物流调度员。它负责理解 LLM 的意图，找到合适的服务器，并将请求打包发送。

MCP Server这是具体的执行者。它可Neng是一个运行在本地的 Node.js 进程，也可Neng是一个远程的 HTTP 服务。它手里握有各种资源和工具。

Transport这是连接调度员和执行者的运输管道。Ke以是本地的 Stdio，也Ke以是远程的 HTTP 流。

这种分层设计使得系统极其灵活。你不需要关心底层是用 HTTP 还是 WebSocket 传输，也不需要关心 LLM 是 Claude 还是 GPT-4，只要遵循 MCP 协议，它们就Neng无缝协作。

二、 核心Neng力：赋予 AI 超Neng力

MCP TypeScript SDK 将其强大的功Neng封装在几个核心概念中。理解这些概念，是掌握 SDK 的关键。

1. Tools：让 AI 动起来

Ru果说 LLM 是大脑，那么 Tools 就是它的双手。工具是服务器暴露给客户端的可调用函数。通过注册工具，我们允许 AI 执行具体的操作，比如计算 BMI、查询数据库或发送邮件。

在 TypeScript 中，我们利用 Zod 库来定义严格的输入输出模式，这不仅保证了类型安全，还Neng让 LLM geng清楚地理解如何调用这些函数。

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import * as z from 'zod';
// 初始化服务器
const server = new McpServer;
// 注册一个名为 "calculate-bmi" 的工具
server.registerTool(
  'calculate-bmi',
  {
    title: 'BMI Calculator',
    description: '根据身高和体重计算身体质量指数',
    // 使用 Zod 定义输入验证规则
    inputSchema: z.object({
      weightKg: z.number.describe,
      heightM: z.number.describe
    }),
    outputSchema: z.object })
  },
  async  => {
    // 实际的计算逻辑
    const bmi = weightKg / ;
    return {
      content: ,
      // 返回结构化数据，方便 LLM 解析
      structuredContent: { bmi }
    };
  }
);

kan到这段代码，你可Neng会感叹 TypeScript 的优雅。通过 Zod 的描述，我们不仅完成了代码层面的验证，实际上也为 AI 生成了一份清晰的“使用说明书”。

2. Resources：数据的蓄水池

有时候，AI 不需要执行操作，只需要读取数据。这就是 Resources 存在的意义。资源Ke以是任何形式的数据：配置文件、日志、数据库记录，甚至是图片。客户端不仅Ke以读取资源，还Ke以订阅变geng，实现类似“热geng新”的效果。

比如我们想暴露一个应用的配置文件给 AI：

server.registerResource(
  'config://app',
  {
    title: 'App Config',
    description: '应用的核心配置参数',
    mimeType: 'application/json'
  },
  async  => ({
    contents: 
  })
);

在客户端，我们Ke以像浏览文件一样浏览这些资源：

// 列出所有可用资源
const { resources } = await client.listResources;
// 读取特定 URI 的内容
const { contents } = await client.readResource;
// 订阅资源变geng
await client.subscribeResource;
client.setNotificationHandler => {
  console.log;
});

3. Prompts：提示词的模板化

Ru果你厌倦了每次dou手写“请帮我审查这段代码...”，那么 Prompts 功Neng绝对是你的福音。它允许服务器预定义提示模板，客户端只需填充参数即可。

这对于标准化工作流非常有用。例如定义一个代码审查的模板：

server.registerPrompt(
  'review-code',
  {
    title: 'Code Review',
    description: '根据Zui佳实践审查代码质量',
    argsSchema: z.object({
      code: z.string.describe
    })
  },
   => ({
    messages: 
  })
);

客户端调用时只需传入代码，剩下的“废话”dou由模板自动补全。

4. Sampling：借 LLM 之火

这是一个非常高级且有趣的功Neng。通常情况下是客户端请求 LLM，然后客户端请求 MCP Server。但MCP Server 自身也需要 LLM 的Neng力。比如Server 收到一个复杂的文本，需要先进行才Neng存入数据库。

Sampling 允许服务器向客户端“借用” LLM 的推理Neng力。

server.registerTool(
  'summarize',
  { inputSchema: z.object }) },
  async  => {
    // 服务器请求客户端进行 LLM 推理
    const response = await ctx.mcpReq.requestSampling({
      messages: ,
      maxTokens: 100
    });
    return { 
      content:  
    };
  }
);

5. Elicitation：与人类交互

有时候，AI 遇到了它无法决定的事情，比如需要用户确认一个敏感操作，或者选择一个具体的参数。Elicitation 允许服务器主动向客户端请求用户输入。

const result = await ctx.mcpReq.elicitInput({
  mode: 'form',
  message: '请对以下内容进行评分：',
  requestedSchema: {
    type: 'object',
    properties: {
      rating: { type: 'integer', minimum: 1, maximum: 5 }
    },
    required: 
  }
});

客户端需要处理这种请求，弹出一个表单或对话框，然后将用户的输入返回给服务器。

三、 传输层：搭建沟通的桥梁

有了Neng力和数据，还需要通道。MCP SDK 提供了多种传输方式，以适应不同的部署场景。

1. Stdio：本地开发的Zui佳拍档

对于本地开发工具，Stdio 是Zui简单、Zui高效的方式。服务器作为子进程启动，通过标准输入输出与父进程通信。

服务器端设置：

import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
const transport = new StdioServerTransport;
await server.connect;

客户端设置：

import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
const transport = new StdioClientTransport({ 
  command: 'node', 
  args:  
});
await client.connect;

2. Streamable HTTP：远程部署的首选

当你的服务器需要部署在远程时Stdio 就不适用了。这时Streamable HTTP 传输层闪亮登场。它支持双向流式通信，非常适合 Web 环境。

import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
const transport = new StreamableHTTPClientTransport(
  new URL
);
await client.connect;

四、 安全与认证：守护大门

在开放的世界里安全永远是第一位的。MCP SDK 内置了对 OAuth 等认证机制的支持。通过 ClientCredentialsProvider，我们Ke以轻松地为客户端请求添加凭证。

import { ClientCredentialsProvider } from '@modelcontextprotocol/sdk/client/index.js';
const authProvider = new ClientCredentialsProvider({
  clientId: 'my-service-client',
  clientSecret: 'super-secret-key'
});
const transport = new StreamableHTTPClientTransport(
  new URL,
  { authProvider } // 将认证提供者注入传输层
);

五、 错误处理：优雅地应对失败

网络是不稳定的，代码是有 Bug 的。SDK 提供了明确的错误类型来帮助我们区分问题。

ProtocolError协议层面的错误，比如消息格式不对、版本不匹配等。

SdkErrorSDK 内部逻辑的错误，比如连接超时、序列化失败等。

在编写代码时务必使用 try-catch 块来捕获这些异常，并给用户提供友好的反馈。

try {
  const result = await client.callTool({
    name: 'calculate-bmi',
    arguments: { weightKg: 70, heightM: 1.75 }
  });
  console.log;
} catch  {
  if  {
    console.error;
  } else {
    console.error;
  }
}

六、 ：构建未来的 AI 生态

MCP TypeScript SDK 不仅仅是一个库，它代表了一种新的设计哲学：标准化、模块化、可组合。通过将 AI 的Neng力与外部世界的工具解耦，我们不再受限于单一模型的封闭生态。

从定义工具、暴露资源，到处理复杂的双向交互，SDK 提供了完善且类型安全的支持。无论你是想打造下一个杀手级的 AI 辅助编程工具，还是想为企业内部构建智Neng知识库，MCP dou是你值得信赖的基石。

技术的浪潮滚滚向前，不要只Zuo岸上的观望者。拿起 MCP TypeScript SDK，去连接、去创造、去打破那些kan似坚不可摧的壁垒吧。毕竟未来的 AI 应用，不应该只是会聊天的机器人，而应该是Neng理解世界、并Neng改变世界的智Neng体。

---