Proof-MCP
# Proof-MCP
<p align="center">
<img src="assets/proof-mcp-logo.svg" alt="Proof-MCP - Formal QA for Code" width="640">
</p>
[](https://github.com/yasir2000/Proof-MCP/actions/workflows/ci.yml)
[](LICENSE)
[](https://skills.sh/yasir2000/Proof-MCP)
Proof-MCP is a local CLI and MCP server that helps developers verify code
without requiring them to write Lean or TLA+ themselves. Its
[agent skills](.github/skills/proof-verification/SKILL.md) examine a
developer-selected implementation and tests, propose candidate properties,
draft formal artifacts, and ask Proof-MCP to check those artifacts.
[Read the full user guide](docs/USER_GUIDE.md) for installation and setup with
GitHub Copilot, Gemini CLI, Claude Code, Codex, and other MCP-compatible agents.
It complements [Clarity](https://github.com/LegacyCodeHQ/clarity-cli):
Clarity supplies structural dependency and cycle evidence; Proof-MCP checks
runtime tests, Lean theorems, and TLA+ models.
## What a result means
- **Lean:** Lean elaborated the selected theorem file with warnings treated as
errors. This verifies the theorem statements, not that they capture
requirements or describe a separate program.
- **TLA+:** TLC completed the configured finite model without finding a
counterexample. Results depend on the modeled state space, bounds, and
assumptions.
- **Runtime tests:** selected test code exited successfully. This is test
evidence, not a proof.
- **Clarity:** cycle findings are structural evidence only.
Generated specifications are candidate abstractions. Passing a generated
theorem or model does not establish that the executable source refines it.
Proof-MCP reports that boundary instead of silently claiming the program is
proved correct.
Generated TLA+ checks are also marked incomplete if TLC cannot show at least
two distinct reachable states; this is a basic vacuity guard, not a proof that
the selected properties are meaningful.
## Architecture
```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
```
## Requirements
- Node.js 20+
- Lean 4 for Lean checks
- Java 21+ and a TLA+ tools JAR for TLC checks
- Python 3 for configured Python tests
- Optional: Clarity CLI on `PATH`
- Node.js 22.20+ for the current Skills CLI (`npx skills`)
Lean, TLC, Python, and Clarity are selected per check. A project does not need
to install every checker or add `.lean`/`.tla` files just to use the
source-first skill workflow.
## Install and run
### Install the published MCP server
After a release, install the package globally:
```powershell
npm install --global @yasir2000/proof-mcp
proof-mcp
```
Or run it without a global install:
```powershell
npx --yes @yasir2000/proof-mcp
```
For a stdio MCP client, configure `npx` as the server command and use
`@yasir2000/proof-mcp` as its argument. For example, in VS Code:
```json
{
"servers": {
"proof-mcp": {
"type": "stdio",
"command": "npx",
"args": ["--yes", "@yasir2000/proof-mcp"],
"env": {
"PROOF_MCP_WORKSPACE": "${workspaceFolder}",
"TLA2TOOLS_JAR": "C:\\tools\\tla2tools.jar"
}
}
}
}
```
Omit `TLA2TOOLS_JAR` when you do not need TLC checks. Lean and TLC are external
tools; install them separately and ensure they are available to the MCP process.
### Build from source
```powershell
npm install
npm run build
$env:TLA2TOOLS_JAR = "C:\tools\tla2tools.jar"
node dist/index.js
```
The last command starts the MCP stdio server. Set `PROOF_MCP_WORKSPACE` if the
server's working directory is not the project root. VS Code can use
[`.vscode/mcp.json`](.vscode/mcp.json). Set `TLA2TOOLS_JAR` in the environment
before starting VS Code when TLC checks are needed; Lean-only checks do not
require it.
### CLI
```powershell
node dist/index.js --help
node dist/index.js verify
node dist/index.js check-lean path\to\Theorems.lean
node dist/index.js check-tla path\to\Spec.tla path\to\Spec.cfg
node dist/index.js qa-plan
node dist/index.js qa-run qa-<approved-id>
```
After publishing or linking the package, the same commands are available as
`proof-mcp`. `verify` runs the repeatable checks in `.proof-mcp.json`; it does
not require a manifest for the Skill-driven generated-artifact flow.
For generated checks from a CLI pipeline, send JSON on stdin:
```powershell
Get-Content .\generated-bundle.json -Raw | node dist/index.js check-generated
```
The input can contain `leanSource`, `tlaSource` plus `tlaConfig`, or both. It
may also include `sourceFiles`, `observations`, `properties`, and
`assumptions` as provenance.
Generated files are temporary by default. Set `persistGenerated` to `true` to
retain the checked bundle and metadata under `.proof-mcp/generated/`.
## Agent and MCP workflows
The MCP server exposes:
- `proof_check_generated`: check agent-drafted Lean/TLA+ source without
requiring formal files in the project; optionally retain the checked bundle.
- `proof_prepare_verification`: discover source in the selected scope and
return bounded file contents, Clarity dependency graph, and cycle-analysis
context so the agent can generate candidate properties/models.
- `proof_discover_qa`: report detected languages, modules, and candidate
build/test commands without executing them.
- `proof_run_approved_checks`: run selected discovered commands after explicit
user approval. Build/test scripts execute repository code.
- `proof_verify_workspace`: run configured checks, or explain how to use the
source-first workflow when there is no manifest.
- `proof_check_lean` and `proof_check_tla`: check existing formal artifacts.
- `proof_run_python_test`: run one selected Python test file.
The skill guides the agent to inspect the requested source and nearby tests,
separate observed behavior from inferred requirements, propose properties and
assumptions, pick an appropriate checker, generate candidate formal content,
and report checker evidence. It does not force Lean and TLA+ on every project:
use TLA+ for suitable stateful or concurrent behavior, Lean for precise
theorems, and runtime/property-based tests when formalization would mislead.
The CLI `proof-mcp prepare [scope ...]` returns the same source/context bundle.
Automatic specification generation is performed by the attached agent/skill;
the standalone CLI does not contain an LLM or invent specifications on its own.
The CLI `qa-plan` shows candidate checks; `qa-run <id ...>` runs only the
selected command IDs. Add `qaCommands` to `.proof-mcp.json` for a project
without a built-in adapter; custom commands are also approval-gated.
- [Formal verifier agent](.github/agents/formal-verifier.agent.md)
- [Proof-verification skill](.github/skills/proof-verification/SKILL.md)
- [Lean specification skill](.github/skills/lean-spec-generation/SKILL.md)
- [TLA+ model-generation skill](.github/skills/tla-model-generation/SKILL.md)
- [Example workspace manifest](.proof-mcp.json)
### Install the agent skills
The MCP server supplies deterministic checkers; the companion skills teach an
AI agent how to derive candidate Lean theorems and TLA+ models from selected
source. For source-to-spec generation, install the MCP server **and** the
skills in the target agent. From a checked-out copy of this repository:
```powershell
npx skills add . --skill proof-verification lean-spec-generation tla-model-generation
```
Or install the skills directly from GitHub:
```powershell
npx skills add yasir2000/Proof-MCP `
--skill proof-verification `
--skill lean-spec-generation `
--skill tla-model-generation `
--agent github-copilot `
--agent gemini-cli `
--agent claude-code `
--agent codex
```
The command installs project-scoped skills by default. Add `--global` to make
them available across projects, or `--copy` if symlinks are not supported on
your machine. Run `npx skills list` to inspect installed skills.
Connect the installed server with your agent's MCP configuration. For a local
source checkout, build it first and use [`.vscode/mcp.json`](.vscode/mcp.json).
MCP clients that support server instructions also receive the generation
workflow when they connect.
The two specialist skills are Proof-MCP-specific and route generated content
through its temporary artifact checker. They do not require users to add
`.lean` or `.tla` files to the target repository or install separate formal
skill packs.
The manifest is optional for ad hoc generated checks. When used, it lists
workspace-relative Lean files, Python test scripts, TLA+ spec/config pairs,
and whether to include Clarity.
`qaCommands` can add project-specific checks that discovery cannot infer from
the repository's manifests. Each entry is an executable plus argument array;
it is never interpreted as a shell command:
```json
{
"qaCommands": [
{
"name": "Custom test suite",
"program": "my-test-runner",
"args": ["--all"],
"cwd": "."
}
]
}
```
Discovery is heuristic: it only proposes recognized checks, and it reports
languages for which no built-in compile/test adapter is available. It is not a
claim of exhaustive coverage. Review the plan and approve only the commands
you intend to run.
## Examples
### Test a JavaScript inventory function
```powershell
npm --prefix examples/javascript-inventory test
```
In an agent with the MCP server and skills connected, try:
> Review `examples/javascript-inventory/src/reservation.js` and its tests.
> Propose properties for successful and rejected reservations, then check a
> small generated Lean abstraction. Do not run build or test commands until I
> approve the exact commands.
The sample properties include non-negative remaining stock and unchanged stock
when a request is rejected. Generated checks cover their abstraction, not a
source-code refinement proof.
### Check the Python job example
```powershell
python -m unittest discover -s examples/python-job
node dist/index.js check-lean examples/python-job/proofs/Job.lean
node dist/index.js check-tla examples/python-job/specs/Job.tla examples/python-job/specs/Job.cfg
```
This example separates Python tests, a Lean reachable-state invariant, and a
TLC liveness check under weak fairness of `Finish`. See
[`examples/README.md`](examples/README.md) for details and the
[full user guide](docs/USER_GUIDE.md) for agent-driven walkthroughs.
## Development
```powershell
npm ci
npm test
npm --prefix examples/javascript-inventory test
python -m unittest discover -s examples/python-job
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for development and pull request
guidance. Apache-2.0 licensed; see [LICENSE](LICENSE).
## Contributors
See the [GitHub contributors graph](https://github.com/yasir2000/Proof-MCP/graphs/contributors).
## Publishing
The npm package is `@yasir2000/proof-mcp`; the MCP Registry name is
`io.github.yasir2000/proof-mcp`. Before the first automated release:
1. If the npm package does not exist yet, publish its first version from an
authenticated maintainer account with `npm publish --access public`. This
account requires two-factor authentication; enter any prompted OTP only in
your local terminal, never in chat or a committed file. Then, in the npm
package's **Trusted Publisher** settings, select GitHub Actions with owner
`yasir2000`, repository `Proof-MCP`, and workflow filename `release.yml`.
Allow direct `npm publish` for that publisher.
2. Ensure GitHub Actions is enabled for the repository. The release workflow
uses GitHub OIDC for npm and the MCP Registry; it does not need stored npm or
MCP Registry tokens.
For each release, update the version in `package.json` and `server.json`
together, push the commit, and push the matching version tag (for example,
`v0.1.0`). The workflow checks the tag and metadata versions, runs tests,
publishes the public npm package, publishes the MCP server metadata, and creates
a GitHub Release with generated notes. The npm package version is checked first
so rerunning a partially completed release does not try to publish that npm
version twice.
The agent skills remain installable from this public GitHub repository through
the Skills CLI (`npx skills add yasir2000/Proof-MCP`); they are distributed
separately from the npm package.
TDQS
Scored across 8 tools
Most tools have clearly distinct roles across discovery, preparation, execution, and verification. The main overlap is between proof_verify_workspace and proof_check_generated, and between proof_discover_qa and proof_prepare_verification, but descriptions clarify their boundaries.
All tools use a consistent proof_<verb>_<object> pattern, such as proof_check_lean, proof_run_python_test, and proof_verify_workspace. The shared prefix and verb-noun structure make the set predictable.
Eight tools is well-scoped for a verification workflow covering discovery, preparation, checking, and approved execution. Each tool has a distinct stage or artifact type, with no obvious padding.
The surface covers the main lifecycle from QA discovery through Lean/TLA+ checks and generated artifact verification. Minor gaps exist around inspecting prior results or managing .proof-mcp.json artifacts, but agents can work around them.