mcp-software-design 0.1.1 → 0.1.3

package/README.md

@@ -1,14 +1,41 @@
 # mcp-software-design
 
+[![npm version](https://img.shields.io/npm/v/mcp-software-design)](https://www.npmjs.com/package/mcp-software-design)
+[![npm downloads](https://img.shields.io/npm/dm/mcp-software-design)](https://www.npmjs.com/package/mcp-software-design)
+[![License: MIT](https://img.shields.io/npm/l/mcp-software-design)](./LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-server-blue)](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, and the 23 Gang-of-Four design patterns — plus pattern
-scaffolding and heuristic code-smell detection.
+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`](../mcp-udacity-commit): same stack (TypeScript, the MCP
+[`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.
@@ -33,7 +60,8 @@ pretending to understand your snippet.
 ## Tools
 
 - **`list_catalog`** `{ kind? }` — list concepts, optionally filtered
-  (`principle` | `pattern` | `creational` | `structural` | `behavioral`).
+  (`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"`).
@@ -47,7 +75,8 @@ pretending to understand your snippet.
 
 ## Resources
 
-- **`design://principles`** — SOLID, OOP pillars, DRY, KISS, YAGNI, and more.
+- **`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
@@ -60,7 +89,10 @@ pretending to understand your snippet.
 - **`apply_pattern`** `{ pattern, code }` — refactor a snippet to apply a named
   pattern (and first judge whether it even fits).
 
-## Install & run
+## Build from source
+
+For local development, or to run a local checkout instead of the published
+package:
 
 ```bash
 npm install
@@ -70,25 +102,14 @@ npm test           # builds, then runs the unit tests
 npm run test:client  # end-to-end check against the built server
 ```
 
-### Register with Claude Code
+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
 ```
 
-Or in an MCP client config:
-
-```json
-{
-  "mcpServers": {
-    "software-design": {
-      "command": "node",
-      "args": ["/absolute/path/to/mcp-software-design/build/index.js"]
-    }
-  }
-}
-```
-
 ## Layout
 
 ```

package/build/catalog.js

@@ -166,6 +166,52 @@ export const PRINCIPLES = [
         ],
         related: ["kiss", "open-closed"],
     },
+    {
+        slug: "meaningful-names",
+        name: "Meaningful Names",
+        category: "principle",
+        aka: ["intention-revealing-names", "naming", "self-documenting-code"],
+        summary: "Names should reveal intent — reach for a word before a comment.",
+        intent: "A name is the first documentation a reader meets. Prefer intention-" +
+            "revealing names that state what a value is or what a function does, so " +
+            "the code explains itself without a comment. Single-letter names are fine " +
+            "in tiny scopes — loop counters, short lambda parameters, coordinates/math " +
+            "— but hide meaning the moment a value outlives a line or two.",
+        whenToUse: [
+            "A variable needs a comment to explain what it holds.",
+            "You reach for `data`, `tmp`, `mgr`, or `x2` because the real name is hard.",
+            "A single-letter name is used far from where it was declared.",
+        ],
+        tradeoffs: [
+            "Over-long names (userAccountRepositoryFactoryInstance) hurt readability as much as cryptic ones.",
+            "Conventional short names beat forced verbosity — `i` in a for-loop, `e` for an event.",
+            "Renaming for clarity is cheap; keep established public/API names stable to avoid churn.",
+        ],
+        related: ["kiss", "single-responsibility", "separation-of-concerns"],
+    },
+    {
+        slug: "clean-code",
+        name: "Clean Code",
+        category: "principle",
+        aka: ["readability", "craftsmanship"],
+        summary: "Code is read far more than it's written — optimize for the reader.",
+        intent: "Clean Code is an umbrella habit, not a single rule: write code a later " +
+            "reader (usually you) can understand quickly and change safely. It's the " +
+            "sum of the concrete principles here — intention-revealing names, small " +
+            "single-purpose units, no duplication, and the simplest thing that works — " +
+            "rather than a separate technique of its own.",
+        whenToUse: [
+            "You hesitate to touch a file because you don't understand it.",
+            "Reviewers keep asking 'what does this do?' about the same code.",
+            "Reading the change takes longer than making it.",
+        ],
+        tradeoffs: [
+            "'Clean' is contextual — a throwaway script and a core library deserve different bars.",
+            "Endless renaming/extracting has diminishing returns; stop once it reads clearly.",
+            "Cleanliness is not correctness — clean code can still be wrong; tests decide behavior.",
+        ],
+        related: ["meaningful-names", "single-responsibility", "dry", "kiss"],
+    },
     {
         slug: "composition-over-inheritance",
         name: "Composition Over Inheritance",
@@ -854,6 +900,34 @@ export const PATTERNS = [
  * Lookup + rendering
  * ------------------------------------------------------------------ */
 export const ALL = [...PRINCIPLES, ...PATTERNS];
+/** The five SOLID principles, by slug. */
+const SOLID_SLUGS = new Set([
+    "single-responsibility",
+    "open-closed",
+    "liskov-substitution",
+    "interface-segregation",
+    "dependency-inversion",
+]);
+/** The four classic OOP pillars, by slug. */
+const OOP_SLUGS = new Set([
+    "encapsulation",
+    "abstraction",
+    "inheritance",
+    "polymorphism",
+]);
+/**
+ * Which sub-group a concept belongs to. Patterns and the remaining principles
+ * (DRY, KISS, YAGNI, composition-over-inheritance, law-of-demeter,
+ * separation-of-concerns) are "general". Drives the "solid"/"oop" filters on
+ * the list_catalog tool.
+ */
+export function principleGroup(concept) {
+    if (SOLID_SLUGS.has(concept.slug))
+        return "solid";
+    if (OOP_SLUGS.has(concept.slug))
+        return "oop";
+    return "general";
+}
 /** Normalize a query for fuzzy matching: lowercase, strip non-alphanumerics. */
 function normalize(text) {
     return text.toLowerCase().replace(/[^a-z0-9]+/g, "");

package/build/index.js

@@ -1,11 +1,18 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { ALL, CATEGORY_LABEL, conceptLine, conceptToMarkdown, findConcept, principlesMarkdown, patternsMarkdown, } from "./catalog.js";
+import { ALL, CATEGORY_LABEL, conceptLine, conceptToMarkdown, findConcept, principleGroup, principlesMarkdown, patternsMarkdown, } from "./catalog.js";
 import { detectSmells, DEFAULTS } from "./smells.js";
 import { scaffoldPattern } from "./scaffold.js";
-const VERSION = "0.1.0";
+/**
+ * Single source of truth: read the version from package.json at startup so it
+ * can never drift from the published package. Resolved relative to this module,
+ * so it works both from `build/` in the repo and from the installed package
+ * (npm ships package.json alongside build/).
+ */
+const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 /** Human-readable summary of what the smell checker looks for. */
 const SMELLS_GUIDE = `# Code-smell heuristics (design://smells)
 
@@ -65,9 +72,11 @@ export function createServer() {
             "kind. Returns each concept's slug, name, category, and one-line summary.",
         inputSchema: {
             kind: z
-                .enum(["all", "principle", "pattern", "creational", "structural", "behavioral"])
+                .enum(["all", "principle", "solid", "oop", "pattern", "creational", "structural", "behavioral"])
                 .optional()
-                .describe('Filter by kind. "pattern" = all GoF patterns. Default "all".'),
+                .describe('Filter by kind. "principle" = all principles; "solid"/"oop" narrow ' +
+                'to the SOLID five / the four OOP pillars; "pattern" = all GoF ' +
+                'patterns. Default "all".'),
         },
         outputSchema: {
             count: z.number(),
@@ -85,6 +94,10 @@ export function createServer() {
                 return true;
             if (selectedKind === "principle")
                 return concept.category === "principle";
+            if (selectedKind === "solid")
+                return principleGroup(concept) === "solid";
+            if (selectedKind === "oop")
+                return principleGroup(concept) === "oop";
             if (selectedKind === "pattern")
                 return concept.category !== "principle";
             return concept.category === selectedKind;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-software-design",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "MCP server that teaches and applies software-design guidance: SOLID/OOP/DRY principles, the 23 GoF design patterns, pattern scaffolding, and heuristic code-smell detection.",
   "type": "module",
   "license": "MIT",
@@ -12,13 +12,21 @@
   },
   "keywords": [
     "mcp",
+    "mcp-server",
     "modelcontextprotocol",
+    "model-context-protocol",
+    "claude",
+    "developer-tools",
+    "software-design",
     "design-patterns",
+    "design-principles",
     "solid",
     "oop",
     "gof",
+    "gang-of-four",
     "refactoring",
-    "claude"
+    "clean-code",
+    "code-smells"
   ],
   "bin": {
     "mcp-software-design": "build/index.js"