archrails-mcp 0.6.0

ArchRails MCP — thin local CLI that proxies the cloud handler. The cloud runs the validators; the CLI ships only transport, auth, git-diff capture, and architect-mode YAML editing.

archrails-mcp

The local CLI for ArchRails. Proxies your IDE's MCP-tool calls to the ArchRails cloud and captures the real git diff that drives the architecture review verdict — so the verdict is grounded in what's actually on disk, not what your agent narrates.

Install

pip install archrails-mcp

Requires Python 3.10+ and git on PATH.

Quick start

1. Authenticate. Get an API key from your ArchRails admin, then:

   archrails login
   

2. Configure your IDE's MCP server to launch archrails mcp start. For Cursor, add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-repo):

   {
     "mcpServers": {
       "archrails": {
         "command": "archrails",
         "args": ["mcp", "start", "--repo", "."]
       }
     }
   }
   

   Per-repo config is recommended — --repo "." resolves correctly because the IDE launches the server in the project root.

3. Check from the shell at any time:

   archrails check
   

   Captures your real git diff (including untracked files), sends it to the ArchRails cloud, and prints the verdict.

The v2 BEFORE / CODE / AFTER protocol

The agent gets two tools:

• get_change_context — call before editing. Returns the owning node for the path(s) you're about to change plus its customer-authored connects, controls, and patterns. Advisory only.
• verify_local_change — call after editing. Returns the authoritative pass/fail verdict. The CLI captures your real git diff automatically; the agent does not construct it.

A violation verdict carries a structured remediation verb (delete / revert / replace) and is non-terminal: the agent must remediate, push, and re-attest until the verdict is satisfied. PR-time + branch protection is the un-bypassable backstop.

What the wheel ships

• The stdio MCP server (archrails mcp start) — talks JSON-RPC over stdin/stdout to your IDE, forwards tool calls to the ArchRails cloud, and special-cases verify_local_change to capture the real workspace diff.
• archrails check — the same architecture review, run directly from a terminal.
• archrails attest verify — offline signature verification for ArchRails attestation manifests.

The wheel is pure transport, auth, and git capture — every validator and every architectural decision lives in the ArchRails cloud.

Docs

• API surface and protocol details: see the docs/api/mcp.md spec your admin can point you at.
• Issues / feedback: contact your ArchRails admin.

License

See your ArchRails contract.