# balanov/mcp-attest architecture

> Architecture diagram of the GitHub repository balanov/mcp-attest, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/balanov/mcp-attest
- Repository: https://github.com/balanov/mcp-attest

## Overview

mcp-attest is a policy-as-code conformance and attestation harness for live MCP servers. The main workflow starts at the CLI: load a policy and target, run identity-specific real calls, compare observed behavior with expected decisions, then report findings and evidence. Separate capabilities cover OAuth probes, portable suites, offline trace checks and shadow-path detection, posture assessment, and OTLP trace export. Relationships below use README statements and the source index/import references; unsampled implementation details are not inferred.

Main entry points: [`src/mcp_attest/cli.py`](https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/cli.py) (CLI), [`src/mcp_attest/conformance.py`](https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/conformance.py) (Conformance runner), [`src/mcp_attest/checks.py`](https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/checks.py) (Trace checks), [`src/mcp_attest/policy.py`](https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/policy.py) (Policy model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Test workflow"]
  node_cli["CLI<br/>[cli.py]"]
  node_policy["Policy model<br/>[policy.py]"]
  node_targets["Target config<br/>[targets.py]"]
  node_runner["Conformance runner<br/>[conformance.py]"]
end

subgraph group_protocol["MCP and OAuth"]
  node_client["MCP client<br/>[client.py]"]
  node_jsonrpc["JSON-RPC<br/>[jsonrpc.py]"]
  node_oauth["OAuth probes<br/>[oauth.py]"]
end

subgraph group_analysis["Trace analysis"]
  node_checks["Trace checks<br/>[checks.py]"]
  node_trace["Trace model<br/>[trace.py]"]
  node_shadow["Shadow paths<br/>[shadow.py]"]
  node_posture["Posture assessment<br/>[posture.py]"]
  node_otlp["OTLP export<br/>[otlp.py]"]
end

subgraph group_assurance["Evidence and rules"]
  node_rules["Rule catalog<br/>[rules.py]"]
  node_evidence["Evidence bundles<br/>[evidence.py]"]
  node_receipts["Call receipts<br/>[receipts.py]"]
  node_report["Findings report<br/>[report.py]"]
end

subgraph group_extensions["Suites and posture"]
  node_suite["Conformance suites<br/>[suite.py]"]
end

node_engineer(("Harness user"))
node_server(("MCP server"))

node_engineer -->|"runs commands"| node_cli
node_cli -->|"loads policy"| node_policy
node_cli -->|"parses target"| node_targets
node_cli -->|"starts tests"| node_runner
node_runner -->|"sends calls"| node_client
node_client -->|"encodes messages"| node_jsonrpc
node_client -->|"connects to"| node_server
node_runner -->|"compares decisions"| node_policy
node_runner -->|"runs probes"| node_oauth
node_cli -->|"runs checks"| node_checks
node_checks -->|"inspects events"| node_trace
node_checks -->|"checks policy"| node_policy
node_checks -->|"uses rule IDs"| node_rules
node_cli -->|"loads traces"| node_trace
node_cli -->|"finds bypasses"| node_shadow
node_shadow -->|"reads routes"| node_trace
node_cli -->|"assesses posture"| node_posture
node_cli -->|"exports traces"| node_otlp
node_otlp -->|"uses trace data"| node_trace
node_cli -->|"runs suites"| node_suite
node_suite -->|"creates policy"| node_policy
node_cli -->|"builds bundles"| node_evidence
node_evidence -->|"uses receipts"| node_receipts
node_cli -->|"formats findings"| node_report
node_report -->|"renders results"| node_checks
node_report -->|"renders results"| node_runner

click node_cli "https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/cli.py"
click node_policy "https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/policy.py"
click node_targets "https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/targets.py"
click node_runner "https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/conformance.py"
click node_checks "https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/checks.py"
click node_trace "https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/trace.py"
click node_shadow "https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/shadow.py"
click node_posture "https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/posture.py"
click node_otlp "https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/otlp.py"
click node_client "https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/client.py"
click node_jsonrpc "https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/jsonrpc.py"
click node_oauth "https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/oauth.py"
click node_rules "https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/rules.py"
click node_evidence "https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/evidence.py"
click node_receipts "https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/receipts.py"
click node_report "https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/report.py"
click node_suite "https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/suite.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_policy,node_targets,node_runner,node_engineer toneBlue
class node_client,node_jsonrpc,node_oauth toneAmber
class node_checks,node_trace,node_shadow,node_posture,node_otlp,node_server toneMint
class node_rules,node_evidence,node_receipts,node_report toneRose
class node_suite toneIndigo
```

## Components

### Test workflow

- [CLI](https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/cli.py): `src/mcp_attest/cli.py`
- [Policy model](https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/policy.py): `src/mcp_attest/policy.py`
- [Target config](https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/targets.py): `src/mcp_attest/targets.py`
- [Conformance runner](https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/conformance.py): `src/mcp_attest/conformance.py`

### MCP and OAuth

- [MCP client](https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/client.py): `src/mcp_attest/client.py`
- [JSON-RPC](https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/jsonrpc.py): `src/mcp_attest/jsonrpc.py`
- [OAuth probes](https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/oauth.py): `src/mcp_attest/oauth.py`

### Trace analysis

- [Trace checks](https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/checks.py): `src/mcp_attest/checks.py`
- [Trace model](https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/trace.py): `src/mcp_attest/trace.py`
- [Shadow paths](https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/shadow.py): `src/mcp_attest/shadow.py`
- [Posture assessment](https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/posture.py): `src/mcp_attest/posture.py`
- [OTLP export](https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/otlp.py): `src/mcp_attest/otlp.py`

### Evidence and rules

- [Rule catalog](https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/rules.py): `src/mcp_attest/rules.py`
- [Evidence bundles](https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/evidence.py): `src/mcp_attest/evidence.py`
- [Call receipts](https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/receipts.py): `src/mcp_attest/receipts.py`
- [Findings report](https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/report.py): `src/mcp_attest/report.py`

### Suites and posture

- [Conformance suites](https://github.com/balanov/mcp-attest/blob/main/src/mcp_attest/suite.py): `src/mcp_attest/suite.py`

### Other components

- **Harness user**
- **MCP server**

## Connections

- Harness user → CLI: runs commands (evidence: `README.md`)
- CLI → Policy model: loads policy (evidence: `src/mcp_attest/cli.py`)
- CLI → Target config: parses target (evidence: `src/mcp_attest/cli.py`)
- CLI → Conformance runner: starts tests (evidence: `src/mcp_attest/cli.py`)
- Conformance runner → MCP client: sends calls (evidence: `src/mcp_attest/conformance.py`)
- MCP client → JSON-RPC: encodes messages (evidence: `src/mcp_attest/client.py`)
- MCP client → MCP server: connects to (evidence: `README.md`)
- Conformance runner → Policy model: compares decisions (evidence: `src/mcp_attest/conformance.py`)
- Conformance runner → OAuth probes: runs probes (evidence: `src/mcp_attest/conformance.py`)
- CLI → Trace checks: runs checks (evidence: `src/mcp_attest/cli.py`)
- Trace checks → Trace model: inspects events (evidence: `src/mcp_attest/checks.py`)
- Trace checks → Policy model: checks policy (evidence: `src/mcp_attest/checks.py`)
- Trace checks → Rule catalog: uses rule IDs (evidence: `src/mcp_attest/checks.py`)
- CLI → Trace model: loads traces (evidence: `src/mcp_attest/cli.py`)
- CLI → Shadow paths: finds bypasses (evidence: `src/mcp_attest/cli.py`)
- Shadow paths → Trace model: reads routes (evidence: `src/mcp_attest/shadow.py`)
- CLI → Posture assessment: assesses posture (evidence: `src/mcp_attest/cli.py`)
- CLI → OTLP export: exports traces (evidence: `src/mcp_attest/cli.py`)
- OTLP export → Trace model: uses trace data (evidence: `src/mcp_attest/otlp.py`)
- CLI → Conformance suites: runs suites (evidence: `src/mcp_attest/cli.py`)
- Conformance suites → Policy model: creates policy (evidence: `src/mcp_attest/suite.py`)
- CLI → Evidence bundles: builds bundles (evidence: `src/mcp_attest/cli.py`)
- Evidence bundles → Call receipts: uses receipts (evidence: `src/mcp_attest/evidence.py`)
- CLI → Findings report: formats findings (evidence: `src/mcp_attest/cli.py`)
- Findings report → Trace checks: renders results (evidence: `src/mcp_attest/report.py`)
- Findings report → Conformance runner: renders results (evidence: `src/mcp_attest/report.py`)
