# React Patterns MCP Server v2

A comprehensive MCP (Model Context Protocol) server that teaches and applies React architecture, design patterns, and best practices — covering everything from [patterns.dev/react](https://www.patterns.dev/react/).

Built in **TypeScript / Node.js** for use with **Claude Code**.

---

## Features

| Category | Tools |
|----------|-------|
| **Pattern Reference** | All patterns.dev/react patterns with full details, comparisons, recommendations |
| **Code Analyzer** | Detect anti-patterns and suggest refactors in existing React code |
| **Template Engine** | Ready-to-use TypeScript code templates per pattern |
| **Scaffold** | Generate project skeleton based on architecture + patterns |
| **Architecture Doc** | ADR generator that recommends patterns for your project |
| **Live Docs** | Fetch docs.react.dev + React version-aware API guidance |
| **Mobile** | Tailwind responsive patterns + React Native layouts |
| **Memory** | Persist project state between sessions |
| **Task Planner** | Break goals into parallelisable subtasks for Claude subagents |
| **Token Optimizer** | Compress outputs, manage response cache |

---

## Covered Patterns

### 🎨 Design Patterns
| ID | Pattern |
|----|---------|
| `hoc-pattern` | Higher-Order Component (HOC) |
| `hooks-pattern` | Hooks Pattern |
| `compound-pattern` | Compound Pattern |
| `container-presentational-pattern` | Container / Presentational |
| `render-props-pattern` | Render Props |
| `observer-pattern` | Observer / Pub-Sub (Zustand) |
| `provider-pattern` | Provider (React Context) |
| `prototype-pattern` | Prototype / Object Pool |
| `module-pattern` | Module / Feature Slice |
| `singleton-pattern` | Singleton (API clients, stores) |

### ⚙️ Rendering Patterns
| ID | Pattern |
|----|---------|
| `client-side-rendering` | CSR (Vite SPA, dashboards) |
| `server-side-rendering` | SSR (Next.js per-request) |
| `static-rendering` | SSG (Next.js build-time) |
| `incremental-static-rendering` | ISR (stale-while-revalidate) |
| `progressive-hydration` | Progressive Hydration |
| `streaming-ssr` | Streaming SSR |
| `react-server-components` | RSC (Next.js App Router) |
| `selective-hydration` | Selective Hydration (React 18) |

### ⚡ Performance Patterns
| ID | Pattern |
|----|---------|
| `dynamic-import` | Dynamic Import / Code Splitting |
| `import-on-visibility` | Import on Visibility (IntersectionObserver) |
| `import-on-interaction` | Import on Interaction (defer until click/hover) |
| `route-based-splitting` | Route-Based Code Splitting |
| `bundle-splitting` | Bundle Splitting / Vendor Chunking |
| `tree-shaking` | Tree Shaking (dead-code elimination) |
| `preload` | Preload Critical Resources |
| `prefetch` | Prefetch Next-Page Resources |
| `prpl-pattern` | PRPL Pattern (PWA loading strategy) |

---

## Tool Reference

| Tool | Description |
|------|-------------|
| `list_all_patterns` | All patterns grouped by category |
| `list_performance_patterns` | Performance patterns only |
| `get_pattern` | Full detail + code example for a pattern |
| `compare_patterns` | Side-by-side comparison of 2–5 patterns |
| `find_pattern_for_use_case` | Describe a problem, get pattern recommendations |
| `ask_architecture_preference` | **Call this first** — shows architecture options |
| `scaffold_project` | Generate project skeleton |
| `analyze_code` | Detect anti-patterns in React code |
| `get_code_template` | Ready-to-use TypeScript code template |
| `generate_architecture_doc` | ADR — which patterns and why for your project |
| `fetch_react_docs` | Live fetch from docs.react.dev with version guidance |
| `save_memory` / `get_memory` | Persist and recall project context across sessions |
| `create_task_plan` | Break a goal into parallelisable subtasks |
| `compress_output` | Compress verbose responses to save tokens |

---

## Installation

### Prerequisites
- Node.js 20+
- npm or pnpm

### Setup

```bash
git clone https://github.com/1beyza/react-patterns-mcp.git
cd react-patterns-mcp
npm install
npm run build
```

### Add to Claude Code

In your project's `.claude/mcp.json` (or global `~/.claude/mcp.json`):

```json
{
  "mcpServers": {
    "react-patterns": {
      "command": "node",
      "args": ["/absolute/path/to/react-patterns-mcp/dist/index.js"]
    }
  }
}
```

Or run directly for testing:

```bash
npm run dev   # tsx (no build needed)
```

---

## Usage Workflows

### New Project
```
1. create_task_plan     — break the goal into subtasks
2. generate_architecture_doc  — get pattern recommendations + ADR
3. scaffold_project     — generate directory structure + setup commands
4. get_code_template    — get starter code for each essential pattern
5. save_memory          — persist architecture choices
```

### Existing Project Improvement
```
1. analyze_code         — detect issues and pattern opportunities
2. compare_patterns     — compare alternatives
3. suggest_refactor     — get a refactor plan toward a target pattern
4. get_code_template    — get the target pattern's starter code
```

### Quick Pattern Lookup
```
list_all_patterns        — browse everything
get_pattern <id>         — full details + code example
find_pattern_for_use_case — describe your problem, get recommendations
```

---

## Architecture

```
react-patterns-mcp/
├── src/
│   ├── index.ts                    # MCP server entry — registers all tools
│   ├── tools/                      # Tool layer — MCP tool handlers
│   │   ├── index.ts               # Barrel export
│   │   ├── pattern-tools.ts       # Pattern query / compare / recommend
│   │   ├── scaffold-tools.ts      # Project scaffolding
│   │   ├── analyzer-tools.ts      # Code analysis + refactor suggestions
│   │   ├── template-tools.ts      # Code template retrieval
│   │   ├── architecture-tools.ts  # ADR generation
│   │   ├── docs-tools.ts          # Live React docs + version guidance
│   │   ├── mobile-tools.ts        # Mobile / responsive patterns
│   │   ├── memory-tools.ts        # Project state persistence
│   │   ├── task-planner-tools.ts  # Subtask decomposition
│   │   └── token-optimizer-tools.ts # Output compression + cache
│   ├── data/                       # Data layer — pure data, no MCP logic
│   │   ├── patterns.ts            # All design & rendering pattern definitions
│   │   ├── templates.ts           # Code templates per pattern
│   │   └── mobile-patterns.ts     # Mobile responsiveness patterns
│   └── utils/                      # Utility layer — shared functions
│       ├── validator.ts           # Zod schemas for all tool inputs
│       ├── formatter.ts           # Markdown output formatting
│       ├── cache.ts               # TTL response cache
│       └── file-io.ts             # Memory persistence (JSON files)
├── memory/                         # Runtime project memory (gitignored)
├── dist/                           # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md
```

**Layer rules:**
- `data/` — pure data objects, no side effects
- `utils/` — pure functions and shared helpers, no MCP awareness
- `tools/` — MCP tool handlers; validate with Zod, call data/utils, return strings
- `index.ts` — MCP protocol binding only; no business logic

---

## All MCP Tools

| Tool | Description |
|------|-------------|
| `list_all_patterns` | List all patterns with summaries |
| `list_design_patterns` | List design patterns only |
| `list_rendering_patterns` | List rendering patterns only |
| `get_pattern` | Full details + code example for a pattern |
| `compare_patterns` | Side-by-side comparison of 2–5 patterns |
| `find_pattern_for_use_case` | Describe your problem → get recommendations |
| `get_related_patterns` | Patterns related to a given pattern |
| `get_pattern_tradeoffs` | Quick pros/cons for a pattern |
| `scaffold_project` | Generate full project scaffold |
| `analyze_code` | Detect anti-patterns in React code |
| `suggest_refactor` | Refactor plan toward a target pattern |
| `get_code_template` | Get ready TypeScript code for a pattern |
| `list_templates` | List all available code templates |
| `generate_architecture_doc` | ADR with pattern recommendations |
| `fetch_react_docs` | Live docs.react.dev content |
| `get_react_version_guidance` | Version-specific API guidance |
| `get_mobile_pattern` | Mobile/responsive pattern details |
| `get_tailwind_responsive_cheatsheet` | Tailwind responsive design guide |
| `save_memory` | Persist project state to disk |
| `get_memory` | Retrieve saved project state |
| `clear_memory` | Delete project memory |
| `list_project_memory` | List all projects with saved state |
| `create_task_plan` | Break a goal into parallelisable subtasks |
| `compress_output` | Reduce token cost of verbose output |
| `get_cache_stats` | View response cache statistics |
| `clear_caches` | Clear all response caches |