Arch-Master MCP

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

pnpm install

2. Build

pnpm build
# output → dist/

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

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

---

Development

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