# Arch-Master MCP

> Multi-stack scaffolding engine exposed as a **Model Context Protocol (MCP)** server.  
> Generates production-ready module structures for NestJS, Java Spring, and Python FastAPI — directly from any MCP-compatible AI client.

> **Zero-token boilerplate.** Designed for projects that are just getting started — instead of asking the AI to write every file (which burns thousands of tokens), the AI simply calls a tool and the entire module structure is generated locally on your machine in milliseconds.

---

## What it does

Arch-Master MCP exposes **two tools** over stdio:

| Tool | Description |
|---|---|
| `scaffold_module` | Generates all architecture files for a named module in the chosen stack/pattern |
| `list_patterns` | Returns a markdown table of every supported stack and its available patterns |

No files are uploaded to the AI. All generation runs **locally** — only the file list is returned to the client.

### Why this matters for new projects

When starting a project from scratch, the AI would normally write every file from scratch — entity, repository, service, controller, module, interfaces, mappers — burning thousands of output tokens per module. Arch-Master flips this: the AI decides *what* to generate, the MCP generates *how*.

| Approach | Tokens per module (approx.) |
|---|---|
| AI writes each file manually | ~2 000 – 5 000 tokens |
| `scaffold_module` via Arch-Master | ~50 – 100 tokens |

---

##  Supported stacks & patterns

| Stack | Patterns | Base path |
|---|---|---|
| `nestjs` | `hexagonal`, `layers`, `clean` | `src/modules` |
| `java_spring` | `hexagonal`, `layers`, `clean` | `src/main/java/com/company/modules` |
| `python_fastapi` | `hexagonal`, `layers`, `clean` | `src/modules` |

---

## Quick start

### 1. Install dependencies

```bash
pnpm install
```

### 2. Build

```bash
pnpm build
# output → dist/
```

### 3. Register in your MCP client (e.g. Claude Desktop)

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

---

## Development

```bash
pnpm test          # unit tests (Jest)
pnpm test:cov      # coverage report
pnpm build         # compile TypeScript → dist/
```

### Project structure

```
src/
├── index.ts                  # MCP server entry point (tool registration)
├── core/
│   ├── generator.ts          # File creation engine
│   └── template-engine.ts    # {{Variable}} template renderer
├── handlers/
│   └── scaffold.handler.ts   # Tool request handlers
├── strategies/
│   ├── index.ts              # Strategy registry (single source of truth)
│   ├── hexagonal/            # Hexagonal pattern templates per stack
│   ├── layers/               # Layered pattern templates per stack
│   └── clean/                # Clean architecture templates per stack
├── types/
│   └── mcp-types.ts          # Shared TypeScript interfaces
└── utils/
    └── file-system.ts        # fs helpers
```

---

##  Extending

- **New stack:** add an entry in `src/strategies/index.ts` and its pattern files under `src/strategies/<pattern>/`.
- **New pattern for an existing stack:** add a pattern file and wire it in `src/strategies/index.ts`.
- The `src/index.ts` entry point is **generic** — it never needs to change.

---

##  Technical stack

- **Runtime:** Node.js 20+ / TypeScript (ESM, `NodeNext` module resolution)
- **MCP SDK:** `@modelcontextprotocol/sdk`
- **Validation:** Zod
- **Build:** NestJS CLI → `dist/`
- **Package manager:** pnpm