SuperAPI AI 工具集

build-clean-mcp-architecture

智能体与模型

查看项目

更新于 10-16 06:16

技能介绍

用途:面向 TypeScript mcp-use/server 的架构标准,决定文件放在哪、各层可导入什么、bootstrap 负责什么,以及如何用机制强制约束。具体 API、认证、传输、widget 等机械配方不在本技能范围。

主要能力:

  • 三种模式:Greenfield(无 src/ 时)、Refactor(单体 tools、缺 application 层、env 读取分散、业务逻辑混入协议导入)、Review(给现有仓库或 PR 做结构评级,输出 P0/P1/P2)、Implementing(在干净分层仓库中添加工具等)、Ask(仅咨询)。
  • 规范目录:domain/、application/、handlers/、gateways/、presenters/、infrastructure/、resources/、prompts/、shared/。
  • 导入矩阵:domain/ 只导入自身;application/ 仅导入 domain/ 与 shared/;handlers/ 可导入 domain、application、presenter 端口、Zod 与协议边缘类型;gateways/ 可导入 domain 端口与 provider SDK;presenters/ 可导入 domain 响应对象;infrastructure/ 可导入各层;shared/ 只导入 domain 类型,且不得有副作用与框架导入。
  • 约束:内层不得导入外层;domain/ 与 application/ 不得出现 mcp-use 或 SDK 类型;单一组合根与单一配置缝(仅 runtime-config.ts 读 process.env,用 Zod 校验);handler 边界用 Zod;禁止 any、@ts-ignore 等;禁止 src/ 下 console.*(stdout 为 JSON-RPC);provider 错误在 gateway 分类为 DomainError;每文件一工具;应用层禁止 barrel。
  • 检测与验证:用 dependency-cruiser 加 TypeScript/lint 做 CI 阻断门;提供只读审计脚本 scripts/audit-layer-imports.sh、scripts/check-folder-layout.sh、scripts/check-zod-boundary.sh,可在目标 MCP 项目根运行或把项目根作为首个参数;编辑技能包时用 python3 scripts/validate-skills.py。

使用方式:编辑前先选定唯一模式;若证据与所选模式冲突,指出一次后按代码库匹配的模式继续。需查具体规则时读取对应 references 文件(如 folder-layout.md、dependency-rules.md、composition-root.md、gateways-and-ports.md 等)。

限制:不处理原始 @modelcontextprotocol/sdk 机制、mcp-use/server API 配方、客户端或 MCPAgent 工作,以及 token 成本、工具描述质量、运行时 UX 等非结构问题;这些应交给其他技能。资料未提供具体版本、收费或平台信息。