npm package: @gherk/reactive-architecture
Description: MCP server that teaches AI assistants the reactive architecture philosophy: Component → Store → Service + Controller → Service → Repository
Latest version: 1.9.2

# @gherk/reactive-architecture

An MCP (Model Context Protocol) server that teaches AI coding assistants a **framework-agnostic reactive architecture philosophy** — covering both frontend and backend patterns.

Add this server to any AI assistant (Antigravity, Cursor, Claude Desktop, Copilot, Gemini CLI) and it will **always** structure code following the same proven patterns, regardless of the tech stack.

## Philosophy

### Frontend: Component → Store → Service

```
Component → Store → Service
   (UI)    (State)  (Data Access)
```

- **Component** — Presentation + user interaction only. Reads from store, dispatches actions.
- **Store** — Single source of truth. State management (loading/error/data), business logic.
- **Service** — Pure data access (HTTP, WebSocket, localStorage). Stateless, no logic.

### Backend: Controller → Service → Repository

```
Controller → Service → Repository
  (HTTP)    (Business)  (Data Access)
```

- **Controller** — HTTP adapter. Validates input, calls service, formats response.
- **Service** — Business logic. Orchestrates operations, enforces rules.
- **Repository** — Data access. DB queries, ORM calls, external API clients.

## Installation

### From npm

```bash
npx @gherk/reactive-architecture
```

### From source

```bash
git clone <repo>
cd mcps/reactive-architecture
npm install
npm run build
```

## Configuration

### Antigravity (Gherk Desktop)

Already pre-configured in `agent-go/internal/mcp/mcp-servers.json`. No setup needed — the server is available automatically when Gherk Desktop runs.

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "reactive-architecture": {
      "command": "npx",
      "args": ["-y", "@gherk/reactive-architecture"]
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "reactive-architecture": {
      "command": "npx",
      "args": ["-y", "@gherk/reactive-architecture"]
    }
  }
}
```

### VS Code (Copilot)

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "reactive-architecture": {
      "command": "npx",
      "args": ["-y", "@gherk/reactive-architecture"]
    }
  }
}
```

### Gemini CLI

Add to `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "reactive-architecture": {
      "command": "npx",
      "args": ["-y", "@gherk/reactive-architecture"]
    }
  }
}
```

## Available Tools (10)

### Frontend Architecture

| Tool | Description |
|------|-------------|
| `get_architecture_guide` | Returns the reactive philosophy guide (Component → Store → Service). Supports sections: `overview`, `component`, `store`, `service`, `anti-patterns`, `file-structure`, `implementation-flow`. |
| `detect_and_guide` | Auto-detects the frontend stack from `package.json` content and returns tailored guidance with state library, HTTP pattern, and reactivity model. Supports Angular, React, Vue, Svelte. |
| `generate_scaffold` | Generates a complete feature scaffold (file names + content) for any framework. Supports operations: `list`, `detail`, `create`, `update`, `delete`. |
| `get_framework_example` | Returns concrete, copy-paste-ready examples of the reactive pattern for a specific framework and UI pattern (`list`, `detail`, `form`, `crud`). |
| `get_folder_structure` | Returns the recommended project folder structure. Supports: Angular, React, Next.js, Vue, Nuxt.js, SvelteKit. Includes detection guidance for existing projects. |
| `get_style_rules` | Returns strict coding style rules: formatting (4-space indent, single quotes, 120-char lines), size limits (10 lines/function, 160 lines/file), import ordering, and stack-specific naming conventions. |

### Backend Architecture

| Tool | Description |
|------|-------------|
| `get_backend_guide` | Returns the backend architecture guide (Controller → Service → Repository) with code examples. Supports: Django, Go, NestJS, Spring Boot, FastAPI, Express, Laravel, .NET. |
| `get_backend_folder_structure` | Returns the recommended backend folder structure with module portability. Same 8 stacks as above. |

### Analysis

| Tool | Description |
|------|-------------|
| `validate_architecture` | Validates a described architecture against the reactive patterns. Returns errors, warnings, and suggestions with severity levels. |
| `audit_project` | Parses a project's file tree (from `tree` or `find` command), auto-detects modules, validates each against both frontend and backend patterns, and generates **structured refactoring tickets** with priorities and concrete actions. |

## Available Resources

| URI | Description |
|-----|-------------|
| `reactive://philosophy` | Complete philosophy document as markdown |

## Available Prompts

| Prompt | Description |
|--------|-------------|
| `plan_feature` | Structured template for planning a feature with the Component → Store → Service decomposition |

## Supported Stacks

### Frontend

- **Angular** — Signals + Signal Store, inject-based services
- **React** — Zustand/TanStack Query, custom hooks
- **Vue** — Pinia + Composition API, composables
- **Svelte** — Svelte stores, reactive declarations

### Backend

- **Django** — DRF + Services/Selectors pattern
- **Go** — Handlers → Services → Repositories (interfaces)
- **NestJS** — Decorators, injectable services, TypeORM repos
- **Spring Boot** — `@RestController` → `@Service` → `@Repository`
- **FastAPI** — Routers → Services → Repositories (SQLAlchemy)
- **Express** — Router → Controller → Service → Repository
- **Laravel** — Controllers → Services → Eloquent Repositories
- **.NET** — Controllers → Services → EF Core Repositories

## How It Works

The AI calls the MCP tools to understand how to structure code **before** writing it:

1. **Stack Detection** — `detect_and_guide` auto-detects framework from `package.json`
2. **Architecture Guide** — `get_architecture_guide` / `get_backend_guide` provides the philosophy
3. **Folder Structure** — `get_folder_structure` / `get_backend_folder_structure` defines where files go
4. **Style Rules** — `get_style_rules` enforces formatting and size constraints
5. **Scaffolding** — `generate_scaffold` creates the feature boilerplate
6. **Validation** — `validate_architecture` / `audit_project` checks compliance

## Development

```bash
npm run dev    # Watch mode (recompiles on changes)
npm run build  # Production build
npm start      # Run the server directly
```

## License

MIT