mcp-for-beginners 实战:使用 TypeScript 编写并运行自己的 MCP 客户端

原创2026-10-10 13:33:181,959 阅读
文章标签:教程示例工程MCP 服务MCP Clients人工智能

mcp-for-beginners 实战:使用 TypeScript 编写并运行自己的 MCP 客户端

本指南以开源课程 mcp-for-beginners 中 03-GettingStarted/02-client/solution/typescript 解决方案为骨架,完整讲解如何基于 @modelcontextprotocol/sdk 编写一个可通过 stdio 传输协议与 MCP Server 通信的 TypeScript 客户端。你将掌握客户端与传输对象的创建、服务器能力(Prompts / Resources / Tools)的发现与调用、项目的构建与运行,并能独立看懂客户端与服务端之间的调用关系与输出结果。

文档定位:一个开箱即用的客户端解决方案

课程 Creating a client 的核心观点是:客户端是直接与 MCP Server 通信、请求资源、工具和提示词的自定义应用或脚本。与 MCP Inspector 这类图形化交互工具不同,自研客户端可以实现可编程、自动化的交互,让开发者把 MCP 能力集成进自己的工作流。

translations/de/03-GettingStarted/02-client/solution/typescript/README.md(即本文依据的德语版解决方案说明,英文原版见 typescript/README.md)给出了该 TypeScript 客户端的完整运行指引,其运行链路为:

npm install → npm run build(编译并启动 Server) → npm run client(编译并启动 Client)

解决方案目录同时包含客户端代码与服务端代码两个部分(服务端实为上一章 01-first-server 的同款演示服务器),因此你可以在一对项目里直观看到 MCP 请求的完整闭环。

解决方案结构一览

先看 solution/typescript 目录的组织方式(对照 solution/README.md 中的多语言结构说明):

typescript/
├── package.json     # 依赖与 npm scripts
├── package-lock.json
├── tsconfig.json    # TypeScript 编译配置
└── src/
    ├── index.ts     # MCP Server:add 工具、file 资源模板、review-code 提示词
    └── client.ts    # MCP Client:连接、发现并调用上述能力

两个关键配置文件:

  • package.json 声明了模块类型与脚本:
    {
        "type": "module",
        "scripts": {
            "build": "tsc && node ./build/index.js",
            "client": "tsc && node ./build/client.js",
            "inspector": "npx @modelcontextprotocol/inspector node build/index.js"
        },
        "dependencies": {
            "@modelcontextprotocol/sdk": ">=1.26.0",
            "type": "^2.7.3",
            "uuid": "^14.0.0",
            "zod": "^3.24.2"
        }
    }
    
    @modelcontextprotocol/sdk 是官方 TypeScript SDK(锁文件中解析到的具体版本为 1.26.0,见 package-lock.json),zod 用于在服务端定义参数 Schema。
  • tsconfig.json 指定编译目标 ES2022、模块方案 Node16、输出目录 ./build,源码目录 ./src。build 与 client 两个脚本都会先执行 tsc,把 src/ 下的 TypeScript 编译为 build/ 下的 JavaScript,再交由 Node 运行。

第 0 步:前置准备(可选)

德语版文档特别注明:"Es wird empfohlen, uv zu installieren, aber es ist nicht zwingend erforderlich"——即推荐安装 uv,但并非强制。uv 是一个快速 Python 包管理器,本示例主要依赖 Node.js 生态,因此即使不安装 uv 也完全不影响运行。你需要确认本机具备:

  • Node.js(建议 18+,SDK 依赖中 @hono/node-server 即要求 >=18.14.1)
  • npm(随 Node.js 分发)

第 1 步:安装依赖

在 typescript 目录下执行:

npm install

该命令依据 package.json 与 package-lock.json 安装全部运行时依赖(SDK、zod、uuid 等)与开发依赖(TypeScript、@types/node 等)。安装完成后,node_modules 中即包含 @modelcontextprotocol/sdk,客户端与服务端代码所需的导入均可解析。

第 2 步:构建并启动服务器

npm run build

该脚本实际执行 tsc && node ./build/index.js,先编译 src/index.ts,再直接启动 MCP Server。服务器通过 StdioServerTransport 在标准输入/输出上收发 JSON-RPC 消息:

const transport = new StdioServerTransport();
await server.connect(transport);

从源码结构看,这个服务器对外暴露了三种能力(与上一章 01-first-server/solution/typescript/src/index.ts 完全一致):

  1. 工具 add:接收两个数字 a、b,返回其和的文本结果。参数 Schema 用 zod 声明:
    server.tool("add",
      { a: z.number(), b: z.number() },
      async ({ a, b }) => ({
        content: [{ type: "text", text: String(a + b) }]
      })
    );
    
  2. 动态资源模板 file:匹配 file://{path} 形式的 URI,返回一段文本:
    server.resource(
      "file",
      new ResourceTemplate("file://{path}", { list: undefined }),
      async (uri, { path }) => ({ contents: [{ uri: uri.href, text: `File, ${path}!` }] })
    );
    
  3. 提示词 review-code:接收一段代码字符串,生成一条要求评审该代码的用户消息:
    server.prompt(
      "review-code",
      { code: z.string() },
      ({ code }) => ({
        messages: [{ role: "user", content: { type: "text", text: `Please review this code:\n\n${code}` } }]
      })
    );
    

注意:npm run build 启动服务器后进程会保持运行,等待来自 stdin 的客户端连接。建议另开一个终端执行下一步的客户端命令。

第 3 步:运行客户端

npm run client

该脚本实际执行 tsc && node ./build/client.js。客户端在编译后启动,并通过 stdio 自动拉起服务器子进程完成握手。

客户端源码逐段解析

src/client.ts 是本次示例的核心,共分四个阶段。

阶段一:导入并创建传输与客户端

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

const transport = new StdioClientTransport({
  command: "node",
  args: ["./build/index.js"]
});

const client = new Client(
  {
    name: "example-client",
    version: "1.0.0"
  }
);

await client.connect(transport);
  • 传输对象:StdioClientTransport 是"进程间"传输,它通过 command/args 指定如何启动服务器子进程(这里为 node ./build/index.js),并在两者之间建立 stdin/stdout 管道。
  • 客户端实例:Client 需要 name 与 version,用于 MCP 协议握手阶段的客户端标识。
  • 连接:await client.connect(transport) 完成初始化握手,此后即可发起请求。这正是课程主文档 02-client/README.md 中强调的"客户端可以自己拉起服务器,也可以连接已运行的服务器"的能力。

阶段二:发现并调用提示词

const prompts = await client.listPrompts();
const prompt = await client.getPrompt({
  name: "review-code",
  arguments: {
    code: "console.log(\"hello\");"
  }
});
console.log("Prompt: ", prompt.messages[0].content);

先通过 listPrompts() 发现服务器注册的提示词,再用 getPrompt({ name, arguments }) 按名调用。这里调用的是服务端定义的 review-code,code 参数值会拼进服务端返回的提示词模板,因此输出为:

Prompt:  {
  type: 'text',
  text: 'Please review this code:\n\nconsole.log("hello");'
}

阶段三:列出资源与资源模板

const resources = await client.listResources();
for(let resource in resources.resources) {
  console.log("Resource: ", resource);
}

const templates = await client.listResourceTemplates();
for(let template of templates.resourceTemplates) {
  console.log("Resource template: ", template.name);
}

listResources() 返回服务器已声明的静态资源列表;listResourceTemplates() 返回可动态匹配的模板。服务端 file://{path} 是一个资源模板,因此客户端输出:

Resource template:  file

阶段四:调用工具

const result = await client.callTool({
  name: "add",
  arguments: {
    a: 1,
    b: 8
  }
});
console.log("Tool result: ", result);

callTool({ name, arguments }) 按名称与参数调用服务端工具。此处调用 add,传入 a=1、b=8,服务端计算后返回 9,因此输出:

Tool result:  { content: [ { type: 'text', text: '9' } ] }

预期输出与结果解读

德语版文档给出了运行 npm run client 后应看到的完整输出:

Prompt:  {
  type: 'text',
  text: 'Please review this code:\n\nconsole.log("hello");'
}
Resource template:  file
Tool result:  { content: [ { type: 'text', text: '9' } ] }

逐行对照:

输出 来源
Prompt: { type: 'text', text: 'Please review this code:...' } getPrompt("review-code", { code }) 的返回内容
Resource template: file listResourceTemplates() 中的模板名 file
Tool result: { content: [ { type: 'text', text: '9' } ] } callTool("add", { a: 1, b: 8 }) 的结果,1 + 8 = 9

可以看到,客户端输出的每一部分都能在服务端 src/index.ts 中找到对应定义——这正是验证"客户端 ↔ 服务器"契约一致性的最直接方式。若输出与上述不一致,可优先核对工具名、参数名是否与服务端声明完全一致。

交叉验证:更完整的 TypeScript 客户端示例

在 02-client/client_example_typescript.ts 中还提供了一个功能更完整的 TypeScript 客户端参考实现,可作为本解决方案的延伸学习。它在基础连接之外还演示了:

  • 通过 listTools() 列出服务器全部工具及其描述;
  • 依次调用 add、subtract、multiply、divide、help 等计算器工具;
  • 通过 extractTextResult() 从 content 数组中提取 type: "text" 的文本结果;
  • 对 listResources()/readResource() 与 listPrompts()/getPrompt() 使用 try/catch 容错处理(服务器未实现这些能力时优雅降级)。

该文件的运行方式与解决方案一致(npm run build 后 npm run client),其多语言运行说明与排错建议可参见 complete_examples.md。

多语言对照:TypeScript 客户端的定位

课程解决方案按语言组织(见 solution/README.md),TypeScript 方案与 Python、.NET、Java、Rust 方案解决同一问题。核心差异在于传输与异步模型,可对照 complete_examples.md 中的对比表:

语言 传输 服务器启动 异步模型 关键库
TypeScript Stdio 自动拉起 Async/Await Node MCP SDK
Python Stdio 自动拉起 AsyncIO Python MCP SDK
.NET Stdio 自动拉起 Async/Await .NET MCP SDK
Java SSE/HTTP 外部启动 Sync WebFlux、MCP SDK
Rust Stdio 自动拉起 Async/Await Rust MCP SDK、Tokio

TypeScript 客户端与 Python 客户端(solution/python/README.md)在思路上高度相似:都是"创建传输 → 建立会话 → 列出并调用能力",只是 API 命名不同(TypeScript 为 listResources/callTool,Python 为 list_resources/call_tool)。如果你已经熟悉其中一种,迁移到另一种的成本很低。

常见问题排查

结合 complete_examples.md 的排错清单,运行本示例时可能遇到:

  1. Module not found:npm install 未成功或未在 typescript 目录下执行,请确认 node_modules 中存在 @modelcontextprotocol/sdk。
  2. 连接失败/无输出:npm run build 启动的服务器进程可能已退出或被占用;StdioClientTransport 的 command/args 需能正确解析到 build/index.js。
  3. Tool not found:callTool 中的 name 与服务器注册名不一致(例如把 add 写成了 Add)。MCP 工具名区分大小写,必须以服务器声明为准。
  4. 参数校验失败:add 工具的 a/b 必须是数字;服务端 zod Schema(z.number())会在类型不匹配时拒绝请求。
  5. 调试建议:可先用 MCP Inspector 验证服务器能力(package.json 中已内置 npm run inspector),再运行客户端,便于区分问题出在服务端还是客户端。

后续进阶

本示例的客户端是"显式调用"式的——每次调用工具、资源或提示词都需要在代码中写死。在真实场景中,用户更希望用自然语言与系统交互。课程的下一章 Creating a client with an LLM 会在此基础上为客户端接入大语言模型:客户端先列出服务器能力并保存其 Schema,再把能力以 LLM 可理解的格式注入提示,从而让用户用自然语言驱动 MCP 服务器,这正是从"脚本化客户端"走向"智能体客户端"的关键一步。

关键要点

  • 客户端既能发现(list)服务器能力,也能调用(call)服务器能力,是验证服务器功能的最佳手段之一。
  • StdioClientTransport 通过 command/args 自动拉起服务器子进程,因此本示例可以"一条命令"完成端到端验证;客户端同样支持连接已运行的服务器。
  • 客户端输出的每一项(Prompt / Resource template / Tool result)都能在服务端源码中找到对应注册,契约一致性是可验证、可测试的。
登录后查看全文
mcp-for-beginners