系列文章目录第一章 TypeScript MCP Server从零到一已更新第二章 TypeScript MCP Server提取业务逻辑与建立自动化测试已更新第三章 TypeScript MCP Server分析 package.json 与处理文件系统边界已更新第四章 TypeScript MCP Server多 Tool 组织与模块复用已更新第五章 TypeScript MCP ServerResources、Prompts 与结构化输出已更新第六章 TypeScript MCP Server独立综合项目与能力验收已更新文章目录系列文章目录前言一、阶段目标与任务边界1.1 本阶段目标1.2 包含的工作1.3 明确不做的工作二、定义 explain_npm_script 接口契约2.1 Tool 名称与输入2.2 成功输出2.3 错误输出三、按职责重组项目结构3.1 推荐目录结构3.2 模块职责四、测试优先实现脚本解释能力4.1 先补充失败测试4.2 提取 package.json 服务4.3 实现脚本解释业务函数五、拆分 Tool 注册与入口组合六、完成静态、Inspector 与 Trae 验证6.1 完整静态验证6.2 Inspector 验证七、验收清单与常见问题7.1 验收标准7.2 ESM 相对导入失败7.3 拆分后出现循环依赖7.4 命令拆分不准确总结前言前三个阶段已经完成 MCP Server、自动化测试以及calculate_sum和analyze_package_json。当 Tool 数量继续增加如果仍把注册、业务逻辑和启动代码全部放进入口文件维护成本会迅速上升。本文将新增explain_npm_script复用现有package.json能力并完成多 Tool 的模块化组织。操作原则只分析脚本文本不执行任何来自package.json的命令。一、阶段目标与任务边界1.1 本阶段目标实现explain_npm_scriptTool复用现有package.json读取与校验能力将业务逻辑、Tool 注册和 Server 启动拆分保持现有两个 Tool 的名称和行为不变为新增业务逻辑编写单元测试使用 Inspector 和 Trae 验证三个 Tool。1.2 包含的工作根据文件路径和脚本名称读取 npm script返回脚本原文及基础命令说明处理脚本不存在、字段异常和文件读取错误提取可复用的package.json读取逻辑将 Tool 注册拆到独立模块。1.3 明确不做的工作不执行 npm script不启动子进程不判断命令一定安全或危险不实现 Shell 完整语法解析器不增加远程 Transport、数据库或外部 API。二、定义 explain_npm_script 接口契约2.1 Tool 名称与输入Tool 使用稳定名称explain_npm_script输入 Schema 如下inputSchema:{filePath:z.string().trim().min(1).describe(package.json 文件路径),scriptName:z.string().trim().min(1).describe(要解释的 npm script 名称),}调用示例{filePath:package.json,scriptName:build}2.2 成功输出exportinterfaceNpmScriptExplanation{filePath:string;scriptName:string;command:string;segments:string[];}其中segments可以按、||或;做基础拆分但本阶段不追求完整 Shell 解析。保留command原文可以在基础拆分不够准确时提供可靠的兜底信息。2.3 错误输出Tool handler 捕获可预期错误并返回{isError:true,content:[{type:text,text:解释 npm script 失败${message}}],}这能把单次调用失败限制在当前 Tool 内避免 Server 因业务错误退出。三、按职责重组项目结构3.1 推荐目录结构src/ ├─ index.ts ├─ domain/ │ └─ calculate-sum.ts ├─ services/ │ └─ package-json.ts ├─ tools/ │ ├─ register-calculate-sum.ts │ ├─ register-analyze-package-json.ts │ └─ register-explain-npm-script.ts └─ tests/ ├─ calculate-sum.test.ts ├─ analyze-package-json.test.ts └─ explain-npm-script.test.ts如果移动现有测试会引入过多配置调整也可以暂时保留测试文件位置。本阶段重点是职责拆分不要求机械照搬目录。3.2 模块职责模块职责index.ts创建 Server、注册 Tools、连接 stdio、处理启动失败services/package-json.ts解析路径、读取文件、解析 JSON、执行 Zod 校验register-*.ts声明 Tool Schema将输入输出适配到 MCP 协议业务函数完成计算或脚本文本分析不依赖 MCP Transport依赖方向也要保持单向Tool 模块可以依赖 service 和业务函数但 service 不应反向依赖 Tool 或 Server。这样可以避免循环依赖也便于业务逻辑独立测试。四、测试优先实现脚本解释能力4.1 先补充失败测试先为以下场景编写测试找到指定脚本并返回原始命令能识别由连接的多个命令片段脚本不存在时返回明确错误scripts缺失时返回明确错误scripts字段类型错误时校验失败不执行脚本内容。执行pnpm test新增测试应先因实现不存在而失败。这一步确认测试确实能够约束后续实现而不是一开始就无条件通过。4.2 提取 package.json 服务将第三阶段的路径处理、文件读取、JSON 解析和 Zod 校验提取为可复用函数同时确保analyzePackageJson的外部行为不变。完成后执行pnpm test pnpm typecheck4.3 实现脚本解释业务函数建议函数契约exportasyncfunctionexplainNpmScript(inputPath:string,scriptName:string,):PromiseNpmScriptExplanation实现要求复用 package.json 服务只读取和分析字符串不使用exec、spawn或其他命令执行 API脚本不存在时抛出可读错误返回规范化文件路径、脚本名称、原始命令和命令片段。package.json中的 scripts 属于外部输入。即使脚本看起来正常本阶段也只解释文本绝不把它交给命令执行 API。五、拆分 Tool 注册与入口组合每个注册模块接收McpServer并只完成一个 Tool 的注册。例如exportfunctionregisterExplainNpmScriptTool(server:McpServer):void{// 注册 Tool}拆分后index.ts只保留以下组合与启动职责创建 MCP Server调用各个 Tool 注册函数创建并连接 stdio Transport处理启动失败。已有的calculate_sum、analyze_package_json名称和行为必须保持不变。模块化的目的不是重写已有能力而是在不引入回归的前提下控制入口文件复杂度。六、完成静态、Inspector 与 Trae 验证6.1 完整静态验证pnpm test pnpm typecheck pnpm build三条命令分别验证业务行为、类型契约和最终构建结果缺一不可。6.2 Inspector 验证Inspector 应显示calculate_sum analyze_package_json explain_npm_script依次验证解释存在的build脚本请求不存在的脚本并确认返回 Tool 错误错误发生后再次调用calculate_sum确认 Server 未退出在 Trae 重连后调用新增 Tool。Inspector 用于确认协议层发现和调用正常Trae 验证则确认真实客户端集成没有回归。七、验收清单与常见问题7.1 验收标准已实现explain_npm_script输入包含filePath和scriptName复用了 package.json 读取与校验逻辑没有执行任何 npm script三个 Tool 分模块注册index.ts只承担组合和启动职责测试覆盖成功、脚本缺失和字段异常原有两个 Tool 没有回归pnpm test、pnpm typecheck、pnpm build全部通过Inspector 和 Trae 能调用三个 Tool。7.2 ESM 相对导入失败NodeNext 项目源码中的相对导入继续使用编译后的.js后缀。7.3 拆分后出现循环依赖Tool 模块可以依赖 service 和业务函数service 不应反向依赖 Tool 或 Server。7.4 命令拆分不准确本阶段只做基础说明不需要支持引号嵌套、转义、管道和所有跨平台 Shell 语法。返回原始命令是必要兜底信息。完成本阶段后应能够独立组织一个包含多个 Tool 的小型本地 MCP并保持协议层、业务层和系统边界清晰分离。总结本文围绕 Tool 增多后的工程组织问题完成了explain_npm_script的接口设计、测试策略和安全边界定义并将 package.json 读取能力、业务函数、Tool 注册及 Server 启动按职责拆分。经过测试、类型检查、构建、Inspector 和 Trae 验证后一个小型多 Tool MCP Server 就具备了清晰且可持续扩展的模块结构。关键要点回顾脚本解释不等于脚本执行只读取和分析 scripts 文本禁止使用exec、spawn等 API。复用应发生在业务与服务层把路径处理、文件读取、JSON 解析和 Zod 校验集中到 package.json 服务。入口文件只负责组合和启动每种 Tool 独立注册业务逻辑不依赖 MCP Transport。错误需要隔离可预期错误返回isError: true单次失败不能终止 Server。模块化不能引入回归新增 Tool 后仍要验证原有两个 Tool 的名称与行为。下一篇文章将不再只增加 Tool而是系统学习 MCP 的 Resources、Prompts 与结构化输出建立正确的能力选择边界。