第一章：TypeScript-MCP-Server-从零到一

系列文章目录第一章 TypeScript MCP Server从零到一已更新第二章 TypeScript MCP Server提取业务逻辑与建立自动化测试已更新第三章 TypeScript MCP Server分析 package.json 与处理文件系统边界已更新第四章 TypeScript MCP Server多 Tool 组织与模块复用已更新第五章 TypeScript MCP ServerResources、Prompts 与结构化输出已更新第六章 TypeScript MCP Server独立综合项目与能力验收已更新提示写完文章后目录可以自动生成如何生成可参考右边的帮助文档文章目录系列文章目录前言一、认识 MCP 与运行链路1.1 MCP 是什么1.2 运行链路一览二、项目初始化2.1 运行时依赖2.2 开发依赖2.3 配置 package.json为什么设置 type: module每条脚本的用途2.4 创建 TypeScript 配置三、编写第一个 MCP Server3.1 创建入口文件3.2 逐段理解源码McpServerregisterToolZod 输入 SchemaTool 返回值stdio Transport为什么日志必须使用 console.error四、类型检查与构建五、使用 MCP Inspector 调试六、接入 Trae七、日常开发工作流八、常见问题排查8.1 Trae 找不到 Tool8.2 修改源码后行为没有变化8.3 进程启动后一直不退出8.4 JSON 配置无法解析8.5 协议解析错误或 Server 意外断开8.6 Node 找不到模块8.7 TypeScript 编译报 ESM 相关错误九、验收清单与后续学习9.1 第一阶段验收清单9.2 第一阶段之后学什么9.3 命令汇总总结前言提示本文记录如何从零搭建一个基于 TypeScript、Node.js 和 stdio 的本地 MCP Server并接入 Trae 完成第一个 Tool 的调用。随着 AI 编程助手的普及如何让大模型安全、可控地调用本地能力成为了一个关键问题。MCPModel Context Protocol正是为此而生——它定义了一套标准协议让 AI 能够发现并调用外部工具。本文将以一个最小可运行的项目为例带你从依赖配置、源码编写、Inspector 调试一直走到在 Trae 中成功调用第一个calculate_sumTool。操作原则每完成一节先执行该节的验证命令验证通过后再继续。提示以下是本篇文章正文内容下面案例可供参考一、认识 MCP 与运行链路1.1 MCP 是什么MCPModel Context Protocol是一种开放协议用于标准化应用程序向大语言模型暴露上下文和工具的方式。你可以把它理解为AI 的 USB-C 接口——不管 Server 端如何实现Client 端如 Trae只要遵循协议就能统一发现和调用工具。1.2 运行链路一览理解整体链路比急着写代码更重要。本次要建立的链路如下用户 ↓ 自然语言 Trae 中的 AIMCP Client ↓ 判断是否调用工具 calculate_sum Tool ↓ MCP 消息stdio 本地 Node.js MCP Server ↓ 执行 TypeScript 中定义的函数 返回计算结果 ↓ Trae 组织最终答案各角色职责Trae是 MCP Client负责连接 Server并把可用 Tool 提供给 AI。本项目是 MCP Server负责声明并执行 Tool。stdio是通信通道。Trae 会启动本项目的 Node 进程通过标准输入和标准输出交换 MCP 协议消息。calculate_sum是第一个 Tool相当于给 AI 调用的函数。二、项目初始化2.1 运行时依赖依赖当前版本作用modelcontextprotocol/sdk^1.29.0官方 MCP TypeScript SDK用于创建 Server、注册 Tool 和建立 stdio 通信zod^4.4.3定义并校验 Tool 的输入参数同时帮助 SDK 生成参数 Schema2.2 开发依赖依赖当前版本作用typescript^7.0.2类型检查并将 TypeScript 编译为 JavaScripttypes/node^26.1.1为process、Node 文件系统等 API 提供类型tsx^4.23.1开发阶段直接执行 TypeScriptvitest^4.1.10单元测试框架不是运行 MCP 的必需依赖但后续测试会用到2.3 配置 package.json打开项目根目录的package.json修改为下面的结构。依赖版本保留 pnpm 当前安装的实际值不要手动降级或复制其他版本。{name:my-mcp,version:1.0.0,description:A TypeScript MCP server for learning MCP,type:module,main:dist/index.js,scripts:{dev:tsx watch src/index.ts,build:tsc -p tsconfig.json,start:node dist/index.js,typecheck:tsc -p tsconfig.json --noEmit,test:vitest run},keywords:[mcp,model-context-protocol],author:,license:ISC,packageManager:pnpm10.28.2,dependencies:{modelcontextprotocol/sdk:^1.29.0,zod:^4.4.3},devDependencies:{types/node:^26.1.1,tsx:^4.23.1,typescript:^7.0.2,vitest:^4.1.10}}为什么设置type: moduleMCP SDK 以现代 ESM 方式提供模块源码会使用import{McpServer}frommodelcontextprotocol/sdk/server/mcp.js;type: module告诉 Node.js编译后的.js文件按照 ESM 运行而不是 CommonJS。每条脚本的用途pnpm dev开发时监听源码变化并自动重启。pnpm typecheck只检查类型不生成文件。pnpm build将src编译到dist。pnpm start运行编译后的正式入口。pnpm test后续运行 Vitest 测试。修改后执行pnpm install这一步会让锁文件与package.json保持一致。2.4 创建 TypeScript 配置在项目根目录创建tsconfig.json{compilerOptions:{target:ES2022,module:NodeNext,moduleResolution:NodeNext,rootDir:src,outDir:dist,strict:true,esModuleInterop:true,forceConsistentCasingInFileNames:true,skipLibCheck:true,sourceMap:true,types:[node]},include:[src/**/*.ts],exclude:[node_modules,dist]}关键配置说明target: ES2022使用现代 Node.js 支持的 JavaScript 能力。module/moduleResolution: NodeNext按 Node.js ESM 规则解析模块。rootDir: srcTypeScript 源码放在src。outDir: dist编译结果放在dist。strict: true开启严格类型检查。types: [node]加载 Node.js 类型。三、编写第一个 MCP Server3.1 创建入口文件创建src/index.tsimport{McpServer}frommodelcontextprotocol/sdk/server/mcp.js;import{StdioServerTransport}frommodelcontextprotocol/sdk/server/stdio.js;import*aszfromzod/v4;constservernewMcpServer({name:my-mcp,version:1.0.0,});server.registerTool(calculate_sum,{title:两数求和,description:计算两个数字的和。当用户需要对两个数字做加法时使用。,inputSchema:{a:z.number().describe(第一个数字),b:z.number().describe(第二个数字),},},async({a,b}){constresultab;return{content:[{type:text,text:${a}${b}${result},},],};},);asyncfunctionmain():Promisevoid{consttransportnewStdioServerTransport();awaitserver.connect(transport);console.error(my-mcp server is running via stdio);}main().catch((error:unknown){console.error(MCP Server 启动失败,error);process.exit(1);});3.2 逐段理解源码McpServerconstservernewMcpServer({name:my-mcp,version:1.0.0,});它创建 MCP Server 实例。name和version是客户端连接后看到的服务身份信息不是 Tool 名称。registerToolserver.registerTool(calculate_sum,config,handler);它包含三部分calculate_sum稳定、唯一的 Tool 标识推荐使用英文和 snake_case。config告诉客户端和 AI 这个 Tool 做什么、接受什么参数。handlerTool 被调用时真正执行的业务代码。description不只是给人看的。AI 会依靠它决定何时调用 Tool所以应明确写出做什么和什么时候使用。Zod 输入 SchemainputSchema:{a:z.number().describe(第一个数字),b:z.number().describe(第二个数字),}它同时承担向客户端声明参数结构在运行时校验外部输入给 TypeScript 推导 handler 中a、b的类型。因为 AI 传来的参数属于外部输入不能只依赖 TypeScript 的编译时类型。Tool 返回值return{content:[{type:text,text:...,},],};Tool 不直接返回普通字符串而是返回 MCP 规定的内容数组。第一版使用最简单的text内容。stdio TransportconsttransportnewStdioServerTransport();awaitserver.connect(transport);这会让当前 Node.js 进程通过 stdin/stdout 接收和发送 MCP 消息。为什么日志必须使用console.errorstdio 模式下stdout用于传输 MCP 协议消息。随意调用console.log()可能污染协议流导致客户端解析失败。因此服务运行期间console.error(调试信息);不要使用console.log(调试信息);四、类型检查与构建先执行类型检查pnpm typecheck预期命令正常结束没有 TypeScript 错误。然后执行构建pnpm build构建成功后应出现dist/ ├─ index.js └─ index.js.map最后尝试启动pnpmstart预期看到my-mcp server is running via stdio进程会继续等待 MCP Client 发送消息这是正常现象不是卡死。按CtrlC停止。注意仅执行pnpm start只能证明进程能启动不能完整验证 Tool因为 stdio Server 正在等待符合 MCP 协议的输入。下一节使用 Inspector 验证。五、使用 MCP Inspector 调试Inspector 是 MCP 的交互式调试客户端可以发现并调用 Server 暴露的 Tool。不必把 Inspector 安装为项目依赖直接执行pnpm dlx modelcontextprotocol/inspector node dist/index.js命令会输出本地访问地址。在浏览器打开该地址然后确认 Transport 为STDIO。确认 Command 是node。确认 Arguments 包含当前项目的dist/index.js。点击连接按钮。打开Tools。点击列出工具应看到calculate_sum。输入a 10、b 20。调用 Tool。预期结果10 20 30如果 Inspector 命令对相对路径解析异常使用绝对路径pnpm dlx modelcontextprotocol/inspector noded:\BFF-BackendForFrontend\myMcp\dist\index.jsInspector 验证通过意味着Node 进程可以启动MCP 握手成功客户端可以发现 Tool参数 Schema 正常Tool handler 可以执行并返回 MCP 内容。六、接入 Trae不同版本的 Trae 设置入口和配置文件位置可能不同但核心配置始终是命令 参数 工作目录。在 Trae 的 MCP 设置中新增本地 stdio Server。推荐配置概念如下{mcpServers:{my-mcp:{command:node,args:[d:\\BFF-BackendForFrontend\\myMcp\\dist\\index.js],cwd:d:\\BFF-BackendForFrontend\\myMcp}}}注意事项JSON 中 Windows 路径的反斜杠需要写成\\。使用dist/index.js前必须先执行pnpm build。command使用node不要使用会持续 watch 的pnpm dev。如果 Trae 的可视化配置只提供 Command 和 Args就分别填写node与入口文件绝对路径。保存配置后重新加载或连接该 MCP Server。确认 Trae 显示calculate_sumTool然后发起测试请使用 calculate_sum 工具计算 135 和 246 的和并告诉我工具返回了什么。预期过程AI 识别应调用calculate_sum参数为{ a: 135, b: 246 }MCP Server 返回135 246 381AI 将结果告诉你。提示明确要求使用工具是首次联调手段。正常使用时可以直接问135 加 246 等于多少但模型可能认为简单算术无需调用工具因此不适合作为首次验证。七、日常开发工作流修改源码时pnpm dev提交或接入 Trae 前pnpm typecheck pnpm test pnpm buildTrae 使用编译后的dist/index.js所以每次修改src/index.ts后都要重新执行pnpm build然后在 Trae 中重启或重连 MCP Server。八、常见问题排查8.1 Trae 找不到 Tool按顺序检查是否执行过pnpm builddist/index.js是否存在Trae 中入口路径是否为绝对路径JSON 路径中的\\是否正确MCP Server 是否已经在 Trae 中启用或重连Inspector 是否能发现calculate_sum。如果 Inspector 正常而 Trae 不正常问题通常在 Trae 配置如果 Inspector 也失败优先检查项目代码和构建结果。8.2 修改源码后行为没有变化Trae 运行的是dist/index.js不是src/index.ts。重新执行pnpm build然后重连 Server。8.3 进程启动后一直不退出这是正常的。stdio Server 必须持续等待客户端消息。使用CtrlC停止手动启动的进程。8.4 JSON 配置无法解析Windows 路径必须转义d:\\BFF-BackendForFrontend\\myMcp\\dist\\index.js不能直接写成d:\BFF-BackendForFrontend\myMcp\dist\index.js8.5 协议解析错误或 Server 意外断开检查业务代码是否使用了console.log()。stdio Server 的普通日志应改成console.error()。8.6 Node 找不到模块确认在项目根目录执行过pnpm install pnpm build同时确认 Node.js 满足 SDK 要求。当前 SDK 要求 Node.js18推荐使用 Node.js 20 或更高的 LTS 版本。8.7 TypeScript 编译报 ESM 相关错误确认package.json包含type: moduletsconfig.json同时使用module: NodeNext和moduleResolution: NodeNextSDK 子路径导入带.js后缀。九、验收清单与后续学习9.1 第一阶段验收清单全部满足后第一阶段完成package.json已配置 ESM 和开发脚本已创建tsconfig.json已创建src/index.tspnpm typecheck通过pnpm build通过dist/index.js已生成Inspector 能列出calculate_sumInspector 调用后返回正确结果Trae 能连接my-mcpTrae 能调用calculate_sum。9.2 第一阶段之后学什么不要立即添加数据库、远程 HTTP 或复杂框架。建议按以下顺序扩展将求和业务逻辑提取成独立函数并用 Vitest 编写单元测试实现analyze_package_json学习文件读取与边界校验实现explain_npm_script学习多个 Tool 的组织方式学习 MCP Resources向 AI 暴露只读项目信息接入一个外部 API学习.env和密钥管理最后学习 Streamable HTTP、认证和远程部署。建议第二个 Tool 选择analyze_package_json因为它与你的前端经验直接相关并且不依赖 API Key 或数据库。9.3 命令汇总完成文件修改后依次执行pnpm install pnpm typecheck pnpm build pnpmstart看到启动日志后按CtrlC再运行 Inspectorpnpm dlx modelcontextprotocol/inspector noded:\BFF-BackendForFrontend\myMcp\dist\index.jsInspector 验证通过后将node dist/index.js 绝对路径配置到 Trae并测试calculate_sum。总结提示这里对文章进行总结本文从认识 MCP 协议和运行链路出发完整走通了 TypeScript MCP Server 的搭建流程配置package.json与tsconfig.json、编写第一个calculate_sumTool、逐段理解源码核心概念、完成类型检查与构建、使用 Inspector 交互式调试最终成功接入 Trae 并完成首次工具调用。关键要点回顾stdio 通信下stdout是协议通道日志必须用console.error否则会污染协议流。Zod Schema 三合一同时承担参数声明、运行时校验和类型推导。Trae 运行的是dist/index.js每次改源码都要重新pnpm build。description 是写给 AI 看的要明确做什么和什么时候使用。首次联调要明确要求使用工具避免模型跳过工具调用。下一篇文章我们将进入进阶 Tool 开发提取业务逻辑并编写单元测试敬请关注。