Architecture Drift MCP

Compare evidence-linked documentation claims with facts observed in the current source tree. The server keeps extraction, deterministic comparison, model adjudication, and patch proposals separate so an uncited guess cannot become confirmed architecture drift.

flowchart LR
    A[Discover bounded sources] --> B[Cited documentation claims]
    A --> C[Cited implementation facts]
    B --> D[Deterministic comparison]
    C --> D
    D --> E{Evidence strength}
    E --> F[Aligned]
    E --> G[Suspected or unknown]
    E --> H[Evidence-bound adjudication]
    H --> I[Review-only patch proposal]

Highlights

• Bounded inventory of documentation, manifests, configuration, specifications, and source files
• Deterministic command, environment, endpoint, dependency, and service extraction
• Host-model claim extraction with exact path and line-range validation
• Fresh source hashes that reject mixed old/new citations
• Exact semantic alignment plus conservative suspected and unknown states
• Confirmed model adjudication restricted to known claim and fact IDs
• Review-only documentation replacements that never write into the audited project
• Redacted Markdown and JSON reports outside the project tree

Install

uv tool install "git+https://github.com/efficjump/architecture-drift-mcp.git"
architecture-drift-mcp --transport stdio

For source development:

git clone https://github.com/efficjump/architecture-drift-mcp.git
cd architecture-drift-mcp
uv sync --all-extras --locked
uv run architecture-drift-mcp --transport stdio

Generic MCP client configuration

{
  "mcpServers": {
    "architecture-drift": {
      "command": "architecture-drift-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

The installed command keeps local checkout paths out of client configuration.

Tool workflow

Stage	Tools
Audit state	create_audit, list_audits, get_audit
Discovery	discover_sources
Evidence	extract_claims, extract_facts
Decision	compare_drift, adjudicate_drift
Output	propose_doc_patches, build_drift_report

Deterministic absence never becomes confirmed drift. A confirmed adjudication requires known implementation fact IDs, while unsupported extractor coverage remains unknown.

Safety model

• Project roots must remain inside ARCH_DRIFT_ALLOWED_ROOTS.
• Symlinks, binary files, and over-limit sources are excluded from extraction.
• Sources are hash-checked again before citation or fact extraction.
• Sampled content is redacted and every returned citation is validated against source lines.
• Patch proposals are persisted externally and never applied by this server.

The path boundary is not an operating-system sandbox. Audit untrusted projects in isolation.

Streamable HTTP

architecture-drift-mcp --transport streamable-http --host 127.0.0.1 --port 8768

The default endpoint is http://127.0.0.1:8768/mcp.

Development

uv sync --all-extras --locked
uv run ruff format --check .
uv run ruff check .
uv run mypy src
uv run pytest --cov --cov-report=term-missing
uv build

See architecture, security policy, and contribution guide.

License

MIT