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

package/README.md

@@ -1,455 +1,351 @@
 <div align="center">
 
 # CORBAT MCP
-#### Coding Standards Server for Claude
+#### AI Coding Standards Server
 
-### AI-generated code that passes code review on the first try.
-
-**The only MCP that makes Claude generate professional-grade code — with proper architecture, comprehensive tests, and zero code smells.**
+**AI-generated code that passes code review on the first try.**
 
 [![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)
+[![Coverage](https://img.shields.io/badge/coverage-82%25-brightgreen.svg)](https://github.com/corbat-tech/coding-standards-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![MCP](https://img.shields.io/badge/MCP-1.0-blue.svg)](https://modelcontextprotocol.io/)
 
-</div>
-
-<p align="center">
-  <img src="assets/demo.gif" alt="CORBAT Demo" width="800">
-</p>
-
 ---
 
-## The Real Problem With AI-Generated Code
+[![Cursor](https://img.shields.io/badge/Cursor-✓-black?style=flat-square&logo=cursor)](docs/setup.md#cursor)
+[![VS Code](https://img.shields.io/badge/VS_Code-✓-007ACC?style=flat-square&logo=visualstudiocode)](docs/setup.md#vs-code)
+[![Windsurf](https://img.shields.io/badge/Windsurf-✓-00C7B7?style=flat-square)](docs/setup.md#windsurf)
+[![JetBrains](https://img.shields.io/badge/JetBrains-✓-orange?style=flat-square&logo=jetbrains)](docs/setup.md#jetbrains-ides)
+[![Zed](https://img.shields.io/badge/Zed-✓-084CCF?style=flat-square)](docs/setup.md#zed)
+[![Claude](https://img.shields.io/badge/Claude-✓-cc785c?style=flat-square)](docs/setup.md#claude-desktop)
 
-When you ask Claude to write code, it works. But does it pass code review?
+**Works with GitHub Copilot, Continue, Cline, Tabnine, Amazon Q, and [25+ more tools](docs/compatibility.md)**
 
-```
-❌ No dependency injection
-❌ Missing error handling
-❌ Basic tests (if any)
-❌ No input validation
-❌ God classes and long methods
-❌ Fails SonarQube quality gates
-```
-
-**You spend hours fixing AI-generated code to meet your team's standards.**
+</div>
 
 ---
 
-## What If Claude Wrote Code Like Your Senior Engineers?
+## The Problem
 
-<table>
-<tr>
-<td width="50%">
+AI-generated code works, but rarely passes code review:
 
-### Without Corbat MCP
+| Without Corbat | With Corbat |
+|----------------|-------------|
+| No dependency injection | Proper DI with interfaces |
+| Missing error handling | Custom error types with context |
+| Basic tests (if any) | 80%+ coverage with TDD |
+| God classes, long methods | SOLID, max 20 lines/method |
+| Fails SonarQube | Passes quality gates |
 
-```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;
-  }
-}
-```
+**Result:** Production-ready code that passes code review.
 
-- 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
-  ) {}
+## Quick Start
 
-  getUser(id: UserId): User {
-    const user = this.repository.findById(id);
-    if (!user) throw new UserNotFoundError(id);
-    return user;
-  }
+**1. Add to your MCP config:**
 
-  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;
+```json
+{
+  "mcpServers": {
+    "corbat": {
+      "command": "npx",
+      "args": ["-y", "@corbat-tech/coding-standards-mcp"]
+    }
   }
 }
 ```
 
-- Dependency injection
-- Custom error types
-- Input validation & normalization
-- Repository pattern (ports & adapters)
-- 15 comprehensive tests
+**2. Config file location:**
 
-</td>
-</tr>
-</table>
+| Tool | Location |
+|------|----------|
+| Cursor | `.cursor/mcp.json` |
+| VS Code | `.vscode/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| JetBrains | Settings → AI Assistant → MCP |
+| Claude Desktop | `~/.config/Claude/claude_desktop_config.json` |
+| Claude Code | `claude mcp add corbat -- npx -y @corbat-tech/coding-standards-mcp` |
 
----
+> [Complete setup guide](docs/setup.md) for all 25+ tools
 
-## Benchmark Results: The Numbers Don't Lie
+**3. Done!** Corbat auto-detects your stack.
 
-We tested Claude generating identical tasks **with and without** Corbat MCP across 20 scenarios.
+```
+You: "Create a payment service"
 
-<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>
+Corbat: ✓ Detected: Java 21, Spring Boot 3, Maven
+        ✓ Profile: java-spring-backend
+        ✓ Architecture: Hexagonal + DDD
+        ✓ Testing: TDD, 80%+ coverage
+```
 
-> **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)
+## Benchmark Results v2.0
 
----
+### Overall Impact
 
-## Why Corbat MCP vs Other Solutions?
+<div align="center">
 
-| 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 |
+| Metric | Without Corbat | With Corbat | **Improvement** |
+|--------|:--------------:|:-----------:|:---------------:|
+| **Quality Score** | 4.6/10 | 7.7/10 | **+67%** |
+| **Custom Errors** | 3 | 18 | **+500%** |
+| **Interfaces/Ports** | 19 | 41 | **+116%** |
+| **Files (modularity)** | 55 | 95 | **+73%** |
 
-**Linters and analyzers catch problems after the fact. Corbat MCP prevents them.**
+</div>
 
-### vs Other Coding MCPs
+### By Complexity Level
 
-| 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 |
+| Category | Scenarios | Without | With | **Improvement** |
+|----------|-----------|:-------:|:----:|:---------------:|
+| **Basic** | UserService, REST API, React Form | 4.0 | 7.6 | **+90%** |
+| **Intermediate** | Kafka Consumer, FastAPI, Go HTTP | 4.3 | 7.2 | **+67%** |
+| **Advanced** | Saga, Circuit Breaker, Event Sourcing | 5.6 | 8.2 | **+46%** |
 
----
+### Pattern Detection
 
-## Quick Start (2 minutes)
+| Pattern | Without Corbat | With Corbat |
+|---------|:--------------:|:-----------:|
+| Hexagonal Architecture | 0/10 scenarios | **10/10** |
+| Repository Pattern | 2/10 | **7/10** |
+| Custom Error Types | 1/10 | **8/10** |
+| Dependency Injection | 2/10 | **10/10** |
+| Saga Pattern | 0/10 | **1/1** (when needed) |
 
-**Step 1** — Add to Claude:
+### Real Example: Saga Pattern (Scenario 07)
 
 <table>
 <tr>
-<td><b>Claude Code</b></td>
+<th>Without Corbat</th>
+<th>With Corbat</th>
+</tr>
+<tr>
 <td>
 
-```bash
-claude mcp add corbat -- npx -y @corbat-tech/coding-standards-mcp
+```java
+// Hardcoded rollback, not extensible
+try {
+  targetAccount.credit(amount);
+} catch (Exception e) {
+  rollbackDebit(sourceAccount, amount);
+  throw new TransferException(...);
+}
 ```
 
 </td>
-</tr>
-<tr>
-<td><b>Claude Desktop</b></td>
 <td>
 
-Edit `~/.config/Claude/claude_desktop_config.json`:
-```json
-{
-  "mcpServers": {
-    "corbat": {
-      "command": "npx",
-      "args": ["-y", "@corbat-tech/coding-standards-mcp"]
+```java
+// Reusable Saga Pattern
+public interface SagaStep<T> {
+  void execute(T context);
+  void compensate(T context);
+}
+
+public class SagaOrchestrator<T> {
+  public void execute(T context) {
+    for (SagaStep<T> step : steps) {
+      step.execute(context);
+      executedSteps.add(step);
     }
   }
+  // Auto-rollback on failure
 }
 ```
 
 </td>
 </tr>
+<tr>
+<td>9 files, 292 LOC, manual rollback</td>
+<td><b>17 files, 707 LOC, orchestrated compensation</b></td>
+</tr>
 </table>
 
-**Step 2** — Just code:
-
-```
-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
-```
-
-**That's it.** Claude now generates code that passes code review.
+[View full benchmark analysis with 10 scenarios](benchmarks/v2/ANALYSIS.md)
 
 ---
 
-## What Gets Injected Automatically
-
-When you ask Claude to create code, Corbat MCP injects professional standards:
-
-```markdown
-## Detected
-- Stack: Java 21 · Spring Boot 3 · Maven
-- Task type: FEATURE
-- Profile: java-spring-backend
-
-## MUST
-✓ Write tests BEFORE implementation (TDD)
-✓ Use hexagonal architecture (domain → application → infrastructure)
-✓ Apply SOLID principles
-✓ Ensure 80%+ test coverage
-✓ Create custom error types with context
-✓ Validate all inputs at boundaries
-
-## AVOID
-✗ God classes (>200 lines) or god methods (>20 lines)
-✗ Hard-coded configuration values
-✗ Mixing business logic with infrastructure
-✗ Returning null/undefined (use Result types or throw)
-```
-
----
+## Code Comparison
 
-## Smart Guardrails by Task Type
+### Before: Without Corbat MCP
 
-Corbat MCP automatically detects what you're doing and applies different rules:
+```typescript
+class UserService {
+  private users: Map<string, User> = new Map();
 
-| 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 |
+  getById(id: string): User | undefined {
+    return this.users.get(id);
+  }
 
+  createUser(input: CreateUserInput): User {
+    if (!input.name) throw new Error('Name is required');
+    const user = { id: uuidv4(), ...input };
+    this.users.set(user.id, user);
+    return user;
+  }
+}
+// ✗ Returns undefined  ✗ Generic errors  ✗ No DI  ✗ Hardcoded storage
 ```
-You: "Fix the login timeout bug"
 
-Corbat detects: BUGFIX
-Applies: Failing test first → Minimal fix → Verify no regressions
-```
+### After: With Corbat MCP
 
----
+```typescript
+// Port (interface)
+interface UserRepository {
+  findById(id: string): User | null;
+  save(user: User): void;
+  existsByEmail(email: string): boolean;
+}
 
-## Built-in Profiles for Every Stack
+// Custom errors
+class UserNotFoundError extends Error { /*...*/ }
+class UserAlreadyExistsError extends Error { /*...*/ }
+class InvalidUserInputError extends Error { /*...*/ }
 
-| 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 |
+// Service with DI
+class UserService {
+  constructor(
+    private readonly repository: UserRepository,
+    private readonly idGenerator: IdGenerator
+  ) {}
 
-**Auto-detection:** Corbat reads `pom.xml`, `package.json`, `requirements.txt` to select the right profile automatically.
+  getUserById(id: string): User {
+    const user = this.repository.findById(id);
+    if (!user) throw new UserNotFoundError(id);
+    return user;
+  }
 
----
+  createUser(input: CreateUserInput): User {
+    this.validateInput(input);
+    this.ensureEmailNotTaken(input.email);
+    const user = createUser(this.idGenerator.generate(), input);
+    this.repository.save(user);
+    return user;
+  }
+}
+// ✓ Repository interface  ✓ 3 custom errors  ✓ DI  ✓ 11 tests  ✓ Testable
+```
 
-## ROI for Development Teams
+**Result:** 3 files → 7 files | 129 LOC → 308 LOC | 0 interfaces → 4 interfaces | 0 custom errors → 3
 
-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
+
+| Profile | Stack | Architecture | Testing |
+|---------|-------|--------------|---------|
+| `java-spring-backend` | Java 21 + Spring Boot 3 | Hexagonal + DDD + CQRS | TDD, 80%+ coverage |
+| `kotlin-spring` | Kotlin + Spring Boot 3 | Hexagonal + Coroutines | Kotest, MockK |
+| `nodejs` | Node.js + TypeScript | Clean Architecture | Vitest |
+| `nextjs` | Next.js 14+ | Feature-based + RSC | Vitest, Playwright |
+| `react` | React 18+ | Feature-based | Testing Library |
+| `vue` | Vue 3.5+ | Feature-based | Vitest |
+| `angular` | Angular 19+ | Feature modules | Jest |
+| `python` | Python + FastAPI | Hexagonal + async | pytest |
+| `go` | Go 1.22+ | Clean + idiomatic | Table-driven tests |
+| `rust` | Rust + Axum | Clean + ownership | Built-in + proptest |
+| `csharp-dotnet` | C# 12 + ASP.NET Core 8 | Clean + CQRS | xUnit, FluentAssertions |
+| `flutter` | Dart 3 + Flutter | Clean + BLoC/Riverpod | flutter_test |
+| `minimal` | Any | Basic quality rules | Optional |
+
+**Auto-detection:** Corbat reads `pom.xml`, `package.json`, `go.mod`, `Cargo.toml`, `pubspec.yaml`, `*.csproj` to select the right profile.
+
+### Architecture Patterns Enforced
+
+- **Hexagonal Architecture** — Ports & Adapters, infrastructure isolation
+- **Domain-Driven Design** — Aggregates, Value Objects, Domain Events
+- **SOLID Principles** — Single responsibility, dependency inversion
+- **Clean Code** — Max 20 lines/method, meaningful names, no magic numbers
+- **Error Handling** — Custom exceptions with context, no generic catches
+- **Testing** — TDD workflow, unit + integration, mocking strategies
 
 ---
 
-## How It Works
+## Customize
 
-```
-┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
-│  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 │     │                 │
-└─────────────────┘     └─────────────────┘     └─────────────────┘
-```
+### Ready-to-use templates
 
-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
+Copy a production-ready configuration for your stack:
 
----
+**[Browse 14 templates](docs/templates.md)** — Java, Python, Node.js, React, Vue, Angular, Go, Kotlin, Rust, Flutter, and more.
 
-## Customize (Optional)
+### Generate a custom profile
 
-### Interactive Setup
 ```bash
 npx corbat-init
 ```
 
-### Manual Config
+Interactive wizard that auto-detects your stack and lets you configure architecture, DDD patterns, and quality metrics.
+
+### Manual config
 
 Create `.corbat.json` in your project root:
 
 ```json
 {
-  "profile": "nodejs",
+  "profile": "java-spring-backend",
+  "architecture": {
+    "pattern": "hexagonal",
+    "layers": ["domain", "application", "infrastructure", "api"]
+  },
+  "ddd": {
+    "aggregates": true,
+    "valueObjects": true,
+    "domainEvents": true
+  },
+  "quality": {
+    "maxMethodLines": 20,
+    "maxClassLines": 200,
+    "minCoverage": 80
+  },
   "rules": {
-    "always": [
-      "Use TypeScript strict mode",
-      "Prefer functional programming"
-    ],
-    "never": [
-      "Use any type"
-    ]
+    "always": ["Use records for DTOs", "Prefer Optional over null"],
+    "never": ["Use field injection", "Catch generic Exception"]
   }
 }
 ```
 
 ---
 
-## Available Tools
-
-| Tool | Purpose |
-|------|---------|
-| `get_context` | **Primary** — Returns all standards for your task |
-| `validate` | Check code against standards (returns compliance score) |
-| `search` | Search 15 standards documents |
-| `profiles` | List all available profiles |
-| `health` | Server status and diagnostics |
-
----
-
-## Compatibility
-
-| 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 searchable standards documents:
-
-- **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 the search tool: `"search kafka"` → Returns event-driven architecture guidelines.
-
----
-
-## Troubleshooting
-
-<details>
-<summary><b>Claude can't find corbat</b></summary>
-
-1. Verify npm/npx is in PATH: `which npx`
-2. Test manually: `npx @corbat-tech/coding-standards-mcp`
-3. Restart Claude completely
-4. Check Claude's MCP logs
-
-</details>
-
-<details>
-<summary><b>Wrong stack detected</b></summary>
+## How It Works
 
-Override with `.corbat.json`:
-```json
-{ "profile": "nodejs" }
 ```
-
-Or specify in prompt: *"...using profile nodejs"*
-
-</details>
-
-<details>
-<summary><b>Standards not being applied</b></summary>
-
-1. Check if `.corbat.json` exists in project root
-2. Verify profile exists
-3. Try explicit: *"Use corbat get_context for: your task"*
-
-</details>
+Your Prompt ──▶ Corbat MCP ──▶ AI + Standards
+                    │
+                    ├─ 1. Detect stack (pom.xml, package.json...)
+                    ├─ 2. Classify task (feature, bugfix, refactor)
+                    ├─ 3. Load profile with architecture rules
+                    └─ 4. Inject guardrails before code generation
+```
 
 ---
 
-## Links
+## Documentation
 
-- [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)
+| Resource | Description |
+|----------|-------------|
+| [Setup Guide](docs/setup.md) | Installation for all 25+ tools |
+| [Templates](docs/templates.md) | Ready-to-use `.corbat.json` configurations |
+| [Compatibility](docs/compatibility.md) | Full list of supported tools |
+| [Benchmark v2 Analysis](benchmarks/v2/ANALYSIS.md) | 10 scenarios with detailed comparison |
+| [API Reference](docs/full-documentation.md) | Tools, prompts, and configuration |
 
 ---
 
 <div align="center">
 
-**Stop fixing AI-generated code. Start shipping it.**
+**Stop fixing AI code. Start shipping it.**
+
+| Without Corbat | With Corbat |
+|:--------------:|:-----------:|
+| 4.6/10 quality | **7.7/10 quality** |
+| 3 custom errors | **18 custom errors** |
+| 0% hexagonal | **100% hexagonal** |
 
-[Get Started](#quick-start-2-minutes) · [View Benchmarks](docs/comparison-tests/RESULTS-REPORT.md) · [Documentation](docs/full-documentation.md)
+*Recommended by [corbat-tech](https://corbat.tech) — We use Claude Code internally, but Corbat MCP works with any MCP-compatible tool.*
 
 </div>