Model Context Protocol TypeScript SDK 基本用法指南

本文将介绍 Model Context Protocol (MCP) TypeScript SDK 的基本概念和用法，帮助您快速上手构建基于 MCP 的客户端和服务器。

背景

Model Context Protocol (MCP) 是一种开放标准协议，旨在规范大型语言模型 (LLM) 与外部工具、API 和数据源的交互方式。它提供了一套统一的接口，让 AI 应用能够发现、调用和利用各种外部能力。

@modelcontextprotocol/typescript-sdk 是 MCP 协议的官方 TypeScript 实现，为开发者提供了在 Node.js 和浏览器环境中构建 MCP 客户端和服务端的完整工具集。无论您是想将自己的工具集成到 AI 生态中，还是想让您的 AI 应用消费外部能力，这个 SDK 都将是您的得力助手。

参考链接：modelcontextprotocol/typescript-sdk on GitHub

安装

要开始使用 SDK，您可以通过 npm 或 yarn 将其添加到您的项目中：

npm install @modelcontextprotocol/sdk zod

zod 是一个强大的 TypeScript 优先的 schema 声明和验证库，MCP SDK 用它来定义工具的输入和输出结构，因此建议一同安装。

基本用法

下面我们将分别介绍如何创建一个 MCP 服务端和客户端。

1. 创建 MCP 服务端

MCP 服务端负责定义和暴露可供客户端使用的资源（Resources）、工具（Tools）和提示（Prompts）。

以下是一个简单的服务端示例，它通过标准输入/输出（Stdio）与客户端通信。

server.ts

import { McpServer } from "@modelcontextprotocol/sdk/server";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio";
import { z } from "zod";

// 1. 初始化 MCP 服务器
const server = new McpServer({
  name: "example-server",
  version: "1.0.0",
});

// 2. 添加资源
// 资源是服务器可以提供给客户端的静态数据。
server.addResource({
  name: "static-data",
  description: "一些静态 JSON 数据",
  value: { foo: "bar", baz: [1, 2, 3] },
});

// 3. 添加工具
// 工具是服务器暴露给客户端的可执行函数。
// 我们使用 zod 来定义工具的输入和输出 schema。
server.addTool({
  name: "greet",
  description: "生成一句问候语",
  input: z.object({
    name: z.string().describe("要问候的人名"),
  }),
  output: z.object({
    message: z.string().describe("生成的问候语"),
  }),
  execute: async ({ name }) => {
    return {
      message: `你好, ${name}!`,
    };
  },
});

// 4. 添加提示
// 提示是预定义的、可供客户端获取的模板。
server.addPrompt({
    name: "hello-world",
    description: "一个简单的 Hello World 提示",
    prompt: "你好，世界！"
})

// 5. 启动服务器并监听连接
const transport = new StdioServerTransport();
server.connect(transport);

console.log("MCP Server is running. Waiting for client connection...");

要运行此服务器，只需执行：

node server.js

2. 创建 MCP 客户端

MCP 客户端连接到服务端，并可以消费其提供的资源、工具和提示。

以下是一个连接到上述服务端的客户端示例。

client.ts

import { Client } from "@modelcontextprotocol/sdk/client";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio";

async function main() {
  // 1. 初始化客户端
  const client = new Client({
    name: "example-client",
    version: "1.0.0",
  });

  // 2. 设置与服务端通信的传输方式
  // 这里使用 StdioClientTransport 与我们之前创建的 server.js 通信
  const transport = new StdioClientTransport({
    command: "node",
    args: ["server.js"],
  });

  // 3. 连接到服务器
  await client.connect(transport);
  console.log("成功连接到 MCP Server!");

  // 4. 与服务器交互
  
  // 列出所有可用的提示
  const prompts = await client.listPrompts();
  console.log("可用的提示:", prompts);

  // 获取特定提示的内容
  const prompt = await client.getPrompt({ name: 'hello-world' });
  console.log("获取 'hello-world' 提示:", prompt);

  // 列出所有可用的资源
  const resources = await client.listResources();
  console.log("可用的资源:", resources);

  // 读取特定资源的内容
  const resource = await client.readResource({ name: "static-data" });
  console.log("读取 'static-data' 资源:", resource);

  // 调用工具
  const toolResult = await client.callTool({
    name: "greet",
    arguments: {
      name: "MCP 用户",
    },
  });
  console.log("调用 'greet' 工具:", toolResult);

  // 5. 断开连接
  await client.disconnect();
  console.log("与服务器断开连接。");
}

main().catch(console.error);

运行客户端：

node client.js

您将看到客户端成功连接到服务器，并依次列出、获取和调用了服务器上定义的提示、资源和工具。

总结

@modelcontextprotocol/typescript-sdk 提供了一套强大而灵活的工具，让开发者可以轻松地将各种功能和服务集成到 AI 应用中。通过定义清晰的资源、工具和提示，您可以构建出功能丰富、可扩展性强的 MCP 应用。

希望本指南能帮助您入门。更多高级用法，如不同的传输协议（HTTP/SSE）、身份验证、流式传输等，请查阅 官方 GitHub 仓库。