系列文章目录第一章 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 明确不做的工作二、正确选择 Tool、Resource 与 Prompt三、设计只读项目概览 Resource3.1 Resource URI3.2 返回内容3.3 验收场景3.4 测试优先四、设计可复用的项目分析 Prompt4.1 Prompt 名称与参数4.2 输出要求五、为 Tool 增加结构化输出5.1 同时返回机器可读与文本结果5.2 结构化输出约束六、按原子任务逐步落地6.1 能力分类练习6.2 Resource 业务测试与注册6.3 Prompt 注册6.4 Tool 结构化输出6.5 完整验证七、使用 Inspector 与 Trae 验证三类能力八、验收清单与常见问题8.1 验收标准8.2 Tool 和 Resource 难以选择8.3 Prompt 被误认为业务逻辑8.4 SDK 示例无法编译总结前言第四阶段完成后项目已经能够维护多个 Tool但一个成熟的 MCP Server 不应把所有能力都设计成 Tool。本文将补齐本地 MCP 的核心原语区分 Tools、Resources 和 Prompts 的职责注册项目概览 Resource 与项目分析 Prompt并为analyze_package_json增加结构化输出。操作原则先判断能力类型再编码。不是所有内容都应该设计成 Tool。一、阶段目标与任务边界1.1 本阶段目标理解 Tool、Resource、Prompt 的适用场景注册一个只读项目概览 Resource注册一个项目分析 Prompt为analyze_package_json增加结构化输出保留面向模型阅读的文本内容验证客户端对三类能力的发现和调用保持现有 Tool 正常工作。1.2 包含的工作一个固定 URI 的项目概览 Resource一个接受分析重点参数的 Prompt一个具有 output schema 和结构化结果的 Tool对相关业务函数进行单元测试使用 Inspector 验证能力暴露情况。1.3 明确不做的工作不接入数据库或外部 API不实现 Resource 订阅和变更通知不实现复杂 URI Template不迁移到远程 HTTP不增加认证和多用户权限。二、正确选择 Tool、Resource 与 Prompt三类能力的核心差异如下能力适用场景本阶段示例Tool需要参数、计算或执行动作分析指定package.jsonResource暴露可读取、可寻址的上下文当前项目概览Prompt提供可复用的任务模板分析 Node.js 项目可以使用以下判断方法需要模型主动传参并触发逻辑使用 Tool内容天然具有 URI主要用于读取上下文使用 Resource目标是复用一套对话指令使用 Prompt。作为分类练习可以判断以下需求分析用户指定的 package.json读取当前项目概览提供固定的项目审查流程计算两个数字之和执行 npm script。前四项依次可以映射到 Tool、Resource、Prompt 和 Tool。最后一项则应明确拒绝在当前学习项目中实现因为它超出了只读、安全的项目边界。三、设计只读项目概览 Resource3.1 Resource URIproject://current/overview稳定 URI 让客户端能够发现并读取当前项目上下文而不必让模型每次都传入磁盘路径。3.2 返回内容项目概览至少包含项目名称和版本npm scripts运行时与开发依赖数量当前 MCP 暴露的能力名称。Resource 只读取当前项目不接受任意磁盘路径。底层应复用现有 package.json 服务以避免重复实现文件读取、JSON 解析和校验逻辑。3.3 验收场景客户端能列出 Resource读取 URI 后能获得文本或 JSON 内容文件读取失败时给出明确错误Resource 读取失败不导致 Server 退出。3.4 测试优先先测试可独立调用的 Resource 内容生成函数至少覆盖正确生成当前项目概览scripts 缺失package.json 不可读取输出不包含文件正文之外的敏感信息。随后把 Resource 注册放在独立模块入口文件只负责调用注册函数。完成后执行pnpm test pnpm typecheck四、设计可复用的项目分析 Prompt4.1 Prompt 名称与参数Prompt 名称analyze_node_project参数focus可选scripts、dependencies、quality 或 overview4.2 输出要求Prompt 返回一组可复用消息引导模型先读取项目概览 Resource必要时调用analyze_package_json按用户选择的重点分析不执行 npm scripts明确区分工具返回的事实和模型建议。Prompt 自身不直接读取文件也不替代 Tool。它负责复用“如何完成项目分析”的对话流程而文件访问、输入校验和业务计算仍由 Resource、Tool 和业务函数承担。注册后应通过测试或静态检查 Prompt 返回的消息内容确保focus参数会影响分析重点同时不包含执行命令的指令。五、为 Tool 增加结构化输出5.1 同时返回机器可读与文本结果为analyze_package_json声明与业务结果匹配的输出 Schema并在成功结果中同时返回return{structuredContent:analysis,content:[{type:text,text:JSON.stringify(analysis,null,2),},],};5.2 结构化输出约束structuredContent与 output schema 一致content保留人和模型可直接阅读的文本错误结果继续使用isError: true不为无法稳定定义的字段设计宽泛 Schema。结构化内容方便客户端按字段消费结果文本内容则兼顾不直接使用结构化数据的模型和用户。两者并存能提高兼容性但必须来源于同一份分析结果避免信息不一致。MCP SDK 版本演进较快具体 SDK API 应以项目当前安装版本的类型定义和官方文档为准不要直接复制其他版本示例。六、按原子任务逐步落地6.1 能力分类练习先完成 Tool、Resource、Prompt 的需求分类并明确拒绝执行 npm script。这一步用于验证设计判断而不是代码能力。6.2 Resource 业务测试与注册先编写项目概览生成函数的测试再实现业务逻辑和独立注册模块确保入口文件继续只承担组合职责。6.3 Prompt 注册实现 Prompt 消息生成函数与注册模块检查参数能改变分析重点并确保消息中没有命令执行指令。6.4 Tool 结构化输出为analyze_package_json增加 output schema 和structuredContent保持原有文本输出和 Tool 名称不变。6.5 完整验证pnpm test pnpm typecheck pnpm build七、使用 Inspector 与 Trae 验证三类能力验证客户端能够列出并调用所有 Tools列出并读取project://current/overview列出并获取analyze_node_projectPrompt读取结构化 Tool 结果在一次调用失败后继续使用其他能力。如果当前 Trae 版本没有展示某类 MCP 能力应使用 Inspector 完成协议级验证并记录客户端限制不要把客户端不支持误判为 Server 实现失败。测试策略应优先覆盖可独立调用的业务函数Resource 内容生成函数Prompt 消息生成函数结构化分析结果函数。不需要重复测试 MCP SDK 内部协议实现。注册是否成功由类型检查、构建和 Inspector 集成验证共同确认。八、验收清单与常见问题8.1 验收标准能准确说明 Tool、Resource、Prompt 的区别已实现project://current/overviewResourceResource 复用了现有 package.json 能力已实现analyze_node_projectPromptPrompt 参数可以改变分析重点analyze_package_json提供结构化输出结构化结果与 output schema 一致文本输出继续保留新能力按模块注册测试、类型检查和构建通过Inspector 能发现并验证三类能力现有三个 Tool 没有回归。8.2 Tool 和 Resource 难以选择“读取一个稳定 URI 的内容”优先考虑 Resource“让模型提供参数并触发计算”优先考虑 Tool。8.3 Prompt 被误认为业务逻辑Prompt 是消息模板不应承担文件读取、输入校验和业务计算。8.4 SDK 示例无法编译MCP SDK 版本演进较快。优先查看当前安装包类型、当前项目锁定版本及对应官方文档确保注册参数与版本匹配。完成本阶段后应能够根据需求选择正确的 MCP 原语并开发具有测试、错误隔离和结构化输出的本地 MCP而不仅是持续堆叠 Tool。总结本文从能力选择出发建立了 Tool、Resource 与 Prompt 的职责边界用 Tool 接收参数并触发计算用 Resource 暴露稳定、可寻址的只读上下文用 Prompt 复用对话任务流程。同时analyze_package_json通过 output schema、structuredContent与文本内容兼顾了机器消费和模型阅读。关键要点回顾先分类再编码稳定 URI 内容优先 Resource可复用任务指令使用 Prompt需要传参计算才使用 Tool。Prompt 不是业务逻辑它只生成消息不负责文件读取、校验或计算。结构化输出必须匹配 Schema不要用宽泛字段掩盖不稳定的数据设计。文本输出仍需保留结构化结果与文本结果应来自同一份业务数据。区分客户端限制与服务端错误Trae 未展示某类能力时用 Inspector 做协议级验证。下一篇文章将进入本地 stdio MCP 的最终综合项目独立设计list_project_files完成从需求分析、测试到客户端验收的全流程能力检验。