io.github.qwertymuzaffar/software-design
SOLID/OOP/DRY, the 23 GoF patterns, pattern scaffolding, and heuristic code-smell detection.
Open source Open in the app JSON README (API)
About
SOLID/OOP/DRY, the 23 GoF patterns, pattern scaffolding, and heuristic code-smell detection.
Details
- Kind
- MCP servers
- Topic
- Developer tools
- Publisher
- qwertymuzaffar
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.3
- Last push
- 2026-08-02T12:49:42Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:16
- Updated
- 2026-08-29 04:01:16
- Origin id
io.github.qwertymuzaffar/software-design
README
# mcp-software-design
[](https://www.npmjs.com/package/mcp-software-design)
[](https://www.npmjs.com/package/mcp-software-design)
[](./LICENSE)
[](https://modelcontextprotocol.io)
An [MCP](https://modelcontextprotocol.io) server that teaches and helps apply
**software-design guidance** — the SOLID principles, the OOP pillars, DRY /
KISS / YAGNI / meaningful naming / clean code, and the 23 Gang-of-Four design
patterns —
plus pattern scaffolding and heuristic code-smell detection.
It's the companion to
[`mcp-udacity-commit`](https://github.com/qwertymuzaffar/mcp-udacity-commit): same stack (TypeScript, the MCP
SDK, stdio transport), same shape (pure logic modules + thin server wiring).
## Install
Register it with Claude Code — one line, nothing to clone:
```bash
claude mcp add software-design -- npx -y mcp-software-design
```
Or in an MCP client config:
```json
{
"mcpServers": {
"software-design": {
"command": "npx",
"args": ["-y", "mcp-software-design"]
}
}
}
```
## Why this exists — and its one honest caveat
The commit server can *lint*: "subject ≤ 50 chars" is objectively checkable.
**Design principles and patterns are not like that** — "does this violate
SRP?" or "should this be a Factory?" are judgment calls, not lint rules.
So this server does **not** pretend to grade your architecture pass/fail.
Instead it does the parts that are genuinely reliable, and hands the judgment
to the model:
| Capability | Primitive | What it gives you |
|---|---|---|
| **Reference** | resources + `explain_concept` | Authoritative, consistent definitions so the model cites the same thing every time. |
| **Scaffolding** | `scaffold_pattern` | A language-agnostic skeleton of a pattern's participants. |
| **Smell heuristics** | `check_smells` | A few genuinely-checkable proxies (long method, deep nesting, …) — **hints, never verdicts**. |
| **Explain / apply** | `review_design`, `apply_pattern` prompts | Prime the model to review or refactor, grounded in the tools + resources above. |
Design analysis is a judgment call, so the "explain/apply helper" is exposed
as MCP **prompts** (which drive the client's model) rather than server code
pretending to understand your snippet.
## Tools
- **`list_catalog`** `{ kind? }` — list concepts, optionally filtered
(`principle` | `solid` | `oop` | `pattern` | `creational` | `structural` |
`behavioral`). `solid` / `oop` narrow to the SOLID five / the four OOP pillars.
- **`explain_concept`** `{ name }` — full guidance for one principle or
pattern (intent, when-to-use, trade-offs, participants). Accepts a slug,
name, or alias (`"SRP"`, `"open-closed"`, `"pubsub"`).
- **`scaffold_pattern`** `{ pattern, names? }` — pseudo-code skeleton for a GoF
pattern; `names` optionally renames roles to your domain
(`{ "Product": "Notification" }`).
- **`check_smells`** `{ code, …thresholds? }` — heuristic scan for long
method, large class, long parameter list, deep nesting, duplication, and
large file. Each finding names the principle it hints at plus a suggested
refactor. All thresholds are overridable per call.
## Resources
- **`design://principles`** — SOLID, OOP pillars, DRY, KISS, YAGNI, meaningful
naming, and more.
- **`design://patterns`** — the 23 GoF patterns, grouped creational /
structural / behavioral.
- **`design://smells`** — what `check_smells` detects, its thresholds, and its
caveats.
## Prompts
- **`review_design`** `{ code, focus? }` — review a snippet against the
principles/patterns, grounded in `check_smells` + the resources.
- **`apply_pattern`** `{ pattern, code }` — refactor a snippet to apply a named
pattern (and first judge whether it even fits).
## Build from source
For local development, or to run a local checkout instead of the published
package:
```bash
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
```
Then register it the same way as [Install](#install) above — both the
`claude mcp add` command and the MCP-client-config form work — but point at
your local build instead of `npx`:
```bash
claude mcp add software-design -- node /absolute/path/to/mcp-software-design/build/index.js
```
## Layout
```
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)
```
The `src/*.ts` logic modules are pure and side-effect-free, so they're unit
tested directly against the compiled output — the server (`index.ts`) is only
thin wiring on top.
## License
MIT