Skip to main content
Glama

Proof-MCP

CI License: Apache-2.0 Skills

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 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 for installation and setup with GitHub Copilot, Gemini CLI, Claude Code, Codex, and other MCP-compatible agents.

It complements Clarity: 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.

Related MCP server: lean-mcp

Architecture

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:

npm install --global @yasir2000/proof-mcp
proof-mcp

Or run it without a global install:

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:

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

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. Set TLA2TOOLS_JAR in the environment before starting VS Code when TLC checks are needed; Lean-only checks do not require it.

CLI

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:

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.

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:

npx skills add . --skill proof-verification lean-spec-generation tla-model-generation

Or install the skills directly from GitHub:

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. 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:

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

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

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 for details and the full user guide for agent-driven walkthroughs.

Development

npm ci
npm test
npm --prefix examples/javascript-inventory test
python -m unittest discover -s examples/python-job

See CONTRIBUTING.md for development and pull request guidance. Apache-2.0 licensed; see LICENSE.

Contributors

See the GitHub contributors graph.

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.

Available Tools

8 tools
proof_check_generatedCheck generated formal artifactsA

Check agent-drafted Lean and/or TLA+ content without requiring formal files in the repository. Optionally retain the checked bundle and its properties/assumptions under .proof-mcp/generated/.

Inputs: purpose, tlaConfig, tlaSource, leanSource, +5 more.

proof_check_leanCheck Lean proofA

Check one workspace-relative Lean 4 file with warnings treated as errors.

Inputs: filePath (required).

proof_check_tlaModel check TLA+C

Run TLC on a workspace-relative TLA+ module and TLC configuration.

Inputs: specPath (required), configPath (required).

proof_discover_qaDiscover QA coverageA

Inspect workspace manifests and source extensions to report detected languages, modules, and candidate build/test commands. This is planning only and never executes project commands.

Inputs: no named parameters.

proof_prepare_verificationPrepare source verificationB

Discover source files in an optional scope, collect a bounded source context and Clarity dependency graph, and return instructions for the agent to draft properties and candidate Lean/TLA+ artifacts.

Inputs: purpose, maxFiles, scopePaths, maxCharacters, +1 more.

proof_run_approved_checksRun approved QA checksA

Execute only discovered command IDs that the user explicitly approved. This runs local repository code. Never call this tool until the user has seen the plan and approved the selected IDs.

Inputs: approvedCommandIds (required).

proof_run_python_testRun Python testA

Run one workspace-relative Python test file. This executes local code and is runtime evidence, not a formal proof.

Inputs: filePath (required).

proof_verify_workspaceVerify configured workspaceA

Run artifacts from .proof-mcp.json. If no manifest exists, use proof_check_generated to check candidate artifacts without adding Lean or TLA+ files to the project.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 8 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      A
      maintenance
      Enables LLM agents to interact with the Lean theorem prover through the Language Server Protocol, providing tools for analyzing Lean projects, accessing diagnostics, goal states, documentation, and searching for theorems using both local and external search services.
      22
      81,428 PyPI
      559
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI coding agents to perform Lean 4 formal verification, navigate project symbols offline, and inspect C FFI bindings.
      5
      4
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI-driven formal proof search in Lean 4 by submitting theorems with sorry placeholders and running parallel LLM agents whose proposed edits are verified by the Lean compiler until a machine-checked proof is produced. Also provides Mathlib theorem search and job/attempt management tools.
      3
      MIT