Skip to main content
Glama
godrix

architecture-contract

by godrix
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

@godrix/architecture-contract-mcp

Install MCP Server

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.

Related MCP server: boilerforge

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers