mcp-for-beginners 实战:使用 TypeScript 编写并运行自己的 MCP 客户端
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 完全一致):
- 工具
add:接收两个数字a、b,返回其和的文本结果。参数 Schema 用 zod 声明:server.tool("add", { a: z.number(), b: z.number() }, async ({ a, b }) => ({ content: [{ type: "text", text: String(a + b) }] }) ); - 动态资源模板
file:匹配file://{path}形式的 URI,返回一段文本:server.resource( "file", new ResourceTemplate("file://{path}", { list: undefined }), async (uri, { path }) => ({ contents: [{ uri: uri.href, text: `File, ${path}!` }] }) ); - 提示词
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 的排错清单,运行本示例时可能遇到:
Module not found:npm install未成功或未在typescript目录下执行,请确认node_modules中存在@modelcontextprotocol/sdk。- 连接失败/无输出:
npm run build启动的服务器进程可能已退出或被占用;StdioClientTransport的command/args需能正确解析到build/index.js。 Tool not found:callTool中的name与服务器注册名不一致(例如把add写成了Add)。MCP 工具名区分大小写,必须以服务器声明为准。- 参数校验失败:
add工具的a/b必须是数字;服务端 zod Schema(z.number())会在类型不匹配时拒绝请求。 - 调试建议:可先用 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)都能在服务端源码中找到对应注册,契约一致性是可验证、可测试的。