rocq-solid-mcp 1.0.0__py3-none-any.whl

rocq_solid_mcp/server.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from fastmcp import Context, FastMCP
+from fastmcp.server.lifespan import lifespan
+from pydantic import Field
+
+from .config import bounded_overall_timeout_seconds
+from .manager import RocqLspManager
+from .models import RenderOptions
+
+
+@lifespan
+async def app_lifespan(server: Any) -> Any:
+    manager = RocqLspManager()
+    manager.start_idle_cleanup()
+    try:
+        yield manager
+    finally:
+        await manager.close()
+
+
+mcp = FastMCP("rocq-solid", lifespan=app_lifespan)
+
+
+@mcp.tool()
+async def rocq_check_file(
+    ctx: Context,
+    file: Annotated[
+        str,
+        Field(
+            description="Absolute path to a .v file.",
+        ),
+    ],
+    command_timeout_seconds: Annotated[
+        float | None,
+        Field(
+            description=(
+                "Per Rocq sentence watchdog for checking. None uses the server "
+                "default, 0 disables it, and positive values abort on slow sentences."
+            ),
+        ),
+    ] = None,
+    timeout_after_error_seconds: Annotated[
+        float | None,
+        Field(
+            description=(
+                "Overall deadline once the first error has been reported: "
+                "the whole check is stopped at most this many seconds after "
+                "the first error. None uses the server default, 0 disables "
+                "it, and positive values enable it."
+            ),
+        ),
+    ] = None,
+    clear_cache: Annotated[
+        bool,
+        Field(
+            description=(
+                "Restart this file's coq-lsp process before checking."
+            ),
+        ),
+    ] = False,
+) -> dict[str, Any]:
+    """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.
+    """
+    manager: RocqLspManager = ctx.request_context.lifespan_context
+    result = await manager.check_file(
+        file,
+        command_timeout_seconds=command_timeout_seconds,
+        timeout_after_error_seconds=timeout_after_error_seconds,
+        long_running_seconds=_long_running_alert_threshold(
+            manager.config.timeout_policy.request_seconds
+        ),
+        clear_cache=clear_cache,
+    )
+    return result.render(RenderOptions(message_limit=manager.config.message_limit))
+
+
+@mcp.tool()
+async def rocq_run_at(
+    file: Annotated[str, Field(description="Absolute path to a .v file.")],
+    commands: Annotated[
+        str,
+        Field(
+            description=(
+                "One string containing one or more complete Rocq commands to run at "
+                "the same file position, e.g. 'Require Import List. Check list.'"
+            ),
+        ),
+    ],
+    line: Annotated[
+        int,
+        Field(
+            description=(
+                "1-based line number in the file at which the commands "
+                "string is ran."
+            ),
+        ),
+    ],
+    ctx: Context,
+    character: Annotated[
+        int,
+        Field(description="1-based column offset. Defaults to 1 (start of line)."),
+    ] = 1,
+) -> dict[str, Any]:
+    """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.
+    """
+    manager: RocqLspManager = ctx.request_context.lifespan_context
+    result = await manager.run_at(
+        file,
+        commands,
+        line,
+        character,
+    )
+    return result.render()
+
+
+def _long_running_alert_threshold(request_timeout_seconds: float | None) -> float:
+    return bounded_overall_timeout_seconds(request_timeout_seconds) * 0.8
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

rocq_solid_mcp/session.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from contextlib import suppress
+from pathlib import Path
+
+from .config import RocqLspConfig
+from .notifications import NotificationStore
+from .rocq_client import RocqLspClient
+
+
+class RocqLspSession:
+    def __init__(
+        self,
+        *,
+        workspace: Path,
+        config: RocqLspConfig,
+    ) -> None:
+        self.workspace = workspace
+        self.config = config
+        self.lock = asyncio.Lock()
+        self.active_requests = 0
+        self.last_used_at = time.monotonic()
+        self.versions: dict[str, int] = {}
+        self._client: RocqLspClient | None = None
+        self._notifications = NotificationStore()
+
+    @property
+    def client(self) -> RocqLspClient:
+        if self._client is None:
+            raise RuntimeError("rocq-lsp session has not been started")
+        return self._client
+
+    @property
+    def notifications(self) -> NotificationStore:
+        return self._notifications
+
+    async def start(self) -> None:
+        if self._client is not None:
+            raise RuntimeError("rocq-lsp session has already been started")
+        self.versions.clear()
+        self._notifications = NotificationStore()
+        request_timeout = max(
+            10.0,
+            self.config.timeout_policy.request_seconds
+            + self.config.timeout_policy.cancel_grace_seconds
+            + 5,
+        )
+        client = RocqLspClient(
+            binary=self.config.binary,
+            use_opam=self.config.use_opam,
+            workspace=self.workspace,
+            max_errors=self.config.max_errors,
+            request_timeout=request_timeout,
+            notifications=self._notifications,
+        )
+        self._client = client
+        try:
+            await client.start()
+            await client.notify_change_configuration()
+        except Exception:
+            await self.stop(hard=True)
+            raise
+
+    async def restart(self) -> None:
+        await self.stop(hard=True)
+        await self.start()
+
+    async def stop(self, *, hard: bool = False) -> None:
+        client = self._client
+        self._client = None
+        if client is None:
+            return
+
+        if hard:
+            with suppress(Exception):
+                client.clear_pending_requests()
+            with suppress(Exception):
+                await client.kill_server()
+            return
+
+        with suppress(Exception):
+            await client.close()

rocq_solid_mcp-1.0.0.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: rocq-solid-mcp
+Version: 1.0.0
+Summary: RocqSolid: an MCP server for Rocq proof development, backed by rocq-lsp
+Author: Benjamin Peters
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/bn-peters/rocq-solid-mcp
+Project-URL: Repository, https://github.com/bn-peters/rocq-solid-mcp
+Project-URL: Issues, https://github.com/bn-peters/rocq-solid-mcp/issues
+Keywords: rocq,coq,mcp,proof assistant,lsp,agent
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp<5,>=4.1
+Requires-Dist: pydantic<3,>=2.13
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.25; extra == "dev"
+Requires-Dist: pytest-xdist>=3.6; extra == "dev"
+Dynamic: license-file
+
+# RocqSolid
+
+[![PyPI](https://img.shields.io/pypi/v/rocq-solid-mcp)](https://pypi.org/project/rocq-solid-mcp/)
+[![CI](https://github.com/bn-peters/rocq-solid-mcp/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/bn-peters/rocq-solid-mcp/actions/workflows/ci.yml)
+
+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](https://github.com/bn-peters/coq-lsp)
+of [`coq-lsp`](https://github.com/rocq-community/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:
+```bash
+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`.
+
+## Agent Setup
+
+We recommend using [`uv`](https://docs.astral.sh/uv/), a Python packaging tool.
+To teach your favorite agent about RocqSolid:
+```bash
+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:
+```bash
+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`:
+```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:
+```bash
+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](https://gitlab.mpi-sws.org/users/sign_in) 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](https://mattermost.mpi-sws.org/iris/channels/bens-rocq-mcp) 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:
+```bash
+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.

rocq_solid_mcp-1.0.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+rocq_solid_mcp/__init__.py,sha256=gU22t96hwNKt2vjLV7SVqpCK77_cJv34CU1ZfUhGHrE,186
+rocq_solid_mcp/cli.py,sha256=X-9_S7IQnpwFrCHRUvA9NLbiMLQJE4VTSdUyxfycsHU,1583
+rocq_solid_mcp/config.py,sha256=okA3J6HZuom15mZOOzeI8I4rn-KIbNNtvKbsFlsA_74,5158
+rocq_solid_mcp/manager.py,sha256=eVfN7Vg6TR7G0QXkwkC0n5jp2BxqQ2Wxa_OzyhuxFXA,39457
+rocq_solid_mcp/models.py,sha256=JKBmR_W9cwXR3M8_L8VD08wUbq9ts3hKk6PhmvBbz0E,25280
+rocq_solid_mcp/notifications.py,sha256=h4vrkQqPJsxDZGTr7SYPrYWSj7TAnJxtsZx7bAkrwsM,9426
+rocq_solid_mcp/pipeline.py,sha256=J5_lv2lC4Mjj2ZBHxruLtYJ24CRhey1Z6HvXxsIaTEE,3027
+rocq_solid_mcp/pretty.py,sha256=ZF5tiyvMkiBwyaIdTIsT_6b8Qc5rwpi--kjIFd5QK4A,5272
+rocq_solid_mcp/rocq_client.py,sha256=GdT-LTkA86j3DHUncGmKL7rBqyiA8TfjEKNqwiUrDCU,37096
+rocq_solid_mcp/server.py,sha256=yAosV75ChCJ9rHW9UvSId2V5KOhZViinN085EBvUvz4,4782
+rocq_solid_mcp/session.py,sha256=UwZ1QxFlR809GRzuP2CeuyUEgUIhz_9QFnn4hMcwHPY,2455
+rocq_solid_mcp-1.0.0.dist-info/licenses/LICENSE,sha256=VuNQ6H1MkB-flnJc5QcRPYwSS57yluqfhLrFXeQ754M,1089
+rocq_solid_mcp-1.0.0.dist-info/METADATA,sha256=qzp2iGVtlSh3ZWS2mQ1pHhtYdJbSjgkIrUvEFAlf4FY,6669
+rocq_solid_mcp-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+rocq_solid_mcp-1.0.0.dist-info/entry_points.txt,sha256=RLoXJs-mK9gJwZdvArKgX1N-E27OnNK3-ane6uGlk38,99
+rocq_solid_mcp-1.0.0.dist-info/top_level.txt,sha256=pJxThN1rbjFtzEddrni0dGYkggz_bHOAFihHCAUC34U,15
+rocq_solid_mcp-1.0.0.dist-info/RECORD,,

rocq_solid_mcp-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rocq_solid_mcp-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+bens-rocq-mcp = rocq_solid_mcp.cli:main
+rocq-solid-mcp = rocq_solid_mcp.cli:main

rocq_solid_mcp-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Peters and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rocq_solid_mcp-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rocq_solid_mcp