Skip to content

Commit fb06ae8

Browse files
committed
docs(echidna-mcp): add README with usage, tool reference, examples
Covers installation, Claude Code integration (copy-paste JSON block), all three tools (prove, check_prover, list_provers) with parameter tables and return schemas, two example JSON-RPC exchanges (Z3 prove + check_prover), and a troubleshooting section. Adds SPDX header. https://claude.ai/code/session_019HQFtXfCRbUBMDu9dwabGe
1 parent 470b4eb commit fb06ae8

1 file changed

Lines changed: 53 additions & 5 deletions

File tree

crates/echidna-mcp/README.md

Lines changed: 53 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
<!-- SPDX-License-Identifier: PMPL-1.0-or-later -->
2+
<!-- SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk> -->
3+
14
# echidna-mcp
25

36
Model Context Protocol server that exposes [ECHIDNA](https://github.com/hyperpolymath/echidna)'s
@@ -80,6 +83,38 @@ Prove a theorem from a file using one of ECHIDNA's 105 backends.
8083
| `.dfg` | SPASS |
8184
| `.mm` | Metamath |
8285

86+
### `check_prover`
87+
88+
Check whether a named prover backend is installed and reachable on the current system.
89+
90+
| Parameter | Type | Required | Description |
91+
|-----------|------|----------|-------------|
92+
| `prover` | string | yes | Prover backend name (case-sensitive). Examples: `Z3`, `Lean`, `Coq`, `Vampire`. |
93+
94+
**Returns** a JSON object:
95+
```json
96+
{
97+
"available": true,
98+
"message": "Z3 is available"
99+
}
100+
```
101+
102+
### `list_provers`
103+
104+
List all 105 prover backends supported by ECHIDNA. Takes no parameters.
105+
106+
**Returns** a JSON object:
107+
```json
108+
{
109+
"total": 105,
110+
"provers": {
111+
"Z3": "SMT solver (Microsoft Research)",
112+
"Lean": "Lean 4 interactive proof assistant",
113+
"...": "..."
114+
}
115+
}
116+
```
117+
83118
## Example JSON-RPC exchanges
84119

85120
### Prove a trivial SMT goal with Z3
@@ -122,31 +157,44 @@ Response:
122157
}
123158
```
124159

125-
### Auto-detect prover from extension
160+
### Check that Z3 is installed
126161

162+
Request:
127163
```json
128164
{
129165
"jsonrpc": "2.0",
130166
"id": 2,
131167
"method": "tools/call",
132168
"params": {
133-
"name": "prove",
169+
"name": "check_prover",
134170
"arguments": {
135-
"file": "/workspace/lemmas/associativity.v"
171+
"prover": "Z3"
136172
}
137173
}
138174
}
139175
```
140176

141-
ECHIDNA detects `.v` → Coq and routes accordingly.
177+
Response:
178+
```json
179+
{
180+
"jsonrpc": "2.0",
181+
"id": 2,
182+
"result": {
183+
"content": [{
184+
"type": "text",
185+
"text": "{\n \"available\": true,\n \"message\": \"Z3 is available\"\n}"
186+
}]
187+
}
188+
}
189+
```
142190

143191
## Troubleshooting
144192

145193
**`Failed to invoke echidna: No such file or directory`**
146194
: The `echidna` binary is not on PATH. Either install it or set `ECHIDNA_BIN=/full/path/echidna` in the MCP server env config.
147195

148196
**`verified: false` with empty `message`**
149-
: The prover binary itself is missing. Confirm the target prover is installed: `which z3`, `which coqc`, etc. The `echidna check-prover <Name>` command also reports availability.
197+
: The prover binary itself is missing. Confirm the target prover is installed: `which z3`, `which coqc`, etc. The `check_prover` tool also reports availability.
150198

151199
**Timeout / `verified: false` with partial output**
152200
: Increase `timeout_secs`. Complex goals in interactive provers (Isabelle, Coq) may need 60–600 s. Default is 300 s.

0 commit comments

Comments
 (0)