@godrix/architecture-contract-mcp

Architecture Contract MCP (ARC) — agnostic MCP server that reads arc.yaml from the workspace and exposes tools to map layers, trace slices, generate scaffolding, and validate architectural rules.

• MCP server name: @godrix/architecture-contract-mcp
• Binary: architecture-contract-mcp
• Tool prefix: arc_* (unchanged)
• Node: 20+

Quick install (npx)

No clone or local build required — the published npm package includes compiled JavaScript.

Cursor / Claude Desktop (mcp.json)

{
  "mcpServers": {
    "architecture-contract": {
      "command": "npx",
      "args": ["-y", "@godrix/architecture-contract-mcp"],
      "env": {}
    }
  }
}

Restart your MCP client after saving. Or use the Install MCP Server button above.

Global install (alternative)

npm install -g @godrix/architecture-contract-mcp

Then use "command": "architecture-contract-mcp" in mcp.json.

Local development

git clone https://github.com/godrix/mcp-architecture-contract.git
cd mcp-architecture-contract
npm install
npm run build

{
  "mcpServers": {
    "architecture-contract": {
      "command": "node",
      "args": ["/absolute/path/mcp-architecture-contract/dist/index.js"],
      "env": {}
    }
  }
}

CLI (CI/local)

# Validate manifest + rules (+ validators if configured)
node dist/index.js validate --workspace /path/to/project
node dist/index.js validate --workspace /path/to/project --run-validators

# Scaffold dry-run (default) or write
node dist/index.js scaffold --kind rest_endpoint --name Foo --workspace /path/to/project
node dist/index.js scaffold --kind rest_endpoint --name Foo --workspace /path/to/project --write

Or via bin:

architecture-contract-mcp validate --workspace /path/to/project
architecture-contract-mcp scaffold --kind rest_endpoint --name Foo --write

Exit code 1 when there are error violations or a validator fails.

Local plugins

Custom architectures live under .arc/plugins/{id}/:

my-project/
  arc.yaml
  .arc/plugins/my-arch/
    manifest.yaml
    templates/
      UseCase.java.hbs

# arc.yaml (thin — default from arc_init)
schemaVersion: "1"
extends: ./.arc/plugins/my-arch/manifest.yaml

project:
  name: my-service
  language: java
  rootPackage: com.example.myapp

extends accepts:

• Built-in preset: hexagonal-java@1
• Local file: ./.arc/plugins/my-arch/manifest.yaml

Template priority: .arc/templates/ (project) → plugin/templates/ → built-in preset.

Create an editable plugin from a preset:

{
  "tool": "arc_init_plugin",
  "arguments": {
    "pluginId": "my-arch",
    "preset": "hexagonal-java@1",
    "workspaceRoot": "/path/to/project"
  }
}

MCP tools

| Tool | Description | |------|-------------| | arc_load | Effective manifest + extendsRef, pluginRoots, kindSummaries | | arc_get_rules | Rules, layers, docs and examples per layer | | arc_resolve | Files to create (includePreview optional) | | arc_find | Search with score; role/suffix filters | | arc_trace | Slice or inferred chain (find + imports) | | arc_scaffold | Generate Handlebars files (dryRun default true) | | arc_diff_scaffold | Expected diff vs disk | | arc_validate | Rules + mayDependOn/mustNotDependOn + CLI validators | | arc_validate_manifest | Validate arc.yaml and plugins against schema | | arc_init | Create thin arc.yaml (default) or mode: full | | arc_init_plugin | Create .arc/plugins/{id}/ from preset | | arc_list_presets | List built-in presets | | arc_list_plugins | List local plugins | | arc_describe_kind | Steps/templates for a kind | | arc_explain_layer | Layer + rules + repo examples | | arc_register_slice | Register slice in arc.yaml | | arc_graph | Mermaid graph of layers + violations | | arc_suggest_location | Expected path for role + name |

MCP resources

• arc://guide — full guide (SKILL + README)
• arc://manifest/effective — merged manifest (JSON)
• arc://rules — layers + rules
• arc://plugins — plugins in .arc/plugins/
• arc://plugin/{id} — manifest and templates for a plugin

Prompts

• arc-scaffold-workflow — load → resolve → confirm → scaffold
• arc-init-plugin — create plugin in .arc/plugins/{id}/
• arc-validate-workflow — validate manifest and compliance

Recommended workflow

1. arc_init or arc_init_plugin + local extends
2. arc_load → profile, kinds, pluginRoots
3. arc_resolve (or arc_diff_scaffold) with kind + name
4. Confirm with the user
5. arc_scaffold with dryRun: false
6. arc_validate after changes

Built-in presets

• hexagonal-java@1 — Spring hexagonal (port.in/out, adapters, domain)
• mvc-typescript@1 — controllers, services, api
• fsd-react@1 — Feature-Sliced Design (app, pages, widgets, features, entities, shared)

arc.yaml schema (v1)

arc_init writes to the project:

• .arc/arc-manifest.schema.json — manifest JSON Schema
• .arc/schema.json — alias ($ref) for lint tools
• thin arc.yaml with extends (or full with mode: full)

# yaml-language-server: $schema=./.arc/arc-manifest.schema.json

schemaVersion: "1"
parent: optional/path/to/parent/arc.yaml
extends: preset-id@version | ./.arc/plugins/id/manifest.yaml

project:
  name: string
  language: java | typescript | kotlin | other
  rootPackage: optional
  sourceRoot: "."

profile: hexagonal | mvc | fsd | custom

layers:
  - id: string
    path: glob
    suffix: optional
    mayDependOn: [layerIds]
    mustNotDependOn: [layerIds]

kinds:
  <kindId>:
    variables: { key: description }
    steps:
      - manual: string
      - generate: { layer, template, namingKey? }

rules:
  - id: string
    when: { layer: string | string[] }
    forbidImports: [glob/substring]
    requireSuffix: string
    severity: error | warn
    message: string

Tests

npm test

MCP Inspector

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

Migration from arc-mcp

| Before | After | |--------|-------| | npm package arc-mcp | @godrix/architecture-contract-mcp | | Folder arc-mcp | mcp-architecture-contract | | bin arc-mcp | architecture-contract-mcp | | MCP server name arc | @godrix/architecture-contract-mcp | | Tool names arc_* | unchanged |

License

MIT