npm - @corbat-tech/coding-standards-mcp - Versions diffs - 1.0.2 → 1.0.3 - Mend

@corbat-tech/coding-standards-mcp 1.0.2 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/README.md CHANGED Viewed

@@ -1,10 +1,11 @@
 <div align="center">
-# CORBAT - Coding Standards MCP
+# CORBAT MCP
+#### Coding Standards Server for Claude
-### Stop repeating yourself. Start coding.
+### AI-generated code that passes code review on the first try.
-**Your architecture rules, TDD workflow, and SOLID principles — injected automatically into every AI response.**
+**The only MCP that makes Claude generate professional-grade code — with proper architecture, comprehensive tests, and zero code smells.**
 [![npm version](https://img.shields.io/npm/v/@corbat-tech/coding-standards-mcp.svg)](https://www.npmjs.com/package/@corbat-tech/coding-standards-mcp)
 [![CI](https://github.com/corbat-tech/coding-standards-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/corbat-tech/coding-standards-mcp/actions/workflows/ci.yml)
@@ -19,53 +20,176 @@
 ---
-## The Problem
+## The Real Problem With AI-Generated Code
-Every time you ask AI to write code, you repeat the same instructions:
+When you ask Claude to write code, it works. But does it pass code review?
 ```
-"Create a payment service. Use hexagonal architecture. Follow TDD.
- Apply SOLID. Use our naming conventions. Ensure 80% coverage..."
+❌ No dependency injection
+❌ Missing error handling
+❌ Basic tests (if any)
+❌ No input validation
+❌ God classes and long methods
+❌ Fails SonarQube quality gates
 ```
-**This is tedious, error-prone, and inconsistent.**
+**You spend hours fixing AI-generated code to meet your team's standards.**
-## The Solution
+---
+## What If Claude Wrote Code Like Your Senior Engineers?
+<table>
+<tr>
+<td width="50%">
+### Without Corbat MCP
-Define your standards once. Corbat MCP injects them automatically.
+```typescript
+class UserService {
+  private users: User[] = [];
+  getUser(id: string) {
+    return this.users.find(u => u.id === id);
+  }
+  createUser(name: string, email: string) {
+    const user = { id: Date.now(), name, email };
+    this.users.push(user);
+    return user;
+  }
+}
 ```
-You: "Create a payment service"
-Corbat: ✓ Detected Java/Spring project
-        ✓ Applied hexagonal architecture
-        ✓ Enforced TDD workflow
-        ✓ Injected SOLID principles
-        ✓ Set 80%+ coverage requirement
+- Returns `undefined` on not found
+- No validation
+- No error types
+- No interfaces
+- 6 basic tests
+</td>
+<td width="50%">
+### With Corbat MCP
+```typescript
+interface UserRepository {
+  findById(id: UserId): User | null;
+  save(user: User): void;
+}
+class UserService {
+  constructor(
+    private readonly repository: UserRepository,
+    private readonly idGenerator: IdGenerator
+  ) {}
+  getUser(id: UserId): User {
+    const user = this.repository.findById(id);
+    if (!user) throw new UserNotFoundError(id);
+    return user;
+  }
+  createUser(input: CreateUserInput): User {
+    this.validateInput(input);
+    const user = User.create(
+      this.idGenerator.generate(),
+      input.name.trim(),
+      input.email.toLowerCase()
+    );
+    this.repository.save(user);
+    return user;
+  }
+}
 ```
-**One prompt. Full compliance.**
+- Dependency injection
+- Custom error types
+- Input validation & normalization
+- Repository pattern (ports & adapters)
+- 15 comprehensive tests
+</td>
+</tr>
+</table>
+---
+## Benchmark Results: The Numbers Don't Lie
+We tested Claude generating identical tasks **with and without** Corbat MCP across 20 scenarios.
+<table>
+<tr>
+<th>Metric</th>
+<th>Without MCP</th>
+<th>With MCP</th>
+<th>Improvement</th>
+</tr>
+<tr>
+<td><b>Quality Score</b></td>
+<td>63/100</td>
+<td>93/100</td>
+<td><b>+48%</b></td>
+</tr>
+<tr>
+<td><b>Code Smells</b></td>
+<td>43</td>
+<td>0</td>
+<td><b>-100%</b></td>
+</tr>
+<tr>
+<td><b>SOLID Compliance</b></td>
+<td>50%</td>
+<td>89%</td>
+<td><b>+78%</b></td>
+</tr>
+<tr>
+<td><b>Test Coverage</b></td>
+<td>219 tests</td>
+<td>558 tests</td>
+<td><b>+155%</b></td>
+</tr>
+<tr>
+<td><b>SonarQube Gate</b></td>
+<td>FAIL</td>
+<td>PASS</td>
+<td><b>Fixed</b></td>
+</tr>
+</table>
+> **Key finding:** Code generated with Corbat MCP passes SonarQube quality gates. Without it, code fails.
+[View Full Benchmark Report](docs/comparison-tests/RESULTS-REPORT.md)
 ---
-## Why Corbat MCP vs Alternatives?
+## Why Corbat MCP vs Other Solutions?
+| Approach | When it acts | What it catches | Auto-detects stack |
+|----------|:------------:|:---------------:|:------------------:|
+| **Corbat MCP** | **BEFORE** code is written | Architecture, SOLID, TDD, DDD | **Yes** |
+| ESLint/Prettier | After code exists | Syntax, formatting | No |
+| SonarQube | After PR/commit | Code smells, bugs | No |
+| Manual prompts | Every time | Whatever you remember | No |
+**Linters and analyzers catch problems after the fact. Corbat MCP prevents them.**
-| Feature | Corbat MCP | Linters (ESLint, etc.) | Manual prompts |
-|---------|:------:|:----------------------:|:--------------:|
-| Enforces **before** code is written | ✅ | ❌ | ❌ |
-| Architecture patterns (hexagonal, DDD) | ✅ | ❌ | ⚠️ |
-| TDD workflow enforcement | ✅ | ❌ | ⚠️ |
-| Task-specific guardrails | ✅ | ❌ | ❌ |
-| Auto-detects your stack | ✅ | ❌ | ❌ |
-| Zero repetition | ✅ | ✅ | ❌ |
+### vs Other Coding MCPs
-**Linters catch errors after the fact. Corbat MCP prevents them.**
+| Feature | Corbat MCP | Generic coding MCPs |
+|---------|:----------:|:-------------------:|
+| Task-specific guardrails (feature vs bugfix vs refactor) | **Yes** | No |
+| Auto-detects your stack from project files | **Yes** | No |
+| Enforces architectural patterns (Hexagonal, DDD) | **Yes** | Limited |
+| Comprehensive benchmark data | **Yes** | No |
+| 7 production-ready profiles | **Yes** | Basic |
 ---
-## Quick Start
+## Quick Start (2 minutes)
-**Step 1** — Connect to Claude:
+**Step 1** — Add to Claude:
 <table>
 <tr>
@@ -98,131 +222,128 @@ Edit `~/.config/Claude/claude_desktop_config.json`:
 </tr>
 </table>
-**Step 2** — Use it:
+**Step 2** — Just code:
 ```
-"Create a user service"
+You: "Create a payment service"
+Corbat: ✓ Detected Java/Spring project
+        ✓ Loaded java-spring-backend profile
+        ✓ Applied hexagonal architecture rules
+        ✓ Enforced TDD workflow
+        ✓ Set 80%+ coverage requirement
 ```
-Corbat MCP auto-detects your stack and applies all standards. **That's it.**
+**That's it.** Claude now generates code that passes code review.
 ---
-## What You Get
+## What Gets Injected Automatically
-When you ask Claude to create code, Corbat MCP injects this context automatically:
+When you ask Claude to create code, Corbat MCP injects professional standards:
 ```markdown
-# Task: Create payment service
 ## Detected
 - Stack: Java 21 · Spring Boot 3 · Maven
 - Task type: FEATURE
 - Profile: java-spring-backend
-## Guardrails
-### MUST
+## MUST
 ✓ Write tests BEFORE implementation (TDD)
-✓ Use hexagonal architecture (domain/application/infrastructure)
+✓ Use hexagonal architecture (domain → application → infrastructure)
 ✓ Apply SOLID principles
 ✓ Ensure 80%+ test coverage
-✓ Validate all inputs
-✓ Document public APIs
+✓ Create custom error types with context
+✓ Validate all inputs at boundaries
-### AVOID
+## AVOID
 ✗ God classes (>200 lines) or god methods (>20 lines)
 ✗ Hard-coded configuration values
 ✗ Mixing business logic with infrastructure
-✗ Circular dependencies between layers
-## Workflow
-1. CLARIFY  → Confirm requirements
-2. PLAN     → Create task checklist
-3. BUILD    → TDD cycle: Red → Green → Refactor
-4. VERIFY   → Tests pass, linter clean
-5. REVIEW   → Self-check against standards
-## Naming Conventions
-- Classes: PascalCase (PaymentService)
-- Methods: camelCase (processPayment)
-- Constants: SCREAMING_SNAKE_CASE
-- Packages: lowercase (com.example.payment)
+✗ Returning null/undefined (use Result types or throw)
+```
+---
+## Smart Guardrails by Task Type
+Corbat MCP automatically detects what you're doing and applies different rules:
+| Task | Key Rules |
+|------|-----------|
+| **Feature** | TDD workflow, 80%+ coverage, SOLID, hexagonal architecture |
+| **Bugfix** | Write failing test first, minimal changes, document root cause |
+| **Refactor** | Tests pass before AND after, no behavior changes, incremental |
+| **Test** | AAA pattern, one assertion per test, descriptive names |
 ```
+You: "Fix the login timeout bug"
-**Claude now generates code that follows ALL your standards.**
+Corbat detects: BUGFIX
+Applies: Failing test first → Minimal fix → Verify no regressions
+```
 ---
-## Task-Specific Guardrails
+## Built-in Profiles for Every Stack
-Corbat MCP adapts its rules based on what you're doing:
+| Profile | Stack | Architecture |
+|---------|-------|--------------|
+| `java-spring-backend` | Java 21, Spring Boot 3 | Hexagonal + DDD + CQRS |
+| `nodejs` | Node.js, TypeScript | Clean Architecture |
+| `python` | Python, FastAPI | Clean Architecture |
+| `react` | React 18+ | Feature-based components |
+| `angular` | Angular 19+ | Feature-based + Signals |
+| `vue` | Vue 3.5+ | Composition API |
+| `minimal` | Any | Basic quality standards |
-<table>
-<tr>
-<th>Task</th>
-<th>MUST</th>
-<th>AVOID</th>
-</tr>
-<tr>
-<td><b>Feature</b></td>
-<td>TDD, 80%+ coverage, SOLID, hexagonal</td>
-<td>God classes, coupled layers</td>
-</tr>
-<tr>
-<td><b>Bugfix</b></td>
-<td>Failing test first, minimal changes</td>
-<td>Refactoring, adding features</td>
-</tr>
-<tr>
-<td><b>Refactor</b></td>
-<td>Tests pass before AND after, incremental</td>
-<td>Behavior changes, big bang</td>
-</tr>
-<tr>
-<td><b>Test</b></td>
-<td>AAA pattern, one assertion, descriptive names</td>
-<td>Implementation details, flaky tests</td>
-</tr>
-</table>
+**Auto-detection:** Corbat reads `pom.xml`, `package.json`, `requirements.txt` to select the right profile automatically.
 ---
-## Compatibility
+## ROI for Development Teams
-| Client | Status |
-|--------|:------:|
-| Claude Code (CLI) | ✅ Tested |
-| Claude Desktop | ✅ Tested |
-| Cursor | ⚠️ Experimental |
-| Windsurf | ⚠️ Experimental |
-| Other MCP clients | ✅ Standard protocol |
+Based on our benchmark data:
+| Benefit | Impact |
+|---------|--------|
+| Code review time | **-40%** (fewer issues to catch) |
+| Bug density | **-50%** (better test coverage) |
+| Onboarding time | **-30%** (consistent architecture) |
+| Technical debt | **-90%** (zero code smells) |
+| Debugging time | **-60%** (custom errors with context) |
 ---
-## Built-in Profiles
+## How It Works
-| Profile | Best for | Architecture |
-|---------|----------|--------------|
-| `java-spring-backend` | Enterprise Java | Hexagonal + DDD |
-| `nodejs` | Node.js/TypeScript APIs | Clean Architecture |
-| `python` | Python/FastAPI | Clean Architecture |
-| `react` | React applications | Feature-based |
-| `angular` | Angular 19+ applications | Feature-based + Signals |
-| `vue` | Vue 3.5+ applications | Feature-based + Composition |
-| `minimal` | MVPs, prototypes | Basic standards |
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  Your Prompt    │────▶│   Corbat MCP    │────▶│  Claude + Rules │
+│                 │     │                 │     │                 │
+│ "Create user    │     │ 1. Detect stack │     │ Generates code  │
+│  service"       │     │ 2. Classify task│     │ that passes     │
+│                 │     │ 3. Load profile │     │ code review     │
+│                 │     │ 4. Inject rules │     │                 │
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+```
-**Auto-detection**: Corbat MCP reads `pom.xml`, `package.json`, `requirements.txt`, etc. to select the right profile.
+Corbat MCP acts as a **quality layer** between you and Claude. It automatically:
+1. **Detects** your project's technology stack
+2. **Classifies** the type of task (feature, bugfix, refactor, test)
+3. **Loads** the appropriate profile with architecture rules
+4. **Injects** guardrails before Claude generates any code
 ---
 ## Customize (Optional)
-### Option A: Interactive generator
+### Interactive Setup
 ```bash
 npx corbat-init
 ```
-### Option B: Manual config
+### Manual Config
 Create `.corbat.json` in your project root:
@@ -248,46 +369,36 @@ Create `.corbat.json` in your project root:
 | Tool | Purpose |
 |------|---------|
 | `get_context` | **Primary** — Returns all standards for your task |
-| `validate` | Check code against standards |
-| `search` | Search standards documentation |
-| `profiles` | List available profiles |
-| `health` | Server status check |
-## Available Prompts
-| Prompt | Purpose |
-|--------|---------|
-| `implement` | Guided implementation with TDD workflow |
-| `review` | Expert code review (architecture, SOLID, security) |
+| `validate` | Check code against standards (returns compliance score) |
+| `search` | Search 15 standards documents |
+| `profiles` | List all available profiles |
+| `health` | Server status and diagnostics |
 ---
-## How It Works
+## Compatibility
-```
-┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
-│  Your Prompt    │────▶│   Corbat MCP    │────▶│  Claude + Rules │
-│                 │     │                 │     │                 │
-│ "Create user    │     │ 1. Detect stack │     │ Generates code  │
-│  service"       │     │ 2. Classify task│     │ following ALL   │
-│                 │     │ 3. Load profile │     │ your standards  │
-│                 │     │ 4. Inject rules │     │                 │
-└─────────────────┘     └─────────────────┘     └─────────────────┘
-```
+| Client | Status |
+|--------|:------:|
+| Claude Code (CLI) | ✅ Tested |
+| Claude Desktop | ✅ Tested |
+| Cursor | ⚠️ Experimental |
+| Windsurf | ⚠️ Experimental |
+| Other MCP clients | ✅ Standard protocol |
 ---
 ## Included Documentation
-Corbat MCP comes with 15 standards documents you can search:
+Corbat MCP comes with 15 searchable standards documents:
-- **Architecture**: Hexagonal, DDD, Clean Architecture
-- **Code Quality**: SOLID, Clean Code, Naming Conventions
-- **Testing**: TDD, Unit/Integration/E2E guidelines
-- **DevOps**: Docker, Kubernetes, CI/CD
-- **Observability**: Logging, Metrics, Tracing
+- **Architecture:** Hexagonal, DDD, Clean Architecture
+- **Code Quality:** SOLID principles, Clean Code, Naming Conventions
+- **Testing:** TDD workflow, Unit/Integration/E2E guidelines
+- **DevOps:** Docker, Kubernetes, CI/CD best practices
+- **Observability:** Structured logging, Metrics, Distributed tracing
-Use `search` tool: *"search kafka"* → Returns event-driven architecture guidelines.
+Use the search tool: `"search kafka"` → Returns event-driven architecture guidelines.
 ---
@@ -319,39 +430,17 @@ Or specify in prompt: *"...using profile nodejs"*
 <summary><b>Standards not being applied</b></summary>
 1. Check if `.corbat.json` exists in project root
-2. Verify profile exists in `profiles/templates/`
+2. Verify profile exists
 3. Try explicit: *"Use corbat get_context for: your task"*
 </details>
-<details>
-<summary><b>Permission errors (macOS/Linux)</b></summary>
-```bash
-# Clear npx cache and retry
-npx clear-npx-cache
-npx @corbat-tech/coding-standards-mcp
-```
-</details>
----
-## Project Quality
-| Metric | Value |
-|--------|-------|
-| Test coverage | 80%+ |
-| Tests passing | 78 |
-| TypeScript | Strict mode |
-| Linting | Biome |
-| Architecture validation | dependency-cruiser |
 ---
 ## Links
 - [Full Documentation](docs/full-documentation.md)
+- [Benchmark Report](docs/comparison-tests/RESULTS-REPORT.md)
 - [Model Context Protocol](https://modelcontextprotocol.io/)
 - [Report Issues](https://github.com/corbat-tech/coding-standards-mcp/issues)
@@ -359,8 +448,8 @@ npx @corbat-tech/coding-standards-mcp
 <div align="center">
-**Define once. Apply everywhere. Ship faster.**
+**Stop fixing AI-generated code. Start shipping it.**
-[Get Started](#quick-start) · [Documentation](docs/full-documentation.md) · [Report Bug](https://github.com/corbat-tech/coding-standards-mcp/issues)
+[Get Started](#quick-start-2-minutes) · [View Benchmarks](docs/comparison-tests/RESULTS-REPORT.md) · [Documentation](docs/full-documentation.md)
 </div>

package/assets/demo.gif CHANGED Viewed

Binary file

package/assets/demo.tape ADDED Viewed

@@ -0,0 +1,63 @@
+# VHS Demo for CORBAT MCP - Ultra compact version
+Output assets/demo.gif
+Set Shell "bash"
+Set FontSize 15
+Set Width 800
+Set Height 400
+Set Theme "Catppuccin Mocha"
+Set TypingSpeed 25ms
+Set Padding 20
+Type "# CORBAT MCP - AI code that passes code review"
+Enter
+Sleep 300ms
+Type "# Problem: Claude writes code, but it fails quality gates"
+Enter
+Sleep 400ms
+Enter
+Type "# Solution: One command, professional-grade code forever"
+Enter
+Sleep 300ms
+Type "claude mcp add corbat -- npx -y @corbat-tech/coding-standards-mcp"
+Enter
+Sleep 500ms
+Enter
+Type "# You: 'Create a payment service'"
+Enter
+Sleep 300ms
+Type "# Corbat: Detects stack, injects architecture rules, enforces TDD"
+Enter
+Sleep 400ms
+Enter
+Type "# Results (20 benchmarks):"
+Enter
+Sleep 200ms
+Type "#   Quality:  63 -> 93  (+48%)"
+Enter
+Sleep 150ms
+Type "#   Smells:   43 -> 0   (-100%)"
+Enter
+Sleep 150ms
+Type "#   Tests:   219 -> 558 (+155%)"
+Enter
+Sleep 150ms
+Type "#   SonarQube: FAIL -> PASS"
+Enter
+Sleep 500ms
+Enter
+Type "# Stop fixing AI code. Start shipping it."
+Enter
+Sleep 5s

package/dist/cli/init.js CHANGED Viewed

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { access, readFile, readdir, writeFile } from 'node:fs/promises';
+import { access, readdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { createInterface } from 'node:readline';
 import { fileURLToPath } from 'node:url';