第六章 TypeScript MCP Server：独立综合项目与能力验收-育师

系列文章目录

第一章 TypeScript MCP Server：从零到一（已更新）
第二章 TypeScript MCP Server：提取业务逻辑与建立自动化测试（已更新）
第三章 TypeScript MCP Server：分析 package.json 与处理文件系统边界（已更新）
第四章 TypeScript MCP Server：多 Tool 组织与模块复用（已更新）
第五章 TypeScript MCP Server：Resources、Prompts 与结构化输出（已更新）
第六章 TypeScript MCP Server：独立综合项目与能力验收（已更新）

文章目录

系列文章目录
前言
一、综合项目需求与能力范围
二、设计 list_project_files Tool
- 2.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 能力发现
- - Tools
  - Resource
  - Prompt
- 6.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

另外独立设计并实现一个新 Tool：

list_project_files

本阶段只提供需求和验收标准，不提供完整代码。开发时允许：

查阅 MCP SDK 和 Zod 文档；
查看 TypeScript 与 Node.js API 文档；
参考前几阶段形成的项目模式；
使用 Inspector 查看协议结果。

但不应直接复制一份现成的同类 MCP 实现。重点是独立作出接口、边界和模块划分决策。

二、设计 list_project_files Tool

2.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 SDK，Tool 模块只负责输入输出适配和错误转换。

3.5 集成验证

依次完成测试、类型检查、构建、Inspector 和 Trae 验证。

四、覆盖正常、边界与异常场景

4.1 正常流程

空目录；
只有一层文件；
包含多层子目录；
Windows 路径；
相对路径；
文件结果使用相对路径且排序稳定。

4.2 边界条件

达到最大深度；
达到最大文件数量；
默认跳过node_modules、.git和dist；
includeHidden为false；
includeHidden为true。

4.3 异常情况

路径不存在；
输入路径是文件而不是目录；
没有读取权限；
输入参数不符合 Zod Schema。

权限用例如果难以跨平台稳定构造，可以通过隔离文件系统访问函数或使用平台条件测试；不要为了测试而修改真实项目权限。

五、遵守工程质量要求

index.ts只负责 Server 组合和启动；
每种 MCP 能力独立注册；
业务逻辑不依赖 stdio Transport；
外部输入使用 Zod 校验；
文件系统操作使用 Promise API；
可预期调用错误使用isError: true；
stdio 模式不使用console.log()；
不添加当前需求用不到的抽象或依赖；
不修改或执行用户项目内容。

这些要求共同保证协议层、业务层和系统边界保持分离。特别是 stdio 模式下，stdout属于 MCP 协议通道，普通日志必须避免使用console.log()。

六、完成自动化与 Inspector 验收

6.1 自动化验收

必须全部通过：

pnpm test pnpm typecheck pnpm build

测试要求：

每个核心业务模块有单元测试；
文件系统测试使用临时目录；
测试结束后清理临时数据；
用例互不依赖；
不读取或修改真实用户项目作为测试前提；
原有能力无回归。

6.2 Inspector 能力发现

Inspector 至少能够发现：

Tools

calculate_sum analyze_package_json explain_npm_script list_project_files

Resource

project://current/overview

Prompt

analyze_node_project

6.3 Inspector 手工验证

正确列出当前项目文件；
node_modules和.git默认不出现在结果中；
非法目录返回 Tool 错误；
错误后仍能调用calculate_sum；
package.json 分析与脚本解释仍正常；
Resource 和 Prompt 可以获取；
结构化结果符合声明的 Schema。

七、完成 Trae 端到端验收

重建并重连 MCP Server 后，使用自然语言完成：

让 AI 列出当前项目主要文件；
让 AI 分析 package.json；
让 AI 解释build或test脚本；
让 AI 使用项目概览完成一次总结；
故意提供错误路径，然后继续调用其他 Tool。

确认 AI 使用了 MCP 返回的事实，而不是仅凭上下文猜测。错误路径测试也能验证单次失败是否真正被隔离，而不是让整个 Server 断开。

八、使用评分表评估独立能力

每项按 0～2 分自评：

能力	0 分	1 分	2 分
需求理解	无法确定边界	需要指导	能独立澄清和限定范围
接口设计	参数随意	基本可用	名称、描述、Schema 清晰稳定
模块设计	全部堆在入口	有部分拆分	协议层与业务层职责清晰
输入校验	信任外部数据	部分校验	所有系统边界均校验
错误处理	错误导致退出	能捕获错误	错误明确且调用相互隔离
测试	无测试	只有正常流程	覆盖正常、边界和异常
调试	依赖他人定位	能按提示排查	能独立使用日志和 Inspector
客户端接入	无法接入	按教程接入	能独立配置和排错
MCP 原语选择	全部做成 Tool	基本能区分	能合理选择 Tool/Resource/Prompt
安全意识	无边界	知道主要风险	主动限制路径、数量和副作用

总分 20 分：

0～9：继续按阶段练习；
10～14：可以在指导下开发；
15～17：可以独立开发小型本地 MCP；
18～20：能够稳定设计和维护本地 MCP。

九、最终验收清单与达成标准

9.1 最终验收清单

独立设计并实现了list_project_files；
Tool 有明确输入、输出和安全边界；
使用 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、认证、部署、多用户隔离、限流、审计与远程安全；这些能力应在本地边界和工程基础稳定后再引入。

第六章 TypeScript MCP Server：独立综合项目与能力验收