narya-mcp
OfficialClick on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@narya-mcp start a session on proofs/nat.nry and show me the open holes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
narya-mcp
An MCP server for the Narya proof
assistant. It lets LLM agents typecheck Narya files and develop proofs interactively: load a file into a live Narya
process, inspect the holes (?) with their contexts and types, split holes, check candidate terms, solve holes,
search the project for lemmas, and replay the file after edits.
The interactive tools drive Narya's own ProofGeneral mode (narya -proofgeneral). Its protocol reports goals, hole
positions, error offsets and the current undo instant for every command, so no separate prover backend is needed.
The design follows rocq-mcp.
Install
Requirements: Narya, Python 3.12+ and uv.
git clone https://github.com/balalaika-ai/narya-mcp && cd narya-mcp
uv tool install --editable . # installs the narya-mcp command
uv run pytest # unit tests; with NARYA_BIN=/path/to/narya also the end-to-end testsRegister the server with an MCP client. For Claude Code, a project .mcp.json:
{
"mcpServers": {
"narya": {
"type": "stdio",
"command": "${HOME}/.local/bin/narya-mcp",
"env": { "NARYA_BIN": "/path/to/narya" }
}
}
}Without configuration the server runs NARYA_BIN (or narya on PATH) in the directory of the file. See
Configuration for projects that need more.
Related MCP server: agda-mcp-server
Tools
Positions are 1-based lines and columns; end columns are exclusive. Every response has ok; a failure also has
reason, from a fixed set (src/narya_mcp/reasons.py), and error.
Tool | What it does |
| Typecheck a file in a fresh Narya run: the authoritative check. Errors with file, line and column; warnings; assumed axioms; open holes with their contexts. |
| Typecheck a snippet. With |
| Find |
| Outline of a file: commands, names, line ranges, definitions with holes. |
| Find declarations by words, identifiers or exact name. Narya has no search command; see Search. |
| Full source of a declaration by name, with its location and comment. |
| Start a session: a Narya process that loads the file command by command, up to |
| After an edit, retract the session from the first changed command (Narya |
| Open holes of a session. |
| Narya's proposed shape for a hole (abstraction, tuple, comatch, constructor, or match), not committed. |
| Check up to 20 candidate terms against a hole, without solving it. |
| Type (or normal form) of a term, globally or in the context of a hole. |
| Solve a hole with a term, which may contain new holes. Returns the edit to apply to the file. |
| Run any Narya commands in a session. |
| Session management. |
| Configuration in use, Narya version, live sessions. |
A typical loop: narya_start(file); for each hole, narya_search(session_id, hole), narya_split, narya_try
and narya_synth; narya_solve and apply the edit; narya_sync; at the end, narya_check_file.
Notes:
narya_solvedoes not change the file. Apply the returned edit, andnarya_syncreplays the edited command.narya_trychecks((term) : TYPE)with the printed type of the hole, so it fails if that type mentions other holes.A session command that runs longer than
edit_timeout(120 s) is interrupted with SIGINT: terms whose normalization blows up are stopped before they use all the memory. The session usually survives (see Known issues).Narya stops at the first error of a file; sessions stop loading at the first failing command.
Search
The index holds every def, axiom and mutual and clause of the project, with its signature and the comment just
above it. Optional JSON files (search_annotations) attach labels and descriptions to declarations. Ranking is BM25
over these fields, with identifiers split at _, . and case changes, and with abbreviations learned from the
project (a comment that says "associativity" above a name that contains assoc). The index is cached on disk and
refreshed by file modification times.
With file and line, results are limited to what is visible there (the import closure and earlier declarations).
With session_id and hole, the constants of the goal are added to the query. Narya prints goals in normal form,
where defined constants are unfolded, so the source signature of the definition that contains the hole is used too.
Configuration
A project is configured by a narya-mcp.toml at its root (found by walking up from the file), or by TOML files
listed in NARYA_MCP_CONFIG (separated by :) whose root contains the file.
root = "." # project root, relative to this file
narya = "path/to/narya" # or a launcher, see below
launcher = ["launchers/auto.sh"]
flags = [] # extra Narya flags, for example ["-parametric"]
path_aliases = ["/remote/root"] # paths that Narya may report instead of the project root
quiet_codes = ["W2305"] # diagnostic codes to drop
max_text = 8000 # longer strings in responses are truncated
search_paths = ["src"] # indexed directories (default: the root); imports are followed
search_annotations = ["notes.json"] # JSON lists of {declarations, labels, note, ...}
max_sessions = 4
idle_timeout = 1800 # seconds
command_timeout = 600 # imports and first loads
edit_timeout = 120 # commands under work
load_timeout = 1800
[env] # environment for Narya or the launcher ($VARS expanded, ~ kept)
NAME = "value"narya, launcher and [env] decide what runs, so they are used only from trusted files: those named in
NARYA_MCP_CONFIG, or under a directory listed in NARYA_MCP_TRUSTED. In other files (a cloned repository, for
example) they are ignored, and responses carry config_warnings. NARYA_MCP_JAIL=<dir> refuses files outside
<dir>.
Launchers
A launcher runs Narya somewhere else, for example on a larger machine. It is called as
launcher run <reldir> <narya args...> and must run Narya in <reldir> of its copy of the project, with stdin and
stdout passed through. It may print narya-mcp-pid <token> on stderr; signals are then sent with
launcher signal <token> <SIGNAL>. Lines that start with narya-mcp: on stderr appear as notes in responses.
Included launchers (each script documents its environment variables):
launchers/local-mirror.shruns Narya in a local mirror of the project, so compiled.nyofiles stay out of the source tree.launchers/ssh-workspace.shruns Narya on another machine, in a workspace copied from a precompiled base. A private mount namespace puts the workspace at the path of the base, because.nyofiles store absolute paths. It limits memory and stops Narya when the connection is lost.launchers/auto.shusesssh-workspace.shwhen the host answers, andlocal-mirror.shotherwise.
Measurement
Telemetry. Each call is appended to
$NARYA_MCP_LOG_DIR(default~/.local/state/narya-mcp), one JSONL file per server process and day.NARYA_MCP_LOG=0disables it.scripts/mine_telemetry.pyreports success and latency per tool, the most frequent failure reasons, tools that are never called, and whether search results were used later.Retrieval benchmark.
scripts/search_eval.pybuilds tasks from a project: for a declaration, the query is its comment and signature, and the targets are the constants that its proof uses, among the declarations visible before it. It uses a split by module and a paired bootstrap against the default settings.End-to-end benchmark.
scripts/e2e_bench.pyreplaces definitions of a project with holes, runs headless Claude Code agents in an isolated copy with a budget, and checks the results independently. Its arms differ only in the tools offered (NARYA_MCP_TOOLS).
Known issues
Narya can fail with
anomaly: failure: Meta.Map.find_optwhen it uses a compiled file whose file number changed (gwaithimirdain/narya#142).narya_check_fileandnarya_startthen retry from source.A SIGINT during a computation sometimes stops Narya with
Fatal error: exception Stdlib.Sys.Breakinstead of auser interrupterror. This also occurs without narya-mcp. The session is then lost; start a new one.
License
Apache-2.0
Available Tools
17 toolsnarya_auditNarya AuditB
Audit a file for unsound shortcuts: explicit axiom commands and holes in the file and its whole import
closure (static scan following import/export statements), plus, if typecheck=True, a batch check reporting
the axioms Narya actually assumed. verdict is "clean" only if nothing was found and the check passed.
Inputs: file (required), timeout, typecheck. Returns: object
narya_checkNarya CheckA
Typecheck a snippet of Narya commands (defs, echo, synth, ...).
With file: in the context of that file (its imports and all its definitions), using a session for the file
(an open one is reused, otherwise one is started and kept, so later checks are fast); the snippet's definitions
are undone afterwards. This is the way to try out a lemma next to the code that needs it.
Without file: a fresh run in which the snippet must bring its own import "..." lines (relative to
directory); a snippet with holes fails, since open holes are an error at end of input.
Inputs: source (required), file, timeout, directory. Returns: object
narya_check_fileNarya Check FileA
Typecheck a .ny file with a fresh Narya run (the authoritative check; slow: every import is loaded again).
Use it for the final verdict. While iterating on a file, keep a session instead: narya_start once, then edit the file and call narya_sync, which rechecks only the commands that changed. Returns ok (Narya accepted the file), clean (ok, with no assumed axioms and no open holes), errors with file/line/column, warnings, axioms assumed, holes, timing. Narya stops at the first error in a file. source_only=True ignores compiled .nyo files and rechecks every import from source (slow; for final checks). If loading compiled imports triggers a Narya anomaly, the file is rechecked from source automatically.
Inputs: file (required), timeout, source_only. Returns: object
narya_closeNarya CloseC
Close a session and stop its Narya process.
Inputs: session_id (required). Returns: object
narya_execNarya ExecA
Run Narya commands in a session (def, axiom, echo, synth, notation, import, show, undo, ...), one after the other, stopping at the first failure. Returns each command's output, messages and new holes. Definitions made here are not in the file; narya_sync retracting past them undoes them too.
Inputs: commands (required), session_id (required), timeout. Returns: object
narya_healthNarya HealthB
Toolchain check: which project configuration applies (to file, or the default project), how Narya is run,
its version, and the live sessions with their memory use where measurable.
Inputs: file. Returns: object
narya_holesNarya HolesB
List the open holes of a session: number, position in the file (when known), context and type.
Inputs: session_id (required). Returns: object
narya_lookupNarya LookupB
The full source of a declaration by exact name, with its location, comment and annotations (all files that define the name).
Inputs: name (required), file. Returns: object
narya_searchNarya SearchA
Find declarations (lemmas, definitions, types) by name, words or meaning; Narya itself has no search command.
query may be words ("loop space of the circle"), identifiers or parts of them ("concat inverse"), a book label
("lem:circle-loopspace") or an exact name (ranked first). The index covers names, signatures, the comment above
each declaration and the project's annotation files. With file (and optionally line), only declarations
importable there are returned. With session_id and hole, the constants in the hole's type are added to the
query and the scope is the session's file. kind: def, axiom, data, codata or record.
Inputs: file, hole, kind, line, +3 more. Returns: object
narya_sessionsNarya SessionsA
List live sessions (file, how far it is loaded, idle time, whether the file changed since).
Inputs: no named parameters. Returns: object
narya_solveNarya SolveA
Fill hole hole with term, checked in the hole's context (the term may contain new ? holes, which are
returned). This cannot be undone in Narya. The file is not modified: the result has an edit saying where
the hole is in the file; apply it, and keep the session in sync with narya_sync when you next need it.
Inputs: hole (required), term (required), session_id (required), timeout. Returns: object
narya_splitNarya SplitB
Ask Narya for the shape of a solution of a hole without committing it. Without term: split on the goal
type (abstraction for a function type, tuple for a record, comatch for codata, constructor for a one-constructor
datatype). With term (or comma-separated terms) of a datatype: a match with one branch per constructor.
Inputs: hole (required), session_id (required), term, timeout. Returns: object
narya_startNarya StartA
Start an interactive session (a live Narya process) and return its session_id and open holes.
With file: load the file command by command up to and including the command containing line (default: the
whole file), stopping at the first error (error_at, messages). Holes created by the file are listed with their
position in the file, context and type. With imports (module paths as in import "...", relative to
directory or the file's directory): import them first; without a file this gives a scratch session for
narya_exec / narya_synth. The first load of heavy imports can take a while; afterwards commands are fast.
source_only=True loads imports from source instead of compiled files (slower; used automatically when loading
compiled imports triggers a Narya anomaly).
Inputs: file, line, imports, timeout, +2 more. Returns: object
narya_syncNarya SyncA
Re-read the session's file after edits: retract the commands from the first changed one on (Narya undo)
and replay the file up to and including the command containing line (default: the whole file). Unchanged
commands, including all imports, are kept. Also moves the session backwards when line is earlier.
Inputs: session_id (required), line, timeout. Returns: object
narya_synthNarya SynthA
Synthesize the type of term (Narya synth), or with normalize=True also normalize it (Narya echo).
With hole, the term is elaborated in that hole's context (its variables are in scope). Nothing is committed.
Only synthesizing terms work (constants, applications, ascriptions (t : T)); a bare abstraction does not.
Inputs: term (required), session_id (required), hole, timeout, +1 more. Returns: object
narya_tocNarya TocA
Outline of a .ny file: its commands (def/axiom/notation/import/...) with names and line ranges, and which definitions contain holes. Static; does not run Narya.
Inputs: file (required). Returns: object
narya_tryNarya TryA
Check up to 20 candidate terms against a hole's type, in its context, without solving it. Returns which candidates typecheck (with error messages for the others) and the first success. Commit with narya_solve.
Inputs: hole (required), terms (required), session_id (required), timeout. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Most tools target distinct operations (file check vs snippet check vs session exec; search vs lookup; audit vs holes), so misselection risk is low. However, narya_health slightly overlaps narya_sessions by listing sessions, and the hole-oriented tools narya_try/synth/split, while differentiated in the descriptions, are close enough to warrant care.
All tools follow the same narya_ snake_case prefix with predictable verb/noun forms. There is no mixed casing or inconsistent verb style across the set.
17 tools is slightly above the typical 3-15 range, but each maps to a distinct Narya workflow such as sessions, holes, checking, search, and audit. The set is coherent and not redundant, though it is somewhat heavy.
The surface covers the full interactive proof lifecycle: start/sync/exec/close sessions, check/audit/outline files, list/try/solve/split holes, and search/lookup declarations. No critical operation appears missing for the stated purpose.
Related MCP Connectors
Lean 4 MCP server: compile, prove theorems, and formalize math with Mathlib.
Write, type-check and run AILANG in a sandbox, with Z3-proved contracts and docs search.
Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.
A real-time, multiplayer filesystem for agents and humans: shared files, live edits, history.
Related MCP Servers
- AlicenseBqualityAmaintenanceEnables 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.2214,779 PyPI549MIT
- AlicenseNot gradedqualityDmaintenanceA stateful Model Context Protocol server for interactive Agda proof development, enabling persistent sessions with goal-aware proof actions.33 npm1MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to open, edit, check, run, emit, and save source programs through structured, revision-checked tools over stdio, confining paths to the launch root and returning diagnostics with fixes for rejected edits.5 npm2Apache 2.0
- AlicenseBqualityBmaintenanceEnables coding agents to drive HOL4's built-in hol lsp language server against individual SML script files, exposing proof diagnostics, goal states, evaluation, hover, definitions, symbols and completions as concise text tools. It manages server lifecycle, file syncing, proof-waiting, 1-based Unicode-aware positions, and detection of cheat usage.11BSD 3-Clause