agentic-mcp-solver 4.2.0__tar.gz

agentic_mcp_solver-4.2.0/.gitignore

@@ -0,0 +1,89 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.uv/
+
+# Logs and databases
+*.log
+*.sqlite3
+*.sqlite3-journal
+
+# IDE specific files
+.idea/
+.vscode/
+*.swp
+*.swo
+.cursor/
+
+# OS specific files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Project specific files
+mcp_solver.log
+uv.lock
+mcp-solver.txt
+tests/results/
+CLAUDE.md
+CLAUDE-TEST.md
+docs/
+tmp/
+.mcp.json
+LM_STUDIO_IMPLEMENTATION.md
+local/
+tester-report.md
+testers_report.md
+fix-analysis-script.patch
+
+# Distribution / packaging
+dist/
+*.egg-info/
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/ docs/
+bench_results/

agentic_mcp_solver-4.2.0/CHANGELOG.md

@@ -0,0 +1,128 @@
+# Changelog
+
+### [4.2.0] - 2026-11-13
+
+- **Major Change:** Published on PyPI as `agentic-mcp-solver`, since the name
+  `mcp-solver` is held by an unrelated upload (PEP 541 request pending). The
+  import package and the commands keep their names. Solve kernels fetch the
+  helper library as `agentic-mcp-solver==<version>`.
+- **New Feature:** Supports the MCP Python SDK 2.x alongside 1.x
+  (`mcp>=1.25,<3`); requires agentic-python-coder 3.4.4 and mcp-minion 0.2.2.
+  Resource errors (for example an unknown solver) now raise `ResourceError`,
+  so their text reaches the client under mcp 2.x.
+- **Behavior Change:** The didp backend requires didppy 0.11.1 or later
+  (`>=0.11.1,<0.12`).
+
+### [4.1.0] - 2026-07-22
+
+- **New Feature:** DIDP backend (domain-independent dynamic programming via
+  didppy): state-based modeling with dual-bound and dominance safety rules in
+  the template, plus four benchmark problems (knapsack, talent scheduling,
+  weighted tardiness, TSPTW) with in-validator exact oracles. The bundled
+  benchmark now spans 30 problems across six backends.
+
+### [4.0.0] - 2026-07-14
+
+- **Major Change:** Complete re-architecture. The solving LLM now writes, runs,
+  and verifies a real solver program in a persistent IPython kernel (the kernel
+  server of agentic-python-coder) instead of editing a model item by item
+  through protocol tools. The final program is submitted through a
+  syntax-checked gate (`submit_code`), persisted, and re-executed to produce
+  the solution JSON.
+- **Major Change:** The MCP server (`mcp-solver-serve`) is a solver toolkit for
+  the host LLM — it runs no LLM and needs no API key: `select_backend` sets up
+  a kernel with the solver library, helpers, and modeling instructions; kernel
+  tools and `submit_code` do the rest.
+- **Major Change:** MiniZinc mode retired; CPMpy added. Backends are now
+  PySAT, MaxSAT, Z3, CPMpy, and Clingo. The v3 MCP server lives on unchanged
+  on the `v3` branch.
+- **New Feature:** `mcp-solver` CLI and `mcp-solver-bench` benchmark harness,
+  driven by the bundled **mcp-minion** ReAct agent (also published separately
+  on PyPI) via OpenRouter.
+- **New Feature:** Dependency-free helper library (`mcp_solver.helpers`)
+  injected into solve-time kernels via `uv run --with`.
+- **Improvement:** Every shipped test problem carries an output-format contract
+  and a semantic ground-truth validator; validated end-to-end on the bundled
+  26-problem benchmark and externally on CP-Bench and ASP-Bench.
+- **Note:** Not yet installable from PyPI: the name `mcp-solver` is held by an
+  unrelated third-party upload of stale v2.0.0 code, and PyPI blocks
+  confusably similar names; a PEP 541 name-transfer request is pending. The
+  companion agent **mcp-minion** is on PyPI.
+
+### [3.4.0] - 2025-09-13
+
+- **New Feature:** Complete Answer Set Programming (ASP) mode implementation with Clingo solver (contributed by Luis Angel Rodriguez Reiners)
+  - Full ASP syntax support including facts, rules, constraints, and choice rules
+  - Support for optimization statements (#maximize, #minimize) and weak constraints
+  - Enhanced error handling with detailed validation messages
+  - Six comprehensive test problems demonstrating ASP capabilities
+
+### [3.3.0] - 2025-06-10
+
+- **New Feature:** Added MaxSAT as a 4th mode for weighted optimization problems using RC2 solver
+- **Improvement:** Implemented exact token counting with callback handlers for better usage tracking
+- **Update:** Replaced Black with Ruff for code formatting and linting
+- **Improvement:** Enhanced MaxSAT and Z3 instructions with clearer guidance and examples
+- **Fix:** Resolved error handling issues in PySAT/MaxSAT to preserve UNSAT status correctly
+- **Update:** Added MaxSAT test infrastructure and aligned test problems with experiment6
+- **Improvement:** Added cardinality constraint templates and helper functions for MaxSAT
+
+### [3.2.0] - 2025-05-11
+
+- **Improvement:** Simplified model specification by removing internal model code shortcuts (MC1, MC2, etc.)
+- **Improvement:** Updated client to use direct model codes (AT:claude-3-7-sonnet-20250219, etc.) for better clarity
+- **Update:** Enhanced documentation for model code formats in README.md and INSTALL.md
+- **Update:** Added support for LM Studio local models
+
+---
+
+### [3.1.0] - 2025-04-03
+
+- **Improvement:** Enhanced test client with additional features for better usability and testing workflows.
+- **Improvement:** Improved solution export for Z3 mode, providing better data representation and accessibility.
+- **Update:** Enhanced installation documentation with more detailed setup notes and requirements
+
+### [3.0.0] - 2025-03-28
+
+- **Major Change:** Added PySAT mode and Z3 mode, expanding the supported constraint programming paradigms.
+- **Major Change:** Added a standalone test client for easier testing and demonstration.
+- **Major Change:** Lite mode is now the default mode. The additional tools have been removed from the default configuration.
+- **Update:** The server now advertises only a reduced set of tools by default (clear_model, add_item, replace_item, delete_item, and solve_model).
+
+### [2.3.0] - 2025-02-28
+
+- **New Feature:** Introduced Lite Mode for the MCP Solver. When run with the `--lite` flag, the server advertises only a reduced set of tools (clear_model, add_item, replace_item, delete_item, and solve_model).
+- **New Feature:** In Lite Mode, the `solve_model` tool returns only the status (and the solution if SAT) without additional metadata.
+- **New Feature:** Mode-specific instruction prompts are used: `instructions_prompt_mzn.md` for MiniZinc, `instructions_prompt_pysat.md` for PySAT, and `instructions_prompt_z3.md` for Z3.
+
+### [2.2.0] - 2025-02-15
+
+- **New Feature:** Integrated static prompt endpoints (`prompts/list` and `prompts/get`) to advertise MCP prompt templates ("quick_prompt" and "detailed_prompt") without requiring any arguments.
+- **New Feature:** Advertised detailed tool capabilities by adding descriptive metadata for each tool in the server's capabilities declaration.
+- **Improvement:** Enhanced error reporting for tool endpoints with improved logging and standardized error responses.
+- **Update:** Refactored server initialization to explicitly log the declared capabilities for greater transparency and easier debugging.
+
+### [2.1.0] - 2025-02-09
+
+- **Update:** Change minimum Python requirement to 3.11+ (to support `asyncio.timeout`).
+- **Update:** Bump dependency on `mcp` to version 1.2.0 or later.
+- **Improvement:** Update tool handler messages so that "delete_item" and "replace_item" commands correctly report the operation performed.
+- **Update:** Miscellaneous documentation and cleanup.
+
+### [2.0.0] - 2024-12-29
+
+- Major change: Use item-based editing.
+
+### [1.0.0] - 2024-12-21
+
+- Major change: Use line-based model editing.
+- Makes parameter handling obsolete.
+- Added dynamic knowledge base handling.
+
+### [0.2.1] - 2024-12-16
+
+- Changed parameter handling.
+
+### [0.2.0] - 2024-12-15
+
+- Initial release.

agentic_mcp_solver-4.2.0/INSTALL.md

@@ -0,0 +1,218 @@
+# MCP Solver Installation
+
+MCP Solver v4 lets an LLM write and run real solver programs in a
+persistent IPython kernel (the kernel server of
+[agentic-python-coder](https://github.com/szeider/agentic-python-coder)).
+The solving LLM is either your MCP host (Claude Desktop/Code, Cursor —
+via `mcp-solver-serve`) or the bundled [mcp-minion](minion/) agent (via the
+`mcp-solver` CLI). This guide covers prerequisites, the install variants,
+verification, and common problems.
+
+> **The PyPI package is called `agentic-mcp-solver`.** The PyPI name
+> `mcp-solver` is held by a third-party upload of stale v2.0.0 code, and a
+> [PEP 541](https://peps.python.org/pep-0541/) name-transfer request is
+> pending. Do not install `mcp-solver` from PyPI. The import package
+> (`mcp_solver`) and the commands keep their names.
+
+> **Platform note.** v4 has so far been tested on macOS only. The Windows and
+> Linux instructions below carry over from v3 and have not yet been
+> re-verified under v4; an update will follow.
+
+> Looking for the v3 MCP server (MiniZinc/PySAT/MaxSAT/Z3/ASP)? It lives on the
+> **`v3`** branch, which keeps its own setup instructions.
+
+---
+
+## Prerequisites
+
+### Python 3.13 or 3.14
+
+MCP Solver v4 requires Python 3.13 or 3.14. Python 3.15 does not work yet:
+the solver kernels run on the same Python version as the server, and ortools
+(needed by cpmpy) and python-sat publish no 3.15 wheels yet. uv picks a
+supported version automatically from `pyproject.toml`, even when its own
+default is 3.15.
+
+```bash
+# macOS (Homebrew)
+brew install python@3.13
+
+# Windows
+winget install --id Python.Python.3.13
+
+# Linux: install via your distribution or pyenv
+python3.13 --version
+```
+
+### uv
+
+[uv](https://docs.astral.sh/uv/) is a hard runtime requirement, not just a
+convenience: solver libraries and the MCP Solver helper library are supplied at
+solve time via `uv run --with`, never pip-installed into your environment.
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Verify:
+
+```bash
+uv --version
+```
+
+### OpenRouter API key (CLI path only)
+
+The MCP server needs no API key — the host brings its own model. A key is
+required only for the `mcp-solver` CLI and the benchmark harness, whose
+bundled mcp-minion agent calls models through
+[OpenRouter](https://openrouter.ai). Store the key in one of the places the
+CLI looks:
+
+```bash
+mkdir -p ~/.config/coder
+echo 'OPENROUTER_API_KEY="sk-or-v1-..."' > ~/.config/coder/.env
+```
+
+`OPENROUTER_API_KEY` in the environment works too, as does `~/.mcp-minion`
+(the standalone mcp-minion CLI's location). One key serves everything.
+
+---
+
+## Install
+
+### Clone + editable (development)
+
+The `[agent]` extra pulls in `mcp-minion` (the agent loop) and
+`agentic-python-coder` (the IPython kernel MCP server and model aliases); the
+bare `agentic-mcp-solver` package is only the dependency-free helper library and
+cannot solve anything on its own.
+
+```bash
+git clone https://github.com/szeider/mcp-solver.git
+cd mcp-solver
+uv venv                               # Python 3.13 or 3.14, per pyproject.toml
+uv pip install -e ".[agent]"          # product layer
+uv pip install -e ".[agent,test]"     # + benchmark harness and unit tests
+# uv pip install -e ".[all]"          # everything, including dev tools
+```
+
+An editable install runs in **dev mode**: the CLI auto-detects the source
+checkout and takes both the helper library and the solver templates straight
+from it (printing one provenance line to stderr), so nothing extra is needed to
+run a solve. Use `--dev PATH` (or `MCP_SOLVER_DEV`) to point at a checkout
+explicitly, or `--no-dev` to force the published (PyPI-pinned) helpers.
+
+### From PyPI
+
+`uv tool install --python 3.14 "agentic-mcp-solver[agent]"` installs the
+`mcp-solver` CLI and the `mcp-solver-serve` MCP server, with no clone
+required; the MCP server also runs without any install:
+`uvx --python 3.14 --from "agentic-mcp-solver[agent]" mcp-solver-serve`.
+
+The individual extras are:
+
+| Extra     | Contents                                                        |
+| --------- | -------------------------------------------------------------- |
+| `[agent]` | Product layer: CLI, templates, mcp-minion agent, kernel server  |
+| `[test]`  | Solver libraries (python-sat, z3-solver, cpmpy, clingo, didppy) + pytest |
+| `[dev]`   | ruff                                                            |
+| `[all]`   | `[agent]` + `[test]` + `[dev]`                                  |
+
+### Using the local version (no PyPI involved)
+
+The checkout is fully self-sufficient — development and testing never wait on
+a PyPI release. Everything resolves locally: `mcp-minion` comes from the
+`minion/` workspace member, and dev mode injects the helper library and
+templates straight from the checkout (auto-detected; also available
+explicitly as `--dev PATH` or `MCP_SOLVER_DEV=/path`).
+
+Run the CLI or the benchmark harness from anywhere by pointing `uv` at the
+checkout:
+
+```bash
+uv run --project /path/to/mcp-solver --extra agent mcp-solver z3 "task ..."
+uv run --project /path/to/mcp-solver --extra agent --extra test mcp-solver-bench pysat
+```
+
+Use the local MCP server in an MCP host (Claude Desktop, Claude Code, Cursor)
+with this configuration:
+
+```json
+{
+  "mcpServers": {
+    "mcp-solver": {
+      "command": "uv",
+      "args": ["run", "--project", "/path/to/mcp-solver", "--extra", "agent", "mcp-solver-serve"]
+    }
+  }
+}
+```
+
+This is the supported development path alongside the PyPI release: `--dev`
+always wins over the PyPI pin.
+
+---
+
+## Verify
+
+Check the CLI is available:
+
+```bash
+mcp-solver --help
+```
+
+Run your first solve (canonical example shipped in the repo):
+
+```bash
+mcp-solver pysat --problem tests/problems/pysat/n_queens.md
+```
+
+You should see per-step progress on stderr, a compact stats line, and the
+solution JSON on stdout. The submitted solver program (`n_queens_code.py`) and
+a run log (`run_*.json`) appear in the working directory.
+
+For a full end-to-end check across all backends, run the benchmark harness:
+
+```bash
+mcp-solver-bench pysat --runs 1
+```
+
+---
+
+## Troubleshooting
+
+**`mcp-solver: the agent layer is not installed`**
+You installed the bare package without the product layer. Install the `[agent]`
+extra: `uv pip install "agentic-mcp-solver[agent]"`, or
+`uv pip install -e ".[agent]"` from a checkout (see [Install](#install)).
+
+**`the ipython_mcp server does not provide submit_code`** (CLI) or
+**`the ipython_mcp engine is unavailable or lacks submit_code`** (server)
+Your installed `agentic-python-coder` is older than 3.4.3, or missing from
+the environment the server runs in. Upgrade it:
+`uv pip install "agentic-python-coder>=3.4.3"` (or `-e` from a checkout).
+
+**`uv: command not found` (or the solve fails to start a kernel).**
+uv is missing from your PATH. Install it (see Prerequisites) and make sure its
+install directory (usually `~/.local/bin`) is on your `PATH`. uv is mandatory —
+solver libraries are injected through `uv run --with`.
+
+**`mcp-solver: no OpenRouter API key found.`**
+The key is not being located. Either export `OPENROUTER_API_KEY` in your shell,
+or put it in `~/.config/coder/.env` as `OPENROUTER_API_KEY="..."`. The `.env`
+file is read even when the environment variable is unset, so the file alone is
+enough. The same key drives both MCP Solver and the underlying engine.
+
+**`mcp-solver: problem file not found: <path>`**
+The path passed to `--problem` does not exist. Check the spelling and that you
+are running from the repo root (the shipped problems live under
+`tests/problems/<solver>/`).
+
+**Wrong Python version.**
+v4 needs Python 3.13 or 3.14. Check the checkout's environment with
+`.venv/bin/python --version`. If it shows 3.15 (for example after an explicit
+`uv venv --python 3.15`), recreate it with `uv venv --python 3.14`.
+
+For kernel-server details and the bundled model aliases, see the
+[agentic-python-coder README](https://github.com/szeider/agentic-python-coder);
+for the agent loop itself, see [minion/README.md](minion/README.md).

agentic_mcp_solver-4.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Stefan Szeider
+
+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.