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

发布时间:2026/10/3 22:40:58

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),仅供参考
延伸阅读

更多相关文章

2026/10/3 22:40:58

Fastjson 漏洞 · 04 · 绕过军备竞赛:1.2.25 → 1.2.83

这一篇是本系列的核心:从"默认能打"到"越来越难打",每一个补丁改了什么、攻击者怎么绕、为什么最终必须放弃 1.x 的 autoType 模型。所有结论都对应配套靶场的实测矩阵(lab/fastjson-lab/verify-output.txt)引…

2026/10/3 23:21:00

PostgreSQL空间排查指南:从表大小到WAL与死元组

某天凌晨,监控告警把值班手机震到发烫:磁盘使用率飙到93%,业务日志里全是“could not extend file”的报错。第一反应是赶紧找出哪张表在疯涨,但用psql敲了几条SQL之后发现,统计出来的库大小加起来只有磁盘占用的一半不…

2026/10/3 23:20:59

QGIS快速标注按钮:从字段选择到出图全流程解析

做GIS的应该都有过这种经历:领导说“把图斑名字标出来”,常规操作是先打开图层属性,翻到“标注”选项卡,勾上“标注该图层”,再选字段、调字体、调位置,一套流程下来时间没少花。后来我用QGIS时&#xff0c…

2026/10/3 23:20:59

Bibliometrix安装配置全攻略:从R环境搭建到Biblioshiny可视化分析

第一次用Bibliometrix做文献计量分析的时候,我差点被安装这关劝退。倒不是这个R包本身多难装,而是网上教程大多只丢一句install.packages("bibliometrix"),然后就默认你能跑通。真到自己动手,R版本不匹配、依赖包编译失…

2026/10/3 23:20:59

Android Intent传值避坑指南:正确获取参数的5种方式与常见问题

避坑指南:正确获取Intent传递的值,这几种方式我全给你捋明白了 做Android开发,谁还没跟Intent打过交道?启动Activity、传参数、接收返回值、处理外部链接调起,几乎每个页面跳转背后都有Intent在默默干活。我早期写项目…

2026/10/3 23:15:59

JavaScript数组方法实战:从map到reduce的高频用法与易错点

每个人的备赛与参赛经验,就是在这些最基本的知识点上拉开了差距。我给自己定的目标是:每个高频方法不假思索就能写对。 2. 遍历、筛选、映射:比赛中出场率最高的三个方法 2.1 map:数据清洗和列表渲染的头号工具 map的作用一句话…

2026/10/2 8:16:46

东莞市品牌网站建设报价常见报错与解决

东莞品牌网站建设报价单背后:一份保姆级建站教程避坑实录 网站做好了没人访问,这大概是很多老板最头疼的事。花了大几万做的品牌站,上线后流量惨淡,比路边摊还冷清。别急着骂外包公司,很多“东莞品牌网站建设报价”里藏着不少猫腻,比如用模板站冒充定制…

2026/10/2 18:20:53

如何划分训练/验证集:Spirula Studio五种eval_mode策略详解

如何划分训练/验证集:Spirula Studio五种eval_mode策略详解 【免费下载链接】spirula-studio Cross-vendor 3D Gaussian Splatting trainer - video to splat to mesh, Vulkan or CUDA. 项目地址: https://gitcode.com/GitHub_Trending/sp/spirula-studio Sp…

2026/10/3 15:02:19

SEO怎么推广速查手册新手避坑实战指南

SEO怎么推广速查手册新手避坑实战指南 模板网站太丑不够用?别急着加滤镜,那是治标不治本。很多老板盯着后台流量掉得眼红,却还在纠结首页Banner的圆角是不是3像素。这就像穿着西装去挖土,姿势不对,努力白费。我整理这份 速查手册…

2026/10/3 0:04:31

国内大学生必备的AI写作辅助软件是哪款?

国内高校学生在论文写作过程中,越来越依赖AI辅助工具提升效率,主流方案以本土化全流程工具为核心,结合通用大模型与专业插件,覆盖选题构思、框架搭建、初稿撰写、查重降重、格式调整等关键环节,本文将深入解析当前主流…

2026/10/3 0:04:31

Codex接入Jev模型完整指南:配置方法、本地部署与踩坑排查

最近不少人在讨论 Codex 搭配 Jev 这套玩法,我一开始没太当回事,直到自己把 Jev 接进 Codex跑了几轮编码任务之后,才明白那些说“直接起飞”的人是怎么想的。Codex 作为工具本身已经够能打了,但模型固定、上下文策略固定&#xff…

2026/10/3 0:04:31

GitHub 热门: NVIDIA/Model-Optimizer

👋 Hi,我擅长 AI 大模型应用落地、意识解码与 AI 开发工具链 。 💡 创业路上,用技术换时间,一起把 AI 变成生产力 🚀 >GitHub 热门: NVIDIA/Model-Optimizer 凌晨两点,你刚把跑通了的 Qwen3.…

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑