Skip to main content
Glama
qwertymuzaffar

mcp-software-design

by qwertymuzaffar
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Local

mcp-software-design

npm version npm downloads License: MIT MCP

An MCP 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: 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:

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

Or in an MCP client config:

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

Related MCP server: Inspectra

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:

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 above — both the claude mcp add command and the MCP-client-config form work — but point at your local build instead of npx:

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

Available Tools

4 tools
check_smellsDetect code smells (heuristic)A

Scan a code snippet for heuristic design smells (long method, large class, long parameter list, deep nesting, duplication, large file). Each finding maps to the principle it hints at plus a suggested refactor. HEURISTICS ONLY — hints, never verdicts; a clean run does not certify good design.

ParametersJSON Schema
NameRequiredDescriptionDefault
codeYesThe source snippet to analyze (one file's worth).
maxDepthNoMax nesting depth (default 4).
maxParamsNoMax parameters (default 4).
longMethodNoMax method lines (default 40).
dupThresholdNoDuplicate-line count (default 3).
maxFileLinesNoMax file lines (default 400).
largeClassMethodsNoMax methods per class (default 12).

Output Schema

ParametersJSON Schema
NameRequiredDescription
countYes
smellsYes

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It clearly discloses that results are 'HEURISTICS ONLY — hints, never verdicts' and that 'a clean run does not certify good design.' This is meaningful behavioral context beyond the schema. It also implies no side effects (read-only scan), though it doesn't mention return format details or performance limits. The heuristic limitation is the key trait and is well disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three concise sentences, each adding essential information: what it scans, what each finding includes, and the critical heuristic caveat. There is no filler or redundant phrasing. The key info is front-loaded, and the caveat is placed appropriately at the end.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 7 parameters but all are documented in the schema, and an output schema exists, the description doesn't need to detail return values. It effectively communicates the tool's behavior and output characteristics (findings mapped to principles and refactors). It lacks a note on input languages or limitations, but for a static analysis heuristic tool, the description covers the essential operational context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. Each parameter (e.g., maxDepth, maxParams) has a clear schema description. The tool description adds context by mapping the smells to the parameters, but doesn't provide additional syntax or interaction details beyond what the schema already offers. It doesn't compensate further because the schema is fully self-explanatory.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Scan') and a clear resource ('a code snippet'), and lists the exact smells detected (long method, large class, etc.). This clearly distinguishes it from sibling tools like list_catalog, explain_concept, and scaffold_pattern, which are unrelated. No ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context by stating its function and the heuristic caveat, but it does not explicitly state when to use this tool over alternatives or when not to use it. There is no mention of prerequisites (e.g., supported languages, input size limits) or exclusions. The sibling tools are sufficiently different that use is implied, but not explicitly guided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

explain_conceptExplain a principle or patternA

Return an authoritative explanation of one design principle or GoF pattern: intent, when to use it, trade-offs, participants, and related concepts. Accepts a slug, full name, or alias (e.g. "SRP", "factory").

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesConcept to explain, e.g. "open-closed", "SRP", "observer".

Output Schema

ParametersJSON Schema
NameRequiredDescription
nameNo
slugNo
foundYes
summaryNo
categoryNo
markdownNo

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It explicitly lists the output sections and input flexibility, making the behavior transparent. It does not detail edge cases or error handling, but these are minor for an explanation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core action, no wasted words. Highly efficient and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with an output schema, the description fully covers what the tool does, what inputs are acceptable, and what the explanation will contain. No gaps remain for the agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single 'name' parameter. The description adds value by explaining accepted formats (slug, full name, alias) with examples, which goes beyond the schema's example string.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool returns an authoritative explanation of a design principle or GoF pattern, listing specific content sections (intent, when to use, trade-offs, participants, related concepts). This distinguishes it from siblings like scaffold_pattern (generation) and check_smells (analysis).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context: use for explanations of design principles/patterns, accepts slug, full name, or alias. Does not explicitly exclude other tools, but the purpose is distinct enough for an agent to infer when to choose this tool over siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_catalogList design principles & patternsA

List the catalog of software-design concepts, optionally filtered by kind. Returns each concept's slug, name, category, and one-line summary.

ParametersJSON Schema
NameRequiredDescriptionDefault
kindNoFilter by kind. "principle" = all principles; "solid"/"oop" narrow to the SOLID five / the four OOP pillars; "pattern" = all GoF patterns. Default "all".

Output Schema

ParametersJSON Schema
NameRequiredDescription
countYes
conceptsYes

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Since no annotations are provided, the description carries the full burden of behavioral transparency. It discloses that the tool returns each concept's slug, name, category, and one-line summary, and that filtering is optional. It does not describe side effects or rate limits, but for a read-only list tool this is sufficient and adds value beyond the tool name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that delivers the core action, the optional filter, and the return payload in a well-structured, front-loaded way. No filler or redundancy is present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with an output schema and no siblings referenced in the description, the description is complete enough: it states what is listed, the filter option, and the fields returned. However, it lacks explicit guidance on when to use this tool rather than sibling tools, which would make it fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides 100% coverage of the 'kind' parameter, including all enum values and their meanings. The description only mentions 'optionally filtered by kind' without adding new parameter-level semantics, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists the catalog of software-design concepts, with a specific verb and resource. It distinguishes itself from siblings (scaffold_pattern, explain_concept, check_smells) by focusing on listing and optionally filtering, rather than scaffolding, explaining, or checking.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for listing concepts and optionally filtering by kind, but it does not explicitly state when to prefer this tool over alternatives like explain_concept or check_smells. No exclusions or alternative references are provided, so the guidance is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

scaffold_patternScaffold a GoF patternA

Generate a language-agnostic pseudo-code skeleton for a GoF pattern, showing its participants and how they collaborate. Optionally rename roles to your domain (e.g. Product -> Notification). Translate the result into your target language.

ParametersJSON Schema
NameRequiredDescriptionDefault
namesNoOptional role→name map, e.g. {"Product":"Notification","Creator":"Dispatcher"}.
patternYesPattern slug/name/alias, e.g. "observer", "factory-method".

Output Schema

ParametersJSON Schema
NameRequiredDescription
okYes
codeNo
nameNo
slugNo
errorNo
rolesNo

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses that the tool generates a language-agnostic pseudo-code skeleton, shows participants and collaboration, and allows role renaming. It also clarifies that the output is not final code by saying 'Translate the result into your target language,' giving meaningful behavioral expectations. It does not discuss side effects or permissions, but for a generator these are not critical and the description is sufficiently transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the primary action, and every sentence serves a purpose. The second sentence expands on optional behavior without redundancy. It is concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (2 params, output schema, nested objects), the description is complete. It explains the main function, optional customization, and the need for translation. The output schema covers return structure, so the description need not repeat it. No critical gaps are present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema fully documents both parameters. The description adds only a minor clarification ('Optionally rename roles to your domain') with an example already present in the schema. Thus it adds little meaning beyond the schema, supporting the baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Generate a language-agnostic pseudo-code skeleton for a GoF pattern.' It specifies the action (generate), the resource (skeleton for a GoF pattern), and the content (participants and collaboration). This distinguishes it from sibling tools like list_catalog, explain_concept, and check_smells.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for scaffolding a pattern and provides context about optional renaming and translation, making it clear when to use it. However, it does not explicitly mention alternatives or exclusions, such as using explain_concept for understanding rather than scaffolding. Thus it is clear context without explicit exclusion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.1.3
    • Changedlist_catalog2 fields changed
      • changedInput schema / properties / kind / description
        Previous value: -"Filter by kind. \"pattern\" = all GoF patterns. Default \"all\"."New value: +"Filter by kind. \"principle\" = all principles; \"solid\"/\"oop\" narrow to the SOLID five / the four OOP pillars; \"pattern\" = all GoF patterns. Default \"all\"."
      • changedInput schema / properties / kind / enum
        Previous value: -[
-  "all",
-  "principle",
-  "pattern",
-  "creational",
-  "structural",
-  "behavioral"
-]New value: +[
+  "all",
+  "principle",
+  "solid",
+  "oop",
+  "pattern",
+  "creational",
+  "structural",
+  "behavioral"
+]
  2. 4 tool updatesv0.1.0
    • First observedcheck_smells
    • First observedexplain_concept
    • First observedlist_catalog
    • First observedscaffold_pattern
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0

Scored across 4 tools

Disambiguation5/5

Each tool targets a distinct operation—analyzing code, explaining a concept, listing the catalog, or generating a skeleton. There is no functional overlap among them.

Naming Consistency5/5

All tool names follow a consistent verb_noun snake_case pattern: check_, explain_, list_, scaffold_. The naming scheme makes the action and target immediately predictable.

Tool Count4/5

Four tools is on the lean side for the broad 'software-design' domain, but each tool occupies a clear role in a focused design-assistant workflow. The count is reasonable, if slightly minimal.

Completeness4/5

The set covers discovery (list_catalog), understanding (explain_concept), application (scaffold_pattern), and analysis (check_smells). Missing capabilities like pattern recommendation or direct refactoring would round it out, but these are workable gaps.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers