SuperAPI AI 工具集

build-clean-mcp-architecture

智能体与模型

查看项目

更新于 10-16 07:19

技能介绍

用途:为使用 mcp-use/server 的 TypeScript MCP 服务定义并执行 Clean Architecture 结构,决定文件放哪、各层可导入什么、bootstrap 组装什么,以及如何用工具链强制约束。适用于新建仓库、把单体 src/tools/*.ts 重构为分层、PR 架构评审、排查 domain/ 或 application/ 误引入 mcp-use、修复散落的 process.env、设计端口与适配器。

主要能力与结构:规范给出 src/ 下的 canonical 布局(domain、application、handlers、gateways、presenters、infrastructure、resources、prompts、shared)与导入矩阵。内层不得导入外层:domain/ 只导入自身;application/ 只导入 domain/ 与 shared/;domain/ 与 application/ 不得出现 mcp-use 或 SDK 类型。只有一个组合根和一个配置接缝 runtime-config.ts(唯一读 process.env 处,用 Zod 校验环境)。Zod 只放在 handler 边界,tools 边界禁止 z.any()/z.unknown()。禁止 any、as any、@ts-ignore;type-only 导入使用 import type,需开启 verbatimModuleSyntax。src/ 下禁止 console.*,日志以 JSON 写到 stderr。一个工具一个文件,applications 内不用 barrel。网关处做 provider 错误分类,域名事件在持久化提交后发出。

使用方式:编辑前先选模式——Greenfield、Refactor、Review、Implementing 或 Ask,对应读取不同参考文档。审计时先扫描常见坏味道(内层引入 mcp-use、runtime-config 之外读 env、组合根之外调用 server.tool、handlers 超过约 250 行、bootstrap 之外 new *Gateway、handler schema 出现 z.any()/z.unknown() 等),再按 P0/P1/P2 报告。验证门禁包括项目 typecheck 与 lint、dependency-cruiser 边界检查、相关 handler/use case/gateway/presenter 单测,涉及 wiring、bootstrap、transport、auth/session 或响应表面时才做端到端 MCP 调用;还附带只读审计脚本 audit-layer-imports.sh、check-folder-layout.sh、check-zod-boundary.sh。

限制:本技能只负责结构归属与分层边界,不涵盖类型与校验细节,也不涵盖 @modelcontextprotocol/sdk 的原始服务机制、mcp-use/server 的 API 配方(tool helper、auth、session、transport、widget、CSP、Inspector、部署)、客户端或 MCPAgent,以及通用 agent 可用性、token 成本与工具描述质量等话题,这些应路由到其他技能。