mcp-architecture

Architecture Rules — mcp/

This project follows DDD (Domain-Driven Design) + Hexagonal Architecture (Ports & Adapters) with manual constructor injection. The structure mirrors the api repo, adapted for TypeScript.

Layers

src/
├── domain/          # Inner core — depends on nothing outward
│   ├── value-objects/
│   ├── ports/       # interfaces (1 file = 1 port)
│   └── services/    # pure decision policies (no I/O)
├── application/     # use cases
│   ├── tools/       # MCP tool definitions (1 file = 1 tool)
│   └── tool-registry.ts
├── infrastructure/  # adapters implementing ports
│   ├── api/
│   ├── logging/
│   ├── session/
│   ├── rate-limit/
│   ├── clock/
│   └── error-reporting/
├── presentation/    # transports — composition roots
│   ├── stdio/
│   └── http/
├── shared/          # generic utilities (Result, config schema)
└── bin.ts           # CLI entry; dispatches to a bootstrap

Dependency direction (enforced by dependency-cruiser)

presentation ──→ application ──→ domain
                                ↑
infrastructure ─────────────────┘   (implements ports)

shared ←── used by anyone, depends on nothing

Concretely:

• domain/ imports from nowhere outward. Defines ports; doesn't know what implements them.
• application/ imports from domain/ only. Tools depend on ApiGateway, Logger, Clock, etc. — never on concrete classes.
• infrastructure/ implements domain/ports/*. Wires fetch/pino/etc. to satisfy a port. Stays out of application/.
• presentation/ wires everything together. The *-bootstrap.ts files are the only place new HttpApiGateway(...) exists.
• shared/ is generic utilities (Result, env-schema). No domain types live here.

ESLint enforces this with no-restricted-imports patterns. dependency-cruiser enforces it again with mcp/.dependency-cruiser.cjs. Two locks beats one.

Ports & Adapters

Every external interaction (HTTP, logging, time, randomness) goes through a port: