Archrad Deterministic Mcp

by archradhq

336 downloads

Not rated

GitHub

About

stdio MCP server from @archrad/deterministic—same engine as the archrad CLI. Validates architecture IR (structural + IR-LINT), merges local PolicyPack YAML, checks export drift vs generated files on disk, and returns static archrad_suggest_fix guidance per built-in rule code. No

Details

Author: archradhq
Downloads: 336
Categories: Developer Tools, Infrastructure, API

- Deterministic IR validation without LLM involvement
- Built-in IR-LINT rules for common architecture issues
- Drift detection between IR and on-disk export directories
- Optional PolicyPack support for custom governance rules
- Stateless per-call design; policies must be passed on each invocation
- Curated, static fix suggestions for individual rule codes

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Archrad Deterministic Mcp

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "archrad deterministic mcp": {
            "archrad": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@archrad/deterministic",
                    "archrad-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "archrad deterministic mcp": {
            "archrad": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@archrad/deterministic",
                    "archrad-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "archrad deterministic mcp": {
            "archrad": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@archrad/deterministic",
                    "archrad-mcp"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "archrad deterministic mcp": {
            "archrad": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@archrad/deterministic",
                    "archrad-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "archrad deterministic mcp": {
            "archrad": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@archrad/deterministic",
                    "archrad-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "archrad deterministic mcp": {
            "archrad": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@archrad/deterministic",
                    "archrad-mcp"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "archrad deterministic mcp": {
            "archrad": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@archrad/deterministic",
                    "archrad-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "archrad deterministic mcp": {
            "archrad": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@archrad/deterministic",
                    "archrad-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "archrad deterministic mcp": {
            "archrad": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@archrad/deterministic",
                    "archrad-mcp"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "archrad deterministic mcp": {
            "archrad": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@archrad/deterministic",
                    "archrad-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "archrad deterministic mcp": {
            "archrad": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@archrad/deterministic",
                    "archrad-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "archrad deterministic mcp": {
            "archrad": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@archrad/deterministic",
                    "archrad-mcp"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "archrad deterministic mcp": {
            "archrad": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@archrad/deterministic",
                    "archrad-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "archrad deterministic mcp": {
            "archrad": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@archrad/deterministic",
                    "archrad-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "archrad deterministic mcp": {
            "archrad": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@archrad/deterministic",
                    "archrad-mcp"
                ]
            }
        }
    }
}

From the repository

Install globally with npm install -g @archrad/deterministic; the binary archrad-mcp ships with the package. Alternatively, use npx without a global install by adding the server configuration to your MCP host (e.g., Claude Desktop's claude_desktop_config.json). The server exposes six MCP tools: archrad_validate_ir, archrad_lint_summary, archrad_validate_drift, archrad_policy_packs_load, archrad_suggest_fix, and archrad_list_rule_codes.

`archrad_validate_ir`

Architecture-as-code validation: run this when you need to check whether an IR graph is valid or to list violations before export or drift checks. Keywords: validate IR, architecture lint, IR-STRUCT, IR-LINT, policy pack, blueprint graph, nodes and edges. Runs in one call: 1) Structural validation — graph shape, references, IR-STRUCT-* errors. 2) Architecture lint — design rules (auth, dead nodes, DB access, sync chains, etc.). 3) Optional PolicyPack rules — pass policiesDirectory to load YAML/JSON packs from disk. Returns irStructuralFindings, irLintFindings, and combined (sorted by severity). ok is false when any finding has severity "error". After results: call archrad_suggest_fix with a finding code for remediation text; use archrad_lint_summary for a short human-readable digest. Input: provide exactly one of ir (inline JSON object) or irPath (path to .json). Large graphs: prefer irPath.

`archrad_lint_summary`

Human-readable summary of validation results: error/warning counts and up to 20 top findings (plain text). Keywords: summary, PR comment, explain violations, readable lint output. Use when you need a short narrative or comment, not structured JSON. For machine-actionable findings, use archrad_validate_ir instead. Same inputs as archrad_validate_ir: ir or irPath, optional policiesDirectory. Provide only one of ir or irPath.

`archrad_suggest_fix`

Look up curated remediation steps and documentation URL for one built-in rule code (e.g. IR-LINT-MISSING-AUTH-010, IR-STRUCT-*, DRIFT-*). Keywords: remediation, how to fix, rule code, docs link, IR-LINT, IR-STRUCT. Does not return generated code patches or IR edits — only static guidance. PolicyPack and org-specific rule ids are not covered; see your YAML packs. Call archrad_list_rule_codes to list codes that have static guidance.

`archrad_list_rule_codes`

Returns the sorted list of built-in IR-STRUCT-*, IR-LINT-*, and DRIFT-* codes that archrad_suggest_fix can explain. Keywords: catalog, all rules, rule list, documentation index. Use before suggest_fix to confirm a code exists. Excludes PolicyPack custom ids. No arguments.

`archrad_validate_drift`

Compare the architecture IR to generated code under exportDir and report drift (files that no longer match deterministic export). Keywords: drift, CI, codegen diff, FastAPI, Express, Node, Python, validate export, architecture vs implementation. Requires: ir or irPath, exportDir (absolute path to the export tree), and target. target must be "python" or "nodejs" (use "nodejs" for Node/TypeScript; do not use "node"). Optional: policiesDirectory, skipIrLint (true to skip IR-LINT and only check drift). Returns driftFindings plus IR structural and lint findings from the same engine as CLI validate-drift.

`archrad_policy_packs_load`

Validate PolicyPack YAML/JSON without running against a graph: syntax, rule ids, and compilation. Keywords: policy pack, YAML rules, validate policies, org rules, offline check. You usually do not need this before archrad_validate_ir or archrad_validate_drift — those accept policiesDirectory and load packs internally. Use this tool to debug pack files in isolation. Provide either directory (folder path) or files (array of { name, content }), not both.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "archrad deterministic mcp": {
            "archrad": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@archrad/deterministic",
                    "archrad-mcp"
                ]
            }
        }
    }
}

McpServers

{
    "archrad": {
        "command": "npx",
        "args": [
            "-y",
            "--package=@archrad/deterministic",
            "archrad-mcp"
        ]
    }
}

ArchRad MCP Server — user guide

Audience: Registry listings (e.g. mcp.so), README deep-links, and operators who want a single accurate overview. For transport details, IR size limits, and testing recipes, see MCP.md.

What is ArchRad MCP Server?

ArchRad MCP Server gives AI coding agents (Claude Desktop, Cursor, and other MCP-capable hosts) deterministic architecture governance. When your agent designs or edits a system graph, ArchRad validates the IR (intermediate representation) against structural rules and IR-LINT — before anything is committed. No LLM in the validation loop. Same engine as the archrad CLI. Apache-2.0.

Installation

bash
npm install -g @archrad/deterministic



The MCP server binary

archrad-mcp ships with this package (package.json → bin

).

Alternative (no global install): many hosts accept

npx

json
{
  "mcpServers": {
    "archrad": {
      "command": "npx",
      "args": ["-y", "--package=@archrad/deterministic", "archrad-mcp"]
    }
  }
}



On Windows, if the command is not on

PATH, use the full path to node and to dist/mcp-server.js from a local clone after npm run build — see MCP.md

 §5.3.

Claude Desktop configuration

json
{
  "mcpServers": {
    "archrad": {
      "command": "archrad-mcp",
      "args": []
    }
  }
}



MCP tools


| Tool | Purpose |
|------|---------|
|

archrad_validate_ir | Validate IR JSON against structural rules and built-in IR-LINT, with optional PolicyPack from policiesDirectory. Returns irStructuralFindings, irLintFindings, and a sorted combined list. Curated remediation text for a code is a separate call to archrad_suggest_fix

. |
|

archrad_lint_summary | Short summary and counts of findings (same inputs as validate: ir / irPath, optional policiesDirectory

). |
|

archrad_validate_drift | Compare IR to an on-disk export directory (exportDir) for a given target: python or nodejs only. Surfaces drift-class findings such as DRIFT-MISSING, DRIFT-MODIFIED, DRIFT-EXTRA, and DRIFT-NO-EXPORT, plus lint/structural output from the same pipeline when enabled. Optional policiesDirectory, optional skipIrLint

. |
|

archrad_policy_packs_load | Compile / smoke-check PolicyPack YAML or JSON from a directory or in-memory files list. Returns { ok, ruleCount }

 or errors. Does not register packs for later tools — the process is stateless. To lint with a pack, pass the same path as

policiesDirectory on archrad_validate_ir, archrad_lint_summary, or archrad_validate_drift

. |
|

archrad_suggest_fix | Static, curated guidance for a built-in rule id (e.g. IR-LINT-MISSING-AUTH-010

). Not LLM output; not automatic graph patches. |
|

archrad_list_rule_codes | Returns { codes: string[] } — sorted built-in codes that have static guidance in OSS. For descriptions, severity, and compliance language, use archrad_suggest_fix per code or RULE_CODES.md

. |

Explicit non-goals for OSS MCP are summarized in

MCP.md

 §6–§7.

CLI capabilities (not MCP)


These run in the terminal, not as MCP tools — use them to produce IR before calling

archrad_validate_ir

:

-

archrad ingest openapi --spec <url-or-file>

 — OpenAPI 3.x → IR  
-

archrad init --from docker-compose.yml

 — docker-compose → IR  
-

archrad ingest backstage --catalog <dir>

 — Backstage catalog → IR  

Full flags:

CLI_REFERENCE.md

.

Example IR-LINT rules


Sample of built-in codes (canonical catalog:

RULE_CODES.md

):

| Rule | Description |
|------|-------------|
| IR-LINT-DIRECT-DB-001 | Service calls database directly, bypassing service layer |
| IR-LINT-DIRECT-DB-ACCESS-002 | HTTP-facing service has direct edge to database |
| IR-LINT-MISSING-AUTH-010 | HTTP entry point has no auth boundary |
| IR-LINT-DEAD-NODE-011 | Node with no inbound or outbound edges |
| IR-LINT-MULTIPLE-HTTP-ENTRIES-009 | Multiple HTTP entry points with no gateway |
| IR-LINT-NO-HEALTHCHECK-003 | No health or readiness endpoint defined |

Real-world example (Swagger Petstore)


The repo includes a script that clones public YAML via the GitHub tree API, classifies OpenAPI vs blueprint, and validates. Run from the

@archrad/deterministic package root

 after a build:

bash
cd packages/deterministic   # adjust if your clone layout differs
npm run build
node scripts/github-validate-samples.mjs --repo swagger-api/swagger-petstore --max 5



Findings vary by spec revision; treat output as an illustrative run, not a fixed marketing scorecard.

Enterprise — remote MCP with org policies


For teams using ArchRad Cloud,

@archrad/remote-mcp

 is an HTTP MCP gateway that fetches org PolicyPack context from the API using a per-user or per-org bearer token, so agents do not need local policy files. Deployment (e.g. Cloud Run), token issuance, and what is retained for compliance evidence are product-specific — see

packages/archrad-remote-mcp/README.md

 in this monorepo and your ArchRad Cloud documentation. Do not promise a specific audit trail in OSS copy without matching product/legal language.

Links


- npm: @archrad/deterministic  
- GitHub: arch-deterministic  
- Platform: archrad.com  
- License: Apache-2.0  
- Spec + testing:

MCP.md`

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

archrad_validate_ir

archrad_lint_summary

archrad_suggest_fix

archrad_list_rule_codes

archrad_validate_drift

archrad_policy_packs_load

Claude Desktop / Cursor

McpServers

ArchRad MCP Server — user guide

What is ArchRad MCP Server?

Installation

Claude Desktop configuration

MCP tools

CLI capabilities (not MCP)

Example IR-LINT rules

Real-world example (Swagger Petstore)

Enterprise — remote MCP with org policies

Links

Install

More like this

Sentry

Github

Git

GitLab

Context 7

Playwright

`archrad_validate_ir`

`archrad_lint_summary`

`archrad_suggest_fix`

`archrad_list_rule_codes`

`archrad_validate_drift`

`archrad_policy_packs_load`