系列文章目录第一章 TypeScript MCP Server从零到一已更新第二章 TypeScript MCP Server提取业务逻辑与建立自动化测试已更新第三章 TypeScript MCP Server分析 package.json 与处理文件系统边界已更新第四章 TypeScript MCP Server多 Tool 组织与模块复用已更新第五章 TypeScript MCP ServerResources、Prompts 与结构化输出已更新第六章 TypeScript MCP Server独立综合项目与能力验收已更新文章目录系列文章目录前言一、综合项目需求与能力范围二、设计 list_project_files Tool2.1 Tool 目标2.2 最低输入契约2.3 最低输出契约2.4 必须遵守的安全边界三、按独立开发流程推进3.1 需求澄清3.2 接口设计3.3 测试优先3.4 业务实现3.5 集成验证四、覆盖正常、边界与异常场景4.1 正常流程4.2 边界条件4.3 异常情况五、遵守工程质量要求六、完成自动化与 Inspector 验收6.1 自动化验收6.2 Inspector 能力发现ToolsResourcePrompt6.3 Inspector 手工验证七、完成 Trae 端到端验收八、使用评分表评估独立能力九、最终验收清单与达成标准9.1 最终验收清单9.2 独立开发达成标准总结前言前五个阶段已经覆盖本地 stdio MCP 的搭建、测试、文件系统边界、多 Tool 组织以及 Resources、Prompts 和结构化输出。本文不再提供逐行实现代码而是模拟一次独立开发任务检验能否脱离教程完成需求分析、接口设计、测试、实现、调试和客户端接入。完成本阶段并通过验收可以认为已经具备独立开发小型本地 stdio MCP 的能力。一、综合项目需求与能力范围在现有项目基础上完成一个“本地 Node.js 项目助手 MCP”。它应帮助 AI 获取项目基本信息、分析配置和理解 npm scripts但不得执行项目命令或修改被分析文件。必须保留并整理以下能力calculate_sum analyze_package_json explain_npm_script project://current/overview analyze_node_project另外独立设计并实现一个新 Toollist_project_files本阶段只提供需求和验收标准不提供完整代码。开发时允许查阅 MCP SDK 和 Zod 文档查看 TypeScript 与 Node.js API 文档参考前几阶段形成的项目模式使用 Inspector 查看协议结果。但不应直接复制一份现成的同类 MCP 实现。重点是独立作出接口、边界和模块划分决策。二、设计 list_project_files Tool2.1 Tool 目标列出指定项目目录内的文件帮助 AI 理解项目结构。2.2 最低输入契约directoryPath要分析的目录maxDepth可选限制递归深度includeHidden可选是否包含隐藏文件。2.3 最低输出契约规范化后的根目录文件相对路径列表文件数量是否因限制发生截断。2.4 必须遵守的安全边界只读文件系统默认跳过node_modules、.git和dist限制递归深度限制最大返回文件数不读取文件正文路径不存在或不是目录时返回 Tool 错误单次失败不终止 MCP Server。具体默认深度和最大文件数由开发者自行确定并在 Tool 描述和测试中保持一致。限制深度和数量不是可选优化而是保护 Server 响应规模与文件系统边界的必要措施。三、按独立开发流程推进3.1 需求澄清编码前写下Tool 解决什么问题哪些输入属于系统边界哪些目录默认忽略深度和数量限制成功与错误输出哪些行为明确不做。3.2 接口设计先确定 Zod 输入 Schema、结构化输出 Schema 和 TypeScript 业务结果类型再实现文件扫描。接口先行可以让测试、业务逻辑和 MCP 输出适配共享同一份稳定契约。3.3 测试优先先创建临时目录并编写失败测试再实现最少代码使测试通过。3.4 业务实现文件遍历逻辑独立于 MCP SDKTool 模块只负责输入输出适配和错误转换。3.5 集成验证依次完成测试、类型检查、构建、Inspector 和 Trae 验证。四、覆盖正常、边界与异常场景4.1 正常流程空目录只有一层文件包含多层子目录Windows 路径相对路径文件结果使用相对路径且排序稳定。4.2 边界条件达到最大深度达到最大文件数量默认跳过node_modules、.git和distincludeHidden为falseincludeHidden为true。4.3 异常情况路径不存在输入路径是文件而不是目录没有读取权限输入参数不符合 Zod Schema。权限用例如果难以跨平台稳定构造可以通过隔离文件系统访问函数或使用平台条件测试不要为了测试而修改真实项目权限。五、遵守工程质量要求index.ts只负责 Server 组合和启动每种 MCP 能力独立注册业务逻辑不依赖 stdio Transport外部输入使用 Zod 校验文件系统操作使用 Promise API可预期调用错误使用isError: truestdio 模式不使用console.log()不添加当前需求用不到的抽象或依赖不修改或执行用户项目内容。这些要求共同保证协议层、业务层和系统边界保持分离。特别是 stdio 模式下stdout属于 MCP 协议通道普通日志必须避免使用console.log()。六、完成自动化与 Inspector 验收6.1 自动化验收必须全部通过pnpm test pnpm typecheck pnpm build测试要求每个核心业务模块有单元测试文件系统测试使用临时目录测试结束后清理临时数据用例互不依赖不读取或修改真实用户项目作为测试前提原有能力无回归。6.2 Inspector 能力发现Inspector 至少能够发现Toolscalculate_sum analyze_package_json explain_npm_script list_project_filesResourceproject://current/overviewPromptanalyze_node_project6.3 Inspector 手工验证正确列出当前项目文件node_modules和.git默认不出现在结果中非法目录返回 Tool 错误错误后仍能调用calculate_sumpackage.json 分析与脚本解释仍正常Resource 和 Prompt 可以获取结构化结果符合声明的 Schema。七、完成 Trae 端到端验收重建并重连 MCP Server 后使用自然语言完成让 AI 列出当前项目主要文件让 AI 分析 package.json让 AI 解释build或test脚本让 AI 使用项目概览完成一次总结故意提供错误路径然后继续调用其他 Tool。确认 AI 使用了 MCP 返回的事实而不是仅凭上下文猜测。错误路径测试也能验证单次失败是否真正被隔离而不是让整个 Server 断开。八、使用评分表评估独立能力每项按 02 分自评能力0 分1 分2 分需求理解无法确定边界需要指导能独立澄清和限定范围接口设计参数随意基本可用名称、描述、Schema 清晰稳定模块设计全部堆在入口有部分拆分协议层与业务层职责清晰输入校验信任外部数据部分校验所有系统边界均校验错误处理错误导致退出能捕获错误错误明确且调用相互隔离测试无测试只有正常流程覆盖正常、边界和异常调试依赖他人定位能按提示排查能独立使用日志和 Inspector客户端接入无法接入按教程接入能独立配置和排错MCP 原语选择全部做成 Tool基本能区分能合理选择 Tool/Resource/Prompt安全意识无边界知道主要风险主动限制路径、数量和副作用总分 20 分09继续按阶段练习1014可以在指导下开发1517可以独立开发小型本地 MCP1820能够稳定设计和维护本地 MCP。九、最终验收清单与达成标准9.1 最终验收清单独立设计并实现了list_project_filesTool 有明确输入、输出和安全边界使用 Zod 校验外部参数文件遍历具有深度和数量限制默认忽略大型或内部目录业务逻辑和 MCP 注册分离单元测试覆盖正常、边界和异常所有旧能力无回归测试、类型检查和构建全部通过Inspector 验收通过Trae 验收通过能解释关键设计决策及其理由自评分达到 15 分或以上。9.2 独立开发达成标准如果能够在不依赖逐行教程的情况下完成本阶段遇到 SDK 细节时主动查文档并能独立定位测试、构建和客户端连接问题就可以认为已经具备独立开发小型本地 MCP 的能力。总结本文通过“本地 Node.js 项目助手 MCP”综合项目把前五个阶段的知识集中到一次独立交付中从list_project_files的需求澄清、输入输出契约与安全边界到临时目录测试、业务与协议分层再到自动化、Inspector 和 Trae 端到端验收。最终目标不是简单增加一个 Tool而是证明自己能够独立控制系统边界、错误隔离、工程质量和客户端集成。关键要点回顾文件扫描必须有边界限制递归深度和最大文件数并默认跳过node_modules、.git与dist。坚持只读原则不读取文件正文不执行命令不修改用户项目。测试应独立且可清理使用临时目录覆盖正常、边界和异常流程避免依赖真实项目。协议层与业务层分离文件遍历不依赖 MCP SDK注册模块只做 Schema、输出适配和错误转换。验收必须覆盖完整链路自动化命令、Inspector、Trae 和旧能力回归都通过才算完成。至此本地 stdio MCP 系列的基础与进阶实践告一段落。下一阶段将进入远程 MCP学习 Streamable HTTP、认证、部署、多用户隔离、限流、审计与远程安全这些能力应在本地边界和工程基础稳定后再引入。