ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

mcp-for-beginners 实战:用 TypeScript 与 MCP SDK 构建计算器服务器(工具注册、Zod 校验与 stdio 传输全解析)

mcp-for-beginners 实战:用 TypeScript 与 MCP SDK 构建计算器服务器(工具注册、Zod 校验与 stdio 传输全解析) 教程文档人工智能【免费下载链接】mcp-for-beginnersThis open-source curriculum introduces the fundamentals of Model Context Protocol (MCP) through real-world, cross-language examples in .NET, Java, TypeScript, JavaScript, Rust and Python. Designed for developers, it focuses on practical techniques for building modular, scalable, and secure AI workflows from session setup to service orchestration.项目地址https://gitcode.com/GitHub_Trending/mc/mcp-for-beginners点击查看免费下载这篇技术指南以 mcp-for-beginners 开源课程中的 TypeScript 示例为蓝本完整讲解如何使用modelcontextprotocol/sdk与zod从零构建一个基于 stdio 传输的 MCP 计算器服务器。读完本文你将掌握 MCP Server 的标准工程结构McpServer实例、server.tool工具注册、内容响应与错误处理、TypeScript 项目的编译与运行配置以及如何借助 MCP Inspector 和自写客户端对服务器进行验证。示例定位Getting Started 模块的 TypeScript 计算器在 03-GettingStarted 模块 中课程为每一种主流语言都配套了可直接运行的计算器示例TypeScript 版本位于 03-GettingStarted/samples/typescript/与 Java、.NET、JavaScript、Python、Rust 的同名示例一一对应用于巩固第一课 “你的第一个 MCP Server” 中讲解的工具Tools概念。该示例的核心代码非常精简一个McpServer实例、四个算术工具add、subtract、multiply、divide以及一个 stdio 传输连接。它演示了 MCP TypeScript 开发中三个最关键的基础能力使用官方 SDK 创建并命名一个 MCP Server用server.tool()注册带 Zod 参数模式的工具通过StdioServerTransport让服务器在标准输入/输出上接收和发送 JSON-RPC 消息。项目结构与工程配置先看整个示例的目录布局03-GettingStarted/samples/typescript/ ├── README.md # 示例说明本文的主体文档 ├── package.json # 依赖与 npm 脚本 ├── package-lock.json # 依赖锁定文件 ├── tsconfig.json # TypeScript 编译配置 └── src/ └── index.ts # 服务器唯一入口源码package.json依赖与脚本package.json 中的关键配置如下{ name: tutorial-mcp, version: 1.0.0, main: index.js, type: module, scripts: { start: tsc node ./build/index.js, build: tsc node ./build/index.js }, dependencies: { modelcontextprotocol/sdk: 1.26.0, openai: ^4.95.0, zod: ^3.24.2 }, devDependencies: { types/node: ^22.13.17, typescript: ^5.8.2 } }逐项解读type: module声明项目使用 ES Module 规范这也是源码中import语句能直接使用.js扩展名导入 SDK 子路径如modelcontextprotocol/sdk/server/mcp.js的前提。modelcontextprotocol/sdk1.26.0MCP 官方 TypeScript SDK提供McpServer、StdioServerTransport、Client等核心构造。zod^3.24.2运行时 schema 校验库用于声明工具的输入参数结构SDK 会将这些 Zod schema 自动转换为 MCP 协议要求的 JSON Schema供客户端或 LLM发现与调用。openai^4.95.0从源码结构看src/index.ts 当前并未引用该依赖它是为后续把客户端接入 LLM如 03-llm-client 课程预留的。start/build脚本二者逻辑相同均为tsc node ./build/index.js——先编译 TypeScript再直接运行编译产物。这意味着示例文档中的npm start实际等价于“编译 启动”。tsconfig.json编译目标tsconfig.json 的编译配置与 01-first-server 课程中的工程模板完全一致{ compilerOptions: { target: ES2022, module: Node16, moduleResolution: Node16, outDir: ./build, rootDir: ./src, strict: true, esModuleInterop: true, skipLibCheck: true, forceConsistentCasingInFileNames: true }, include: [src/**/*], exclude: [node_modules] }关键点outDir: ./build、rootDir: ./src源码从src/编译到build/因此index.ts编译后成为build/index.js这正是 npm 脚本与 Inspector 命令所指向的文件。module/moduleResolution: Node16与type: module配套让 Node.js 以 ESM 方式解析node build/index.js中的导入。strict: true开启严格类型检查符合工程化最佳实践。核心实现从 SDK 到四个算术工具示例文档展示的“计算器部分”直接取自 src/index.ts 的完整源码。下面按代码逻辑逐层展开。创建 McpServer 实例// mcp_calculator_server.ts - Sample MCP Calculator Server implementation in TypeScript import { McpServer } from modelcontextprotocol/sdk/server/mcp.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { z } from zod; // Create an MCP server const server new McpServer({ name: Calculator MCP Server, version: 1.0.0 });McpServer来自 modelcontextprotocol/sdk/server/mcp.js 所引用的官方 TypeScript SDK它封装了协议层的握手、能力声明与方法分发开发者只需关注业务注册。name与version会在协议初始化阶段通过initialize响应返回给客户端MCP Inspector 的服务器信息面板中即可看到。用server.tool()注册四个计算工具示例文档给出的工具注册代码正是本示例的核心资产// Define calculator tools for each operation server.tool( add, { a: z.number(), b: z.number() }, async ({ a, b }) ({ content: [{ type: text, text: String(a b) }] }) ); server.tool( subtract, { a: z.number(), b: z.number() }, async ({ a, b }) ({ content: [{ type: text, text: String(a - b) }] }) ); server.tool( multiply, { a: z.number(), b: z.number() }, async ({ a, b }) ({ content: [{ type: text, text: String(a * b) }] }) ); server.tool( divide, { a: z.number(), b: z.number() }, async ({ a, b }) { if (b 0) { return { content: [{ type: text, text: Error: Cannot divide by zero }], isError: true }; } return { content: [{ type: text, text: String(a / b) }] }; } );server.tool()的签名由三部分组成理解它是掌握 MCP TypeScript 开发的关键工具名称第一个参数如add、divide客户端调用tools/call时需精确匹配该名称。输入 schema第二个参数由zod声明的对象模式。z.number()表示参数必须是数字SDK 会自动将其序列化为符合 MCP 规范的 JSON SchemalistTools返回的结果中即可看到每个工具的inputSchema。这也是 MCP 得以让 LLM“看懂”工具边界的基础——模型依据 schema 决定填入什么参数。执行回调第三个参数接收已通过校验的入参返回 MCP 内容结果。注意返回结构是{ content: [{ type: text, text: String(a b) }] }其中content是一个内容块数组{ type: text, text: ... }是文本块的标准形态客户端最终会把text内容呈现给用户或 LLM。错误处理isError标志divide工具演示了 MCP 语义化的错误返回方式if (b 0) { return { content: [{ type: text, text: Error: Cannot divide by zero }], isError: true }; }当除数为零时工具并不抛异常而是返回一个带isError: true的常规结果。该标志会在协议层被标记为工具执行错误客户端与 LLM 可以据此识别“调用失败但服务器未崩溃”的情况。这是 MCP 工具开发中非常重要的实践参数校验失败、业务异常都应优先考虑isError返回而不是让进程崩溃。stdio 传输本地服务器的运行骨架工具的注册只是“业务层”要让服务器真正工作还必须挂载传输。源码末尾的两行是关键// Connect the server using stdio transport const transport new StdioServerTransport(); server.connect(transport).catch(console.error); console.log(Calculator MCP Server started);StdioServerTransport让服务器通过标准输入读取 JSON-RPC 请求、通过标准输出写回响应。正如 03-GettingStarted 模块 第 5 课所述stdio 是本地 MCP 服务器与客户端通信的推荐标准它基于子进程通信自带进程隔离适合运行在本机的服务器场景。server.connect(transport)返回的 Promise 需要被catch兜底避免未处理的拒绝导致进程异常退出。console.log输出会混入 stdout而 stdout 已被 stdio 传输占用为协议通道因此生产实践中更推荐把日志写到 stderr这一点在 01-first-server 课程 的 TypeScript 示例中可以看到其main()内使用console.error(MCPServer started on stdin/stdout)。安装与运行示例文档给出了最简的两步操作它们基于上文分析的工程配置可直接落地# 1. 安装依赖下载 MCP SDK、zod 等 npm install # 2. 编译并启动服务器 npm startnpm start实际执行的是tsc node ./build/index.js即tsc依据tsconfig.json将src/index.ts编译为build/index.jsnode ./build/index.js启动服务器并挂载 stdio 传输。如果你只想编译不运行可单独执行npx tsc修改源码后重新npm start即可完成重编译。启动成功后终端会打印Calculator MCP Server started此时进程处于“等待标准输入消息”的阻塞状态——这正是 stdio 服务器的正常形态它本身不会打印日志输出结果而是要等客户端如 Inspector 或自写客户端发起请求。验证与调试Inspector 与自写客户端使用 MCP Inspector 交互测试MCP Inspector 是课程推荐的图形化调试工具。参照 01-first-server 课程 中 TypeScript 的启动方式对本示例可运行npx modelcontextprotocol/inspector node build/index.jsInspector 会用给定的命令拉起服务器进程随后在浏览器中打开本地 Web 界面。连接成功后在Tools → List Tools中应能看到add、subtract、multiply、divide四个工具选中任一工具填入参数并点击运行即可实时看到结果。例如选中divide并输入a1, b2返回内容为1 / 2 0.5除法结果工具列表与运行效果如下图所示连接建立阶段Inspector 左侧配置区会显示传输类型STDIO与启动命令连接成功后界面左下角出现绿色Connected标识用自写客户端做编程化验证除了图形界面课程 02-client编写客户端 展示了编程化验证服务器的方式。参照其中的 TypeScript 客户端模式可以写一个最小客户端连接本示例import { Client } from modelcontextprotocol/sdk/client/index.js; import { StdioClientTransport } from modelcontextprotocol/sdk/client/stdio.js; // 用 node 拉起我们的计算器服务器 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); // 列出服务器暴露的工具 const tools await client.listTools(); // 调用 add 工具 const result await client.callTool({ name: add, arguments: { a: 5, b: 3 } });注意两点StdioClientTransport的command/args必须与服务器的启动方式一致本示例即node build/index.js先npm start前的编译产物。listTools返回的 schema 中可以看到每个工具的inputSchema这正是zod声明被协议化的直接证据add的参数为{ a: number, b: number }。扩展方向资源、提示词与多语言对照本示例聚焦“工具Tools”这一 MCP 原语而一个完整的 MCP Server 通常还包括资源Resources与提示词Prompts。如果你希望在此基础上继续深化参考 01-first-server 课程 的完整 TypeScript 服务器它额外演示了server.resource()如greeting://{name}动态资源模板与server.prompt()如review-code代码审查提示词的注册方式并给出了可一键复制的 完整解决方案。对照同一计算器在不同语言下的实现可快速理解 MCP 的“一次掌握、多语言复用”特性Java 计算器、.NET 计算器、JavaScript 计算器、Python 计算器 与 Rust 计算器。小结TypeScript 计算器示例虽短却浓缩了 MCP 服务器开发的完整链路McpServer实例化 →zod驱动的工具 schema →server.tool()注册 →StdioServerTransport挂载 → Inspector/客户端验证。理解这套骨架后你可以把add/divide替换为任意业务工具读取文件、查询数据库、调用远程 API并按照 01-first-server 与 02-client 的课程路径逐步构建出资源、提示词齐备的生产级 MCP Server。赞分享教程文档人工智能【免费下载链接】mcp-for-beginnersThis open-source curriculum introduces the fundamentals of Model Context Protocol (MCP) through real-world, cross-language examples in .NET, Java, TypeScript, JavaScript, Rust and Python. Designed for developers, it focuses on practical techniques for building modular, scalable, and secure AI workflows from session setup to service orchestration.项目地址https://gitcode.com/GitHub_Trending/mc/mcp-for-beginners点击查看免费下载相关推荐.NET 9 构建 MCP stdio 服务器实战传输机制、工具实现与 MCP Inspector 调试指南mcp-for-beginners.NET 9 构建 MCP stdio 服务器实战传输机制、工具实现与 MCP Inspector 调试指南mcp for beginners 本文以 m教程文档人工智能mcp-for-beginners Rust 实战使用 rmcp 构建基于 stdio 的 MCP 计算器服务器mcp for beginners Rust 实战使用 rmcp 构建基于 stdio 的 MCP 计算器服务器 本篇技术指南以 mcp for beginn教程文档人工智能使用 JavaScript 与 TypeScript SDK 构建第一个 MCP 计算器服务器mcp-for-beginners 实战指南使用 JavaScript 与 TypeScript SDK 构建第一个 MCP 计算器服务器mcp for beginners 实战指南 本篇技术指南以 m教程文档人工智能创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表