# yasir2000/proof-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/yasir2000/proof-mcp
- Repository: https://github.com/yasir2000/proof-mcp

## Overview

Proof-MCP is a local CLI and stdio MCP server for code-verification workflows. Developers or agents request source context or QA discovery, then submit candidate Lean/TLA+ artifacts or select checks; the server dispatches them to external checkers and returns bounded evidence. Configured workspace verification, approval-gated QA commands, Clarity context, and source preparation are distinct capabilities. Edges below follow the shown entry-point dispatch and sampled module calls; README-documented but unsampled agent skills are represented without speculative implementation links.

Main entry points: [`src/runner.ts`](https://github.com/yasir2000/proof-mcp/blob/main/src/runner.ts) (Checker execution), [`src/index.ts`](https://github.com/yasir2000/proof-mcp/blob/main/src/index.ts) (CLI and MCP entry), [`src/config.ts`](https://github.com/yasir2000/proof-mcp/blob/main/src/config.ts) (Workspace config), [`src/context.ts`](https://github.com/yasir2000/proof-mcp/blob/main/src/context.ts) (Source preparation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and MCP"]
  node_entrypoint["CLI and MCP entry<br/>[index.ts]"]
  node_workspace_config["Workspace config<br/>[config.ts]"]
end

subgraph group_context["Workspace Context"]
  node_source_context["Source preparation<br/>[context.ts]"]
end

subgraph group_verification["Verification"]
  node_workspace_verify["Configured verification<br/>[workspace.ts]"]
  node_generated_verify["Generated artifact checks<br/>[generated.ts]"]
  node_checker_runner["Checker execution<br/>[runner.ts]"]
end

subgraph group_qa["QA Planning"]
  node_qa_planner["QA discovery and approval<br/>[qa.ts]"]
end

node_developer(("Developer or agent"))
node_lean["Lean 4"]
node_tlc["TLC model checker"]
node_python["Python runtime"]
node_clarity["Clarity CLI"]
node_qa_commands["Approved project commands"]
node_agent_skills["Agent specification skills<br/>[skills]"]
node_workspace_files["Selected source and tests"]
node_run_artifacts["Temporary or retained artifacts"]

node_developer -->|"requests checks"| node_entrypoint
node_agent_skills -->|"guides generation"| node_developer
node_entrypoint -->|"resolves workspace"| node_workspace_config
node_entrypoint -->|"prepares context"| node_source_context
node_source_context -->|"resolves paths"| node_workspace_config
node_source_context -->|"reads selected files"| node_workspace_files
node_source_context -->|"requests Clarity context"| node_checker_runner
node_entrypoint -->|"discovers or runs QA"| node_qa_planner
node_qa_planner -->|"reads optional config"| node_workspace_config
node_qa_planner -->|"runs approved commands"| node_qa_commands
node_entrypoint -->|"verifies configured workspace"| node_workspace_verify
node_workspace_verify -->|"reads manifest"| node_workspace_config
node_workspace_verify -->|"dispatches checks"| node_checker_runner
node_entrypoint -->|"checks generated artifacts"| node_generated_verify
node_generated_verify -->|"validates workspace paths"| node_workspace_config
node_generated_verify -->|"writes temporary artifacts"| node_run_artifacts
node_generated_verify -->|"checks generated files"| node_checker_runner
node_checker_runner -->|"runs Lean"| node_lean
node_checker_runner -->|"runs TLC"| node_tlc
node_checker_runner -->|"runs test file"| node_python
node_checker_runner -->|"runs analysis"| node_clarity

click node_entrypoint "https://github.com/yasir2000/proof-mcp/blob/main/src/index.ts"
click node_workspace_config "https://github.com/yasir2000/proof-mcp/blob/main/src/config.ts"
click node_source_context "https://github.com/yasir2000/proof-mcp/blob/main/src/context.ts"
click node_qa_planner "https://github.com/yasir2000/proof-mcp/blob/main/src/qa.ts"
click node_workspace_verify "https://github.com/yasir2000/proof-mcp/blob/main/src/workspace.ts"
click node_generated_verify "https://github.com/yasir2000/proof-mcp/blob/main/src/generated.ts"
click node_checker_runner "https://github.com/yasir2000/proof-mcp/blob/main/src/runner.ts"
click node_agent_skills "https://github.com/yasir2000/proof-mcp/tree/main/.github/skills"

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_entrypoint,node_workspace_config toneBlue
class node_source_context toneAmber
class node_workspace_verify,node_generated_verify,node_checker_runner toneMint
class node_qa_planner toneRose
class node_developer,node_lean,node_tlc,node_python,node_clarity,node_qa_commands,node_workspace_files,node_run_artifacts toneIndigo
class node_agent_skills toneTeal
```

## Components

### CLI and MCP

- [CLI and MCP entry](https://github.com/yasir2000/proof-mcp/blob/main/src/index.ts): `src/index.ts`
- [Workspace config](https://github.com/yasir2000/proof-mcp/blob/main/src/config.ts): `src/config.ts`

### Workspace Context

- [Source preparation](https://github.com/yasir2000/proof-mcp/blob/main/src/context.ts): `src/context.ts`

### Verification

- [Configured verification](https://github.com/yasir2000/proof-mcp/blob/main/src/workspace.ts): `src/workspace.ts`
- [Generated artifact checks](https://github.com/yasir2000/proof-mcp/blob/main/src/generated.ts): `src/generated.ts`
- [Checker execution](https://github.com/yasir2000/proof-mcp/blob/main/src/runner.ts): `src/runner.ts`

### QA Planning

- [QA discovery and approval](https://github.com/yasir2000/proof-mcp/blob/main/src/qa.ts): `src/qa.ts`

### Other components

- **Developer or agent**
- **Lean 4**
- **TLC model checker**
- **Python runtime**
- **Clarity CLI**
- **Approved project commands**
- [Agent specification skills](https://github.com/yasir2000/proof-mcp/tree/main/.github/skills): `.github/skills`
- **Selected source and tests**
- **Temporary or retained artifacts**

## Connections

- Developer or agent → CLI and MCP entry: requests checks (evidence: `README.md`)
- Agent specification skills → Developer or agent: guides generation (evidence: `README.md`)
- CLI and MCP entry → Workspace config: resolves workspace (evidence: `src/index.ts`)
- CLI and MCP entry → Source preparation: prepares context (evidence: `src/index.ts`)
- Source preparation → Workspace config: resolves paths (evidence: `src/context.ts`)
- Source preparation → Selected source and tests: reads selected files (evidence: `src/context.ts`)
- Source preparation → Checker execution: requests Clarity context (evidence: `src/context.ts`)
- CLI and MCP entry → QA discovery and approval: discovers or runs QA (evidence: `src/index.ts`)
- QA discovery and approval → Workspace config: reads optional config (evidence: `src/qa.ts`)
- QA discovery and approval → Approved project commands: runs approved commands (evidence: `src/qa.ts`)
- CLI and MCP entry → Configured verification: verifies configured workspace (evidence: `src/index.ts`)
- Configured verification → Workspace config: reads manifest (evidence: `src/workspace.ts`)
- Configured verification → Checker execution: dispatches checks (evidence: `src/workspace.ts`)
- CLI and MCP entry → Generated artifact checks: checks generated artifacts (evidence: `src/index.ts`)
- Generated artifact checks → Workspace config: validates workspace paths (evidence: `src/generated.ts`)
- Generated artifact checks → Temporary or retained artifacts: writes temporary artifacts (evidence: `src/generated.ts`)
- Generated artifact checks → Checker execution: checks generated files (evidence: `src/generated.ts`)
- Checker execution → Lean 4: runs Lean (evidence: `src/runner.ts`)
- Checker execution → TLC model checker: runs TLC (evidence: `src/runner.ts`)
- Checker execution → Python runtime: runs test file (evidence: `src/runner.ts`)
- Checker execution → Clarity CLI: runs analysis (evidence: `src/runner.ts`)
