Skip to content
Back to search

mcp-solver

Model Context Protocol (MCP) server for constraint optimization and solving"

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/szeider/mcp-solver with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/szeider/mcp-solver'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/szeider--mcp-solver/badge.svg)](/listings/szeider--mcp-solver)

HTML

<a href="/listings/szeider--mcp-solver"><img src="/api/listings/szeider--mcp-solver/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> **v4 is not yet installable from PyPI.** The PyPI name `mcp-solver` is > held by a third-party upload of stale v2.0.0 code, and PyPI blocks > confusably similar names; a [PEP 541](https://peps.python.org/pep-0541/) > name-transfer request is pending. Until it resolves, install from a > checkout:

git clone https://github.com/szeider/mcp-solver.git
cd mcp-solver
uv pip install -e ".[agent]"

# OpenRouter key — only needed for the CLI path, not the MCP server:
mkdir -p ~/.config/coder
echo 'OPENROUTER_API_KEY="sk-or-v1-..."' > ~/.config/coder/.env

See [INSTALL.md](INSTALL.md) for details and troubleshooting.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 278 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # MCP Solver
  2. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Python Version](https://img.shields.io/badge/Python-3.13%20%7C%203.14-blue.svg)](https://www.python.org/)
  3. An MCP server for constraint solving (SAT, MaxSAT, SMT, CP, ASP, DP). It turns
  4. the connected LLM host into a solver-writing agent: the host gets a Python
  5. kernel preloaded with a real solver library, modeling instructions for the
  6. chosen backend, and a submission gate. The host encodes the problem, runs
  7. and verifies it against the real solver, and submits the final program —
  8. the outcome is the solution plus the verified solver program that produced
  9. it.
  10. > **Version 4 is a complete re-architecture.** Both the MCP interface and the
  11. > solving engine changed; the design from the SAT 2025 paper (v3) lives on
  12. > unchanged on the
  13. > [`v3`](https://github.com/szeider/mcp-solver/tree/v3) branch.
  14. > See [From v3 to v4](#from-v3-to-v4-a-new-architecture) below.
  15. ## The MCP server
  16. `mcp-solver-serve` runs over stdio and works with any MCP host: Claude
  17. Desktop, Claude Code, Cursor, or your own client. The host LLM does the
  18. solving itself — the server is a solver toolkit; it runs no LLM and needs
  19. no API key:
  20. - **`select_backend(solver)`** sets up a persistent IPython kernel with the
  21. backend's solver library and returns the modeling instructions for that
  22. backend. Calling it again recycles the kernel for the next problem.
  23. - **Kernel tools** (`python_exec`, `python_reset`, `python_status`,
  24. `python_interrupt`) let the host write, run, and verify a real solver
  25. program; bare `python_exec` calls are routed to the solving kernel
  26. automatically.
  27. - **`submit_code(code)`** is the finish line: the final self-contained
  28. program is syntax-checked and, on success, stored and linked back as an
  29. MCP resource (`mcp-solver://submissions/{id}`), with the verdict as
  30. structured content.
  31. - **Resources:** `mcp-solver://guide` (backend selection and workflow) and
  32. `mcp-solver://template/{solver}` (the full modeling instructions,
  33. browsable without selecting).
  34. - **Statistics** (optional): set `MCP_SOLVER_STATS=/path/to/stats.jsonl` in
  35. the server's `env` to log one JSON line per solving episode — tool-call
  36. counts, execution failures, submissions, wall time. Host tokens are
  37. invisible to the server by protocol design; tool usage is the comparable
  38. metric across hosts. (`submit_code` results also carry a compact stats
  39. snapshot as structured content; the CLI path reports tokens and actual
  40. OpenRouter cost via `--stats-json`.)
  41. Claude Desktop configuration, straight from PyPI (no install step; see
  42. [Installation](#installation) for why the package is called
  43. `agentic-mcp-solver`):
  44. ```json
  45. {
  46. "mcpServers": {
  47. "mcp-solver": {
  48. "command": "uvx",
  49. "args": ["--python", "3.14", "--from", "agentic-mcp-solver[agent]", "mcp-solver-serve"]
  50. }
  51. }
  52. }
  53. ```
  54. From a checkout (the development path):
  55. ```json
  56. {
  57. "mcpServers": {
  58. "mcp-solver": {
  59. "command": "uv",
  60. "args": ["run", "--project", "/path/to/mcp-solver", "--extra", "agent", "mcp-solver-serve"]
  61. }
  62. }
  63. }
  64. ```
  65. The server needs no API key — the model doing the solving belongs to the
  66. host. An [OpenRouter](https://openrouter.ai) key is required only for the
  67. [command-line path](#command-line-use) below, which brings its own agent.
  68. ## Requirements
  69. - Python 3.13 or 3.14 (not yet 3.15: the solver kernels run on the server's
  70. Python version, and ortools and python-sat publish no 3.15 wheels yet)
  71. - [uv](https://docs.astral.sh/uv/) (a hard runtime requirement: solver
  72. libraries are supplied at solve time via `uv run --with`)
  73. - An [OpenRouter](https://openrouter.ai) API key — for the CLI and benchmark
  74. harness only; the MCP server itself runs without one
  75. ## Installation
  76. > **The PyPI package is called `agentic-mcp-solver`.** The PyPI name
  77. > `mcp-solver` is held by a third-party upload of stale v2.0.0 code, and a
  78. > [PEP 541](https://peps.python.org/pep-0541/) name-transfer request is
  79. > pending. Do not install `mcp-solver` from PyPI. The import package
  80. > (`mcp_solver`) and the commands (`mcp-solver`, `mcp-solver-serve`) keep
  81. > their names.
  82. ```bash
  83. uv tool install --python 3.14 "agentic-mcp-solver[agent]" # CLI + MCP server
  84. ```
  85. From a checkout (development):
  86. ```bash
  87. git clone https://github.com/szeider/mcp-solver.git
  88. cd mcp-solver
  89. uv venv # Python 3.13 or 3.14, per pyproject.toml
  90. uv pip install -e ".[agent]"
  91. # OpenRouter key — only needed for the CLI path, not the MCP server:
  92. mkdir -p ~/.config/coder
  93. echo 'OPENROUTER_API_KEY="sk-or-v1-..."' > ~/.config/coder/.env
  94. ```
  95. See [INSTALL.md](INSTALL.md) for details and troubleshooting.
  96. ## Command-line use
  97. The `mcp-solver` CLI runs the same solving pipeline without an MCP host,
  98. which is handy for scripts and benchmarks:
  99. ```bash
  100. mcp-solver pysat "Place 8 non-attacking queens on an 8x8 board and give one solution."
  101. mcp-solver pysat --problem tests/problems/pysat/n_queens.md
  102. ```
  103. The solution JSON goes to stdout; the submitted solver program (e.g.
  104. `n_queens_code.py`) and a complete run log (`run_*.json`) land in the working
  105. directory.
  106. | Option | Description |
  107. | ---------------- | ------------------------------------------------------ |
  108. | `--problem FILE` | Read the task from a markdown file instead of text |
  109. | `--model NAME` | Agent model: an alias like `gpt56terra` or a full OpenRouter ID (default: `gpt56terra`) |
  110. | `--workdir DIR` | Working directory for the run (default: current dir) |
  111. | `--step-limit N` | Maximum agent steps before stopping (default: 30) |
  112. | `-q`, `--quiet` | Suppress per-step progress output |
  113. | `--dev [PATH]` | Dev mode: take templates from a local checkout (bare `--dev` auto-detects; auto-on inside a checkout; also `MCP_SOLVER_DEV`) |
  114. | `--no-dev` | Disable dev mode; use the packaged templates |
  115. | `--stats-json FILE` | Write the run statistics to `FILE` as JSON |
  116. From an editable clone, the CLI runs in **dev mode**: templates come from
  117. the source checkout (auto-detected), with one provenance line on
  118. stderr.
  119. ### mcp-minion
  120. The CLI runs **mcp-minion** underneath: a minimal ReAct agent over MCP,
  121. developed in this repo as the workspace package [`minion/`](minion/). It is
  122. a lightweight, batchable substitute for a full MCP host such as Claude
  123. Desktop — point its standalone CLI at `mcp-solver-serve` (or any MCP server)
  124. to script what a chat host would do interactively (see
  125. [minion/README.md](minion/README.md)). The default agent model is
  126. `gpt56terra`, the bundled alias for OpenRouter's `openai/gpt-5.6-terra`.
  127. ## Backends
  128. Each backend is selected as the first CLI argument (or via the
  129. `select_backend` tool). The right solver library is injected into the
  130. solve-time kernel automatically.
  131. | Backend | Domain | Solver library |
  132. | -------- | ------------------------------- | ------------------- |
  133. | `pysat` | Boolean satisfiability (SAT) | python-sat |
  134. | `maxsat` | Weighted optimization | python-sat (RC2) |
  135. | `z3` | SMT solving / verification | z3-solver |
  136. | `cpmpy` | Constraint programming (CP) | cpmpy |
  137. | `clingo` | Answer Set Programming (ASP) | clingo |
  138. | `didp` | Dynamic programming (DIDP) | didppy |
  139. MiniZinc mode from v3 is retired; constraint programming is now covered by
  140. CPMpy. The `didp` backend is based on domain-independent dynamic programming
  141. ([Kuroiwa & Beck](https://didp.ai/); solved with
  142. [didppy](https://didppy.readthedocs.io)'s anytime beam search): problems are
  143. modeled as state transition systems, a natural fit for routing, sequencing,
  144. scheduling, and packing.
  145. ## How it works
  146. Each solve runs in an ephemeral kernel that `uv run --with` sets up with the
  147. backend's solver library only (python-sat, z3-solver, cpmpy, clingo, or
  148. didppy); this package is not installed there, and nothing is pip-installed
  149. into your environment. This keeps the host environment clean and each solve
  150. reproducible.
  151. Each backend ships a **project template**: a markdown prompt (package data)
  152. with the encoding conventions, output format, and library idioms for that
  153. solver. The template goes to whoever solves: an MCP host receives it from
  154. `select_backend`; the CLI hands it to its mcp-minion agent as the system
  155. prompt. Either way, the solving LLM drives the write → execute → verify
  156. loop in a persistent IPython kernel — the `ipython_mcp` server from
  157. [agentic-python-coder](https://github.com/szeider/agentic-python-coder) —
  158. and must end the solve by calling `submit_code` with the final
  159. self-contained program (syntax-checked server-side, never written to disk
  160. by the kernel). On the MCP path the accepted submission is linked back to
  161. the host as a resource; on the CLI path the client extracts the last
  162. successful submission, writes it to `<basename>_code.py`, and re-executes
  163. it in a fresh `uv` kernel to produce the answer.
  164. ## Benchmark harness
  165. `mcp-solver-bench` runs the bundled test problems in `tests/problems/<solver>/`
  166. end-to-end and validates each result against a per-problem
  167. `*_ground_truth.py` validator (which reads the solution JSON on stdin and
  168. returns `{"valid": ..., "message": ...}`).
  169. ```bash
  170. # Benchmark every backend
  171. mcp-solver-bench
  172. # Specific backends, several runs each, in parallel
  173. mcp-solver-bench pysat z3 --runs 3 --jobs 4
  174. ```
  175. Each run is bounded by `--step-limit` (default: 30 agent steps), and results
  176. are appended to `results.jsonl` in the output directory.
  177. The same problems are also runnable as pytest end-to-end tests
  178. (`uv run pytest minion/e2e_tests -k didp`), and `mcp-solver-runfolder
  179. <solver> <problem> <dir>` materializes a standalone mcp-minion run folder
  180. for any of them.
  181. Current status: in our runs with `gpt-5.6-terra`, all 30 bundled test
  182. problems solve correctly, including the four `didp` problems (TSPTW,
  183. knapsack, weighted tardiness, talent scheduling), each solved to proven
  184. optimality in every run. The MCP server path is validated with Claude Opus
  185. as host: 229/229 instances across
  186. [CP-Bench](https://doi.org/10.5281/zenodo.18034815) (101) and
  187. [ASP-Bench](https://doi.org/10.5281/zenodo.18062939) (128) solve correctly
  188. under strict semantic validation, as do the bundled SAT, MaxSAT, and SMT
  189. problems.
  190. ## From v3 to v4: a new architecture
  191. The SAT 2025 paper, ["Bridging Language Models and Symbolic Solvers via the
  192. Model Context Protocol"](https://doi.org/10.4230/LIPIcs.SAT.2025.30),
  193. documents **v3**: an MCP server exposing model-editing tools (`add_item`,
  194. `replace_item`, `solve_model`, …) through which a chat LLM builds up a solver
  195. model item by item, with solving happening inside the server.
  196. **v4 follows the IPython-kernel approach** laid out in the
  197. [CP-Agent](https://doi.org/10.1145/3786181.3788711) (LLM4Code 2026) and
  198. [ASP-Bench](https://doi.org/10.1145/3786168.3788402) (NSE '26) papers:
  199. instead of a
  200. host LLM editing a model through protocol tools, a dedicated coding agent
  201. works in a persistent IPython kernel, where it iteratively writes an actual
  202. Python solver program, executes it against the real solver, verifies the
  203. result independently, and only then submits the program as the answer.
  204. | | v3 (SAT 2025 paper) | v4 (CP-Agent / ASP-Bench approach) |
  205. | ------------------ | -------------------------------------------- | -------------------------------------------------- |
  206. | Who does the work | The host chat LLM, via MCP editing tools | The host LLM (or **mcp-minion** for batch runs), as a solver programmer |
  207. | Unit of work | Model items (`add_item`, `solve_model`, …) | A complete, runnable Python solver program |
  208. | Execution | Inside the MCP server | In a persistent IPython kernel (`ipython_mcp`) |
  209. | Verification | Manual, by the host LLM | Built into the loop: run → check → `submit_code` |
  210. | Artifact | Transient model state | A verified, re-executable program you keep |
  211. | Host interface | Many fine-grained model-editing tools | A solving kernel: `select_backend`, `python_exec`, `submit_code` |
  212. | Backends | MiniZinc, PySAT, MaxSAT, Z3, ASP | PySAT, MaxSAT, Z3, CPMpy, Clingo, DIDP |
  213. ## Citations
  214. - Stefan Szeider, "Bridging Language Models and Symbolic Solvers via the Model
  215. Context Protocol", SAT 2025. Documents the v3 architecture (v3 branch).
  216. [DOI 10.4230/LIPIcs.SAT.2025.30](https://doi.org/10.4230/LIPIcs.SAT.2025.30)
  217. - Stefan Szeider, "CP-Agent: Agentic Constraint Programming", in
  218. *Proceedings of the 3rd International Workshop on Large Language Models
  219. For Code (LLM4Code 2026)*, pages 6–13, ACM, 2026. The IPython-kernel
  220. approach behind v4.
  221. [DOI 10.1145/3786181.3788711](https://doi.org/10.1145/3786181.3788711)
  222. - Stefan Szeider, "ASP-Bench: From Natural Language to Logic Programs", in
  223. *Proceedings of the 2026 IEEE/ACM 2nd International Workshop on
  224. Neuro-Symbolic Software Engineering (NSE '26)*, pages 1–8, ACM, 2026.
  225. The verification-gated benchmark methodology used by v4's test problems.
  226. [DOI 10.1145/3786168.3788402](https://doi.org/10.1145/3786168.3788402)
  227. ## License
  228. MIT; see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.