Skip to main content
Glama
Pattern Intelligence MCP

Pattern Intelligence MCP

by mateusdcc

Pattern Intelligence MCP

Deterministic architectural decision engine, TypeScript refactoring synthesizer, and automated fitness governance for AI coding agents.

Most pattern tools are searchable glossaries or static prompts. Pattern Intelligence MCP is a full-fledged local architectural intelligence platform: it diagnoses system forces, penalizes unjustified complexity, recommends direct baselines when appropriate, synthesizes complete production TypeScript scaffolds, and generates automated CI/CD architectural fitness rules.

It is implemented in strict TypeScript with 100% deterministic local execution (zero model API, vector database, or external network dependencies) and speaks the Model Context Protocol through the official SDK.


Why Use Pattern Intelligence MCP?

1. Stopping Context Bloat in Multi-Turn Agents

Prompt-heavy frameworks inject tens of thousands of tokens into context on every turn, causing severe attention dilution and bloating token costs. Pattern Intelligence MCP keeps 116 design patterns, AST analyzers, and force ontologies outside the context window, delivering exact blueprints and TypeScript scaffolds on demand.

2. From Abstract Advice to Executable Code & Governance

Where standard LLMs or prompt skills offer conversational opinions, Pattern Intelligence MCP generates:

  • Executable TypeScript Scaffolds: Ready-to-use domain ports, infrastructure adapters, outbox tables, and saga coordinators.

  • Deterministic AST Smell & Complexity Analysis: Exact Cyclomatic Complexity, Cohesion (LCOM4), Module Instability ($I = \frac{C_e}{C_a + C_e}$), Dual-Write hazard detection, and missing timeout detection.

  • Anti-Cargo-Cult Rejection Matrices: Quantified tipping points (e.g. > 5,000 writes/sec, > 15 engineers) that mathematically justify when complex patterns are warranted versus when to keep direct baselines.

  • Automated CI Architecture Fitness Rules: Auto-generated ESLint boundary constraints (@typescript-eslint/no-restricted-imports) and automated TS-Arch/Vitest test suites to enforce architectural boundaries in CI.


Related MCP server: mitos

Core Capabilities

┌─────────────────────────────────────────────────────────────────────────┐
│                       Pattern Intelligence MCP Engine                   │
├─────────────────────────┬──────────────────────────┬────────────────────┤
│   Decision & Strategy   │  Scaffolding & Smells    │ Governance & Graph │
├─────────────────────────┼──────────────────────────┼────────────────────┤
│ • Force Scoring Engine  │ • AST Code Analyzer      │ • Fitness Rules    │
│ • Rejection Matrices    │ • LCOM4 & Complexity     │ • ESLint Enforcer  │
│ • Quantitative Triggers │ • Dual-Write Detector    │ • Typed Edge Graph │
│ • Compound Topologies   │ • TypeScript Scaffolds   │ • ADR Generator    │
└─────────────────────────┴──────────────────────────┴────────────────────┘

A. Multi-Pattern Compound Topologies

Solves real-world distributed challenges by intelligently assembling multi-pattern topologies:

  • Dual-Write Consistency: Transactional Outbox + Idempotent Receiver + Change Data Capture (CDC Relay).

  • Dependency Resilience: Circuit Breaker + Bulkhead + Bounded Timeout + Retry with Jitter + Fallback Router.

  • Third-Party Isolation: Ports & Adapters (Hexagonal) + Anti-Corruption Layer (ACL) + Strategy Dispatch.

  • Distributed Workflows: Saga Orchestrator + Compensating Transaction Handler + Outbox Step Dispatcher.

  • Safe Monolith Migration: Strangler Fig + Branch by Abstraction + Dark Launching Shadow Taps + Canary Fallback.

B. Deterministic AST Smell & Code Quality Analysis

Parses source code into local AST structures to compute:

  • Cyclomatic & Cognitive Complexity: Branch, loop, and conditional operator counting.

  • Cohesion of Methods (LCOM4): Method-variable connectivity graphs to pinpoint God Classes.

  • Package Coupling & Instability: Afferent ($C_a$) and Efferent ($C_e$) coupling metrics.

  • Dual-Write AST Scanner: Spots database updates followed by network/broker calls within uncommitted scopes.

C. Architectural Fitness Function Generator (generate_architecture_fitness_rules)

Automates architectural governance by exporting:

  • ESLint boundary configurations preventing core domain modules from importing infrastructure, ORMs, or vendor SDKs.

  • Automated Vitest fitness test suites that fail CI builds if unauthorized cross-layer dependencies are introduced.


MCP Tool Surface

Tool

Purpose

Distinguishing Output

prescribe_architecture

Unified one-shot blueprint

Domain ports, infrastructure adapters, rollout seams, and rollback triggers.

refactor_code_smell

AST smell refactoring

AST metrics, before/after complexity delta, and refactored TypeScript code.

generate_architecture_fitness_rules

CI/CD architectural governance

ESLint layer boundary configs, Vitest TS-Arch suites, and CI bash commands.

diagnose_code_quality

Static code metrics

Cyclomatic Complexity, LCOM4 cohesion score, Afferent/Efferent coupling, and Instability.

synthesize_pattern_refactoring

Scaffolding generation

Full multi-file TypeScript implementations with contract verification test suites.

analyze_design_case

Open-ended force diagnosis

Transparent multi-term scores, rejected patterns, direct baselines, and compounds.

compare_pattern_options

2-to-6 option evaluation

Trade-off comparison matrix, non-winner declarations, and force tipping points.

detect_pattern_misuse

Anti-cargo-cult detection

Rejection matrix, premature complexity warnings, and quantitative tipping points.

stress_test_pattern_decision

Sensitivity analysis

Decision flip conditions under shifting scale, throughput, or team capacity.

plan_pattern_adoption

Reversible execution plan

Step-by-step Strangler phases, characterization test nets, and rollback triggers.

write_pattern_adr

Durable decision records

Standard Architecture Decision Record with explicit uncertainty boundaries.

get_pattern_evidence_plan

Falsification planning

Testable hypotheses, measurement metrics, experiment designs, and exit criteria.

query_pattern_graph

Knowledge exploration

Typed graph neighbor traversal (complements, prerequisites, conflicts).

Resources expose the catalog (pattern://catalog), ontology (pattern://ontology), individual pattern records (pattern://pattern/{patternId}), and layers (pattern://layer/{layer}).


The 116-Pattern Knowledge Graph

Track / Layer

Count

Examples

TypeScript-Native

8

Discriminated Union, Result Type, Composition Root, Brand Types

GoF Creational

5

Factory Method, Builder, Singleton, Abstract Factory

GoF Structural

7

Adapter, Bridge, Composite, Decorator, Facade, Proxy

GoF Behavioral

11

Command, State, Strategy, Visitor, Observer, Pipeline

Enterprise & Domain

17

Domain Model, Aggregate, CQRS, Event Sourcing, Repository

Messaging & Integration

18

Router, Aggregator, Idempotent Receiver, Transactional Outbox, CDC

Distributed & Resilience

18

Timeout, Circuit Breaker, Bulkhead, Saga, Sharding, Cells

Concurrency & Async

8

Mutex, Actor, Optimistic Concurrency Control (OCC), Reactor

Testing

8

Characterization Test, Contract Test, Property-Based, Mutation

Architecture

10

Ports & Adapters (Hexagonal), Modular Monolith, Event-Driven

Cloud-Native & AI Agent

6

Model Router, Tool Circuit Breaker, Semantic Cache, Singleflight, Cache Stampede Lock, Token Bucket

Each record contains the problem statement, system context, mechanism, simpler direct alternative, misuse risks, evidence plan, TypeScript-specific concerns, adoption costs, and typed graph relations.


Installation & Quick Start

Requirements: Node.js 22 or newer.

Quick Start via npx (Recommended)

Add directly to your MCP client configuration (e.g. Claude Desktop, Cursor, Pi, Codex):

{
  "mcpServers": {
    "pattern-intelligence": {
      "command": "npx",
      "args": ["-y", "pattern-intelligence-mcp"]
    }
  }
}

Global Install

npm install -g pattern-intelligence-mcp
{
  "mcpServers": {
    "pattern-intelligence": {
      "command": "pattern-intelligence-mcp"
    }
  }
}

From Source (Local Development)

git clone https://github.com/mateusdcc/pattern-intelligence-mcp.git
cd pattern-intelligence-mcp
npm install
npm run check
npm run build
{
  "mcpServers": {
    "pattern-intelligence": {
      "command": "node",
      "args": ["/absolute/path/to/pattern-intelligence-mcp/dist/cli.js"]
    }
  }
}

Clean Code Benchmark Performance

Evaluated against maintainability scenarios adapted from Uncle Bob Clean Architecture principles and ryanmcdermott/clean-code-javascript (85,000+ GitHub Stars):

  • 80% Token Reduction: Slashing total token usage from ~300k tokens down to ~61k tokens per scenario by keeping the 116-pattern knowledge graph and AST smell detectors outside the system prompt and querying only when needed.

  • Anti-Cargo-Cult Resistance: Scored 96.5/100 on resisting premature distributed over-engineering (e.g. rejecting Sagas/CQRS when a single local database transaction suffices).

  • Architectural Decision Soundness: Consistently enforces Single Responsibility (aiming for sub-10 line cohesive functions), Open/Closed polymorphic dispatch, and domain boundary insulation.

  • 100% Deterministic & Local: Sub-millisecond execution with zero reliance on external LLM APIs or vector databases.


Example: One-Shot Architectural Prescription

Input Case

{
  "case": {
    "problem": "Three third-party carrier APIs (FedEx, UPS, DHL) expose incompatible models and leak vendor SDK types across 19 domain files.",
    "failureModes": ["vendor downtime", "breaking SDK updates"],
    "goals": ["insulate domain model", "support dynamic carrier selection"],
    "evidence": ["vendor models imported across 19 core domain files"]
  }
}

Result Produced by prescribe_architecture

  1. Verdict: ADOPT-PATTERN (Ports and Adapters + Anti-Corruption Layer + Strategy).

  2. Rejection Matrix: Disqualifies Microservices and CQRS as premature for in-process boundary insulation.

  3. Generated TypeScript Code:

    • Domain Port contract (CarrierPort).

    • Anti-Corruption Layer vendor mapper functions.

    • Infrastructure adapter (FedExAdapter) with AbortSignal timeout handling.

    • Dynamic carrier strategy registry (CarrierRegistry).

  4. Automated CI Fitness Rule: ESLint configuration disallowing @typescript-eslint/no-restricted-imports from importing vendor SDKs inside src/domain/.

  5. Reversible Adoption Seams: File-by-file Strangler Fig migration steps and quantified rollback triggers.


Development & Testing

npm run typecheck       # Strict TypeScript verification
npm run lint            # Biome check & linting
npm test                # Vitest test suite (100 unit tests)
npm run test:coverage   # Full coverage report (>95% coverage)
npm run build           # Compile to dist/

Architectural Principles

  1. Deterministic Local Execution: Zero dependencies on external AI APIs or vector databases. All reasoning is local, deterministic, and auditable.

  2. No-Pattern Baseline: Adding abstraction layers must mathematically beat a simpler direct solution.

  3. Single Responsibility & Brevity: Strict Uncle Bob Clean Code standards with concise, cohesive functions and clear bounded contexts.

  4. Falsifiable & Reversible: Every architectural prescription includes testable metrics, exit criteria, and zero-friction rollback triggers.


License

MIT License. See LICENSE for details.

Available Tools

8 tools
analyze_design_caseAnalyze a design caseA
Read-onlyIdempotent

Diagnose forces before prescribing a pattern. Returns questions, transparent scores, rejected patterns, a non-pattern baseline, evidence plans, and a bounded pattern compound. Use this first for an open-ended design problem.

Inputs: case (required), maxRecommendations.

compare_pattern_optionsCompare pattern optionsA
Read-onlyIdempotent

Compare two to six named patterns against one concrete case. Returns no winner when evidence is insufficient and states the force that would make each option preferable.

Inputs: case (required), patterns (required).

detect_pattern_misuseDetect pattern misuseA
Read-onlyIdempotent

Audit patterns already used or proposed for cargo-cult risk, missing forces, hidden costs, and simpler alternatives. Use during design or code review, not as a generic pattern search.

Inputs: case (required), patternsInUse (required).

get_pattern_evidence_planGet a pattern evidence planA
Read-onlyIdempotent

Return the hypothesis, measurements, experiment, rejection criteria, and deletion triggers for one pattern in one case. Use when a recommendation needs proof before implementation.

Inputs: case (required), pattern (required).

plan_pattern_adoptionPlan safe pattern adoptionA
Read-onlyIdempotent

Create a reversible, evidence-gated adoption plan for one named pattern. The plan starts with a baseline and smallest production slice and includes exit criteria and rollback.

Inputs: case (required), pattern (required).

query_pattern_graphQuery the pattern graphB
Read-onlyIdempotent

Traverse contextual candidates and explicit pattern relationships with layer and cost filters. Use for bounded discovery around a problem or seed—not to dump the entire catalog.

Inputs: text, limit, layers, seedPatterns, +1 more.

stress_test_pattern_decisionStress-test a pattern decisionA
Read-onlyIdempotent

Apply explicit counterfactual scenarios—scale, delivery, consistency, team, evidence, or goals—and report when the leading decision flips. Use before committing to expensive architecture.

Inputs: case (required), scenarios (required).

write_pattern_adrWrite a pattern ADRA
Read-onlyIdempotent

Generate a proposed architecture decision record from a case. It records considered options, uncertainty, validation metrics, open questions, and reversal triggers rather than pretending the decision is final.

Inputs: case (required), title (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool addresses a distinct phase in the pattern workflow: open-ended analysis, option comparison, misuse auditing, stress testing, adoption planning, ADR writing, evidence planning, and graph discovery. The descriptions make the trigger conditions explicit enough that an agent should rarely confuse one operation with another.

    Naming Consistency5/5

    All tools follow a clear snake_case verb-noun pattern, with the pattern theme appearing consistently across objects. The verbs are distinct and readable: analyze, compare, detect, stress_test, plan, write, get, and query.

    Tool Count5/5

    Eight tools is well within the ideal range for a specialized pattern-intelligence server. Each tool covers a necessary step in the decision lifecycle without redundant operations or bloat.

    Completeness4/5

    The set covers the full pattern decision lifecycle from open-ended analysis through comparison, evidence, adoption, and ADR output, plus review-time misuse detection. A minor gap is the absence of a dedicated catalog/detail lookup tool, though query_pattern_graph mitigates this with bounded discovery.

    Related MCP Connectors

    Related MCP Servers