**English** | [한국어](README.ko.md)

# Architecture Drift MCP

[![CI](https://github.com/efficjump/architecture-drift-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/efficjump/architecture-drift-mcp/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-2ea44f.svg)](LICENSE)

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.

```mermaid
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

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

For source development:

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

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

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

```bash
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](docs/architecture.md), [security policy](SECURITY.md), and
[contribution guide](CONTRIBUTING.md).

## License

[MIT](LICENSE)