Deterministic MCP server

@archrad/deterministic

Your architecture drifts before you write a single line of code. archrad validate catches it — deterministically, in CI, before the PR merges.

Define your system as a graph. ArchRAD compiles it, lints it against architecture rules, and tells you exactly what's wrong — with rule codes, not opinions.

New in 0.7.x — archrad demo runs a full example with zero setup, and archrad scan

drafts an IR from any repo with every node cited to file:line. Lint findings only

decrease in this release; nothing that passed on 0.6.x can start failing.

See the changelog.

Quick start (60 seconds)

npm install -g @archrad/deterministic
archrad demo

No IR file, no flags, no config — runs from any directory. Lints a bundled example and shows you the findings:

orders-api (http)  ──▶  orders-db (postgres)

⚠️ IR-LINT-DIRECT-DB-ACCESS-002: API node "orders-api" connects directly to datastore node "orders-db"
   Fix: Introduce a service or domain layer between HTTP handlers and persistence.
⚠️ IR-LINT-MISSING-AUTH-010: HTTP entry node "orders-api" has no auth node or auth config …
⚠️ IR-LINT-NO-HEALTHCHECK-003: No HTTP node exposes a typical health/readiness path …

Then run it on your own repo

archrad scan . --out draft.ir.json    # draft an IR — every node cited to file:line
archrad validate --ir draft.ir.json   # lint it

scan reads your Docker Compose, Kubernetes manifests, Terraform, OpenAPI, package manifests, and source code, then grades every node by confidence so you can see what was parsed versus guessed. The output is a normal IR file — review it, edit it, commit it.

Already have an OpenAPI spec or a Backstage catalog? Skip the scan:

archrad ingest openapi --spec ./openapi.yaml --out ./graph.json
archrad ingest backstage --catalog . --out ./graph.json

Once a graph is committed, archrad validate is your CI gate — exit 1 blocks the merge.

What it does

ArchRAD is a blueprint compiler and governance layer. You define your architecture as an IR — nodes, edges, allowed connections — and ArchRAD validates it against a deterministic rule engine. The same IR, the same rules, the same inputs always produce the same findings.

Shortened. The full README is on GitHub.