React Patterns Server

A comprehensive MCP (Model Context Protocol) server that teaches and applies React architecture, design patterns, and best practices — covering everything from 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

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):

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

Or run directly for testing:

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