software-design

mcp-software-design

一个 MCP 服务，用于讲解并帮助应用软件设计指导原则——SOLID 原则、OOP 支柱、DRY / KISS / YAGNI / 有意义的命名 / 整洁代码，以及四人帮的 23 种设计模式—— 还提供模式框架生成和基于启发式的代码异味检测。

它是 mcp-udacity-commit 的配套项目：使用相同的技术栈（TypeScript、MCP SDK、stdio 传输），采用相同的结构（纯逻辑模块 + 精简的服务接线代码）。

安装

只需一行即可在 Claude Code 中注册，无需克隆：

claude mcp add software-design -- npx -y mcp-software-design

或者在 MCP 客户端配置中：

{
  "mcpServers": {
    "software-design": {
      "command": "npx",
      "args": ["-y", "mcp-software-design"]
    }
  }
}

为什么要做这个项目——以及坦诚说明的一个局限

提交服务可以进行检查：“主题 ≤ 50 个字符”是可以客观验证的。 设计原则和模式并非如此——“这是否违反了 SRP？”或“这里是否应该用工厂模式？”都需要判断，而不是检查规则。

因此，这个服务不会假装能给你的架构评定通过或不通过。 它只负责真正可靠的部分，并将判断交给模型：

能力	原语	能提供什么
参考资料	资源 + explain_concept	权威且一致的定义，确保模型每次引用的内容都相同。
框架生成	scaffold_pattern	与语言无关的模式参与者框架。
代码异味启发式检测	check_smells	一些确实可检查的代理指标（长方法、深层嵌套，……）——仅作提示，绝不下结论。
讲解 / 应用	review_design、apply_pattern 提示词	引导模型进行审查或重构，并以以上工具和资源为依据。

设计分析需要判断，因此“讲解 / 应用辅助功能”以 MCP 提示词的形式提供（由客户端的模型处理），而不是让服务端代码假装能理解你的代码片段。

工具

• list_catalog { kind? } — 列出概念，可选择按类别筛选 （principle | solid | oop | pattern | creational | structural | behavioral）。solid / oop 分别限定为五项 SOLID 原则 / 四项 OOP 支柱。
• explain_concept { name } — 提供单个原则或模式的完整指导 （意图、适用时机、权衡、参与者）。接受 slug、名称或别名（"SRP"、"open-closed"、"pubsub"）。
• scaffold_pattern { pattern, names? } — 为 GoF 模式生成伪代码框架；names 可用于按你的领域重命名角色 （{ "Product": "Notification" }）。
• check_smells { code, …thresholds? } — 启发式扫描长方法、大类、长参数列表、深层嵌套、重复代码和大文件。每项发现都会指出相关原则，并提供建议的重构方式。每次调用均可覆盖所有阈值。

资源

• design://principles — SOLID、OOP 支柱、DRY、KISS、YAGNI、有意义的命名等。
• design://patterns — 23 种 GoF 模式，按创建型 / 结构型 / 行为型分组。
• design://smells — check_smells 检测的内容、阈值及注意事项。

提示词

• review_design { code, focus? } — 根据原则 / 模式审查代码片段，并以 check_smells 和资源为依据。
• apply_pattern { pattern, code } — 将指定模式应用到代码片段并进行重构（首先判断该模式是否适用）。

从源代码构建

用于本地开发，或运行本地检出版本而非已发布的 软件包：

npm install
npm run build      # compiles src → build
npm start          # runs the stdio server
npm test           # builds, then runs the unit tests
npm run test:client  # end-to-end check against the built server

然后按照上方 安装 中的相同方式注册——claude mcp add 命令和 MCP 客户端配置形式均可——但指向 你的本地构建，而不是 npx：

claude mcp add software-design -- node /absolute/path/to/mcp-software-design/build/index.js

目录结构

src/
  catalog.ts   # principles + 23 GoF patterns (data + lookup + markdown)
  smells.ts    # pure, testable code-smell heuristics
  scaffold.ts  # renders a pattern's participants into a skeleton
  index.ts     # MCP wiring: resources, tools, prompts
test/
  catalog.test.mjs   # catalog lookup + scaffolder
  smells.test.mjs    # smell detectors (incl. string/comment edge cases)

src/*.ts 逻辑模块是纯函数且无副作用，因此会直接针对编译后的输出进行单元 测试——服务端（index.ts）只负责在其上进行简单的连接。

许可证

MIT