Metadata-Version: 2.4
Name: archrails-mcp
Version: 0.5.1
Summary: 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.
Author: ArchRails
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Requires-Dist: pyyaml
Requires-Dist: cryptography>=42.0

# archrails-mcp

The local CLI for [ArchRails](https://www.archrails.io). 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

```bash
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:

   ```bash
   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):

   ```json
   {
     "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:

   ```bash
   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`](https://www.archrails.io) spec your admin can point you at.
- Issues / feedback: contact your ArchRails admin.

## License

See your ArchRails contract.
