@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

npx @gherk/reactive-architecture

From source

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:

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

Cursor

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

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

VS Code (Copilot)

Add to .vscode/mcp.json:

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

Gemini CLI

Add to ~/.gemini/settings.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

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

License

MIT