Skip to main content
Glama
RocqSolid
by bn-peters

RocqSolid

PyPI CI

An MCP server for Rocq proof development.

The MCP is deliberately small:

  1. check generates diagnostics for a given file. It tries to return errors from proofs throughout the file. Proof states are cached for efficiency.

  2. run_at runs a command at a given position in a file. This is useful for queries like Search or Check, and for one-off debugging commands.

Requirements

RocqSolid appears to be more stable on OCaml 5 than on OCaml 4. Consider upgrading if you're experiencing crashes.

RocqSolid depends on a patched version of coq-lsp. It improves the stability and error reporting of coq-lsp, and RocqSolid does not work without. It is compatible with Rocq 9.0, 9.1, and 9.2. It needs to be installed in all opam switches RocqSolid should work with:

opam repo add rocq-solid https://github.com/bn-peters/rocq-solid-mcp-opam.git
opam install rocq-solid-mcp-lsp

You might be asked to uninstall coq-lsp. Don't worry, rocq-solid-mcp-lsp is compatible with standard coq-lsp.

Related MCP server: Lean LSP MCP

Agent Setup

We recommend using uv, a Python packaging tool. To teach your favorite agent about RocqSolid:

claude mcp add --scope user rocq-solid -- uvx rocq-solid-mcp
codex mcp add rocq-solid -- uvx rocq-solid-mcp

Project Setup

The MCP looks for _CoqProject and _RocqProject files to set up file dependencies correctly. To generate them in a dune-based project, add (generate_project_file) to your rocq.theory stanzas:

; in theories/dune
(rocq.theory
  (name my-project)
  (generate_project_file)
  (theories Stdlib))

You need to link the right opam switch to your development so that RocqSolid knows which one to use:

opam switch link [switch] .

Timeouts

If you have files that compile very slowly, RocqSolid may time out. You can raise this limit with ROCQ_LSP_TIMEOUT.

For Claude, re-register RocqSolid with a higher limit:

claude mcp remove --scope user rocq-solid
claude mcp add --scope user rocq-solid -e ROCQ_LSP_TIMEOUT=290 -- uvx rocq-solid-mcp

For Codex, add the last two options to the existing entry in ~/.codex/config.toml:

[mcp_servers.rocq-solid]
command = "uvx"
args = ["rocq-solid-mcp"]
# add these two options:
tool_timeout_sec = 300
env = { ROCQ_LSP_TIMEOUT = "290" } # slightly lower than tool_timeout_sec

Upgrading

To upgrade RocqSolid:

uvx rocq-solid-mcp@latest --help

To upgrade coq-lsp, run in your switch:

opam update && opam upgrade rocq-solid-mcp-lsp

Troubleshooting

RocqSolid needs Python 3.11 or newer. If your default python3 is older, uvx reports that no solution was found. Use uvx --python 3.12 rocq-solid-mcp instead.

You can check a single file from the command line, which prints the diagnostics as JSON:

uvx rocq-solid-mcp check path/to/file.v

Environment Variables

All optional; defaults in parentheses.

  • ROCQ_LSP_BINARY (coq-lsp): the coq-lsp executable

  • ROCQ_LSP_USE_OPAM (1): run via opam exec --; 0 runs the binary directly

  • ROCQ_LSP_WORKSPACE (unset): override the inferred workspace root

  • ROCQ_LSP_TIMEOUT (55, max 3600): deadline per call; set slightly below the MCP tool timeout

  • ROCQ_LSP_HARD_TIMEOUT_GRACE (5): extra wait after cancellation before the session is killed

  • ROCQ_LSP_COMMAND_TIMEOUT (5): default per-sentence timeout; 0 disables

  • ROCQ_LSP_TIMEOUT_AFTER_ERROR (10): overall deadline for the rest of a check after its first error; 0 disables

  • ROCQ_LSP_MESSAGE_LIMIT (10, max 50): max errors returned per check

  • ROCQ_LSP_MAX_ERRORS (1000000): max errors coq-lsp collects

  • ROCQ_LSP_IDLE_TTL_SECONDS (1800): idle time before cached sessions are stopped

  • ROCQ_LSP_DUNE_BUILD (1): build dune dependencies before checks; 0 disables

  • ROCQ_LSP_DUNE_TIMEOUT (55, max 3600): limit per dune detection or build command

Support

Join us on the Iris Mattermost!

  1. Go to the GitLab log-in page and select the "GitHub" button, then log in with your GitHub account.

  2. Log in to Mattermost; this should use your GitLab login.

  3. Join the RocqSolid channel.

If you notice that your agent misbehaves with this MCP, please let us know! It would be particularly helpful if you could share your transcripts.

Development

In a clone of this repository:

uv venv .venv && uv pip install -e ".[dev]"
make test

uv tool install -e . installs a development version of rocq-solid-mcp to ~/.local/bin/.

To release a new version, bump version in pyproject.toml and push a tag vX.Y.Z. The release GitHub workflow builds the package and publishes it to PyPI.

Available Tools

2 tools
rocq_check_fileRocq Check FileA

Check a Rocq file and report diagnostics.

Use this to check files for errors. (To find warnings, recompile the file manually.) Error diagnostics include the source sentence and the proof state at error positions.

The first error in a file is always reported, along with later errors reached within the after-error deadline. The list of errors may be truncated. The tool also reports Rocq sentences running for long time.

This tool is efficient due to per-file caching. For dune-based Rocq projects, it attempts to rebuild dependencies before checking and restarts the cached coq-lsp process when that applies. Use clear_cache = true when project files have changed or dependencies were rebuilt outside dune.

Timeouts are handled gracefully, and partial diagnostics are returned when possible. Repeated checks after timeouts use the cache.

Inputs: file (required), clear_cache, command_timeout_seconds, timeout_after_error_seconds. Returns: object

rocq_run_atRocq Run AtA

Run Rocq commands at a file position and return their output.

Use this for running Rocq commands, such as:

  • Search Nat.add.

  • Search insert delete "_eq".

  • Check (3 + 4).

  • About Nat.add.

  • Locate "+".

  • Show. (to show the proof state at a position) The tool is also useful for one-off debugging tasks.

Prefer calling this tool right after imports or between lemmas/definitions. Only use within proofs when necessary.

Inputs: file (required), line (required), commands (required), character. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 2 tools

    Disambiguation4/5

    The two tools have distinct primary purposes: file-level diagnostics versus running Rocq commands at a specific position. There is minor overlap around proof-state inspection, but the descriptions make the intended use clear.

    Naming Consistency4/5

    Both names use the same `rocq_` prefix and snake_case, which is predictable. The action phrasing is slightly inconsistent (`check_file` versus `run_at`), but still readable and coherent.

    Tool Count3/5

    Two tools is thin for a Rocq interaction server, even though both are broad and useful. The surface relies heavily on `rocq_run_at` for many query and debugging tasks.

    Completeness4/5

    The pair covers file checking and arbitrary Rocq command execution, which enables most core workflows. Minor gaps remain, such as warning retrieval requiring manual recompilation and no dedicated proof-state/inspection tool beyond using `rocq_run_at`.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Exposes TypeScript Language Server Protocol functionality to AI agents, enabling them to query types at specific positions, find definitions and references, get diagnostics, run type tests, and type-check inline code just like in an IDE.
      9
      297 npm
      3
      MIT
    • 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
      14,779 PyPI
      549
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI agents with language-aware code analysis through the Language Server Protocol, enabling tasks like getting code insights and diagnostics.
      194
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that bridges LLMs with the Rocq (Coq) proof assistant via LSP, enabling interactive theorem proving with AI.
      10
      Apache 2.0