agentic-mcp-solver 4.2.0__tar.gz → 4.3.0__tar.gz

{agentic_mcp_solver-4.2.0 → agentic_mcp_solver-4.3.0}/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+### [4.3.0] - 2026-11-14
+
+- **Behavior Change:** Requires the MCP Python SDK 2.x (`mcp>=2,<3`; 1.x is no
+  longer supported), agentic-python-coder 3.5.0 and mcp-minion 0.3.0.
+- **Behavior Change:** `mcp-solver` caps a run at 2,000,000 total (input +
+  output) tokens by default, checked after each step; `--token-limit N`
+  changes the cap (`0` = no limit). A run stopped by the cap without an
+  accepted submission exits with code 3; the stats JSON reports
+  `token_limit_reached` and `token_limit`. `mcp-solver-bench --token-limit`
+  passes the value to each solve.
+- **Behavior Change:** New exit code 4: the agent stopped early with an error
+  (for example an LLM API failure) after an accepted submission. That
+  submission is saved and re-executed, and exit 4 replaces 0 when it runs
+  cleanly, since it may not be the agent's final, verified program. Such an
+  error before any accepted submission, a failed kernel setup, or an
+  exception during the solve exits with 1 and a one-line message instead of
+  a traceback.
+- **Behavior Change:** The engine, its kernels and the CLI's re-execution of
+  the submitted program (in `mcp-solver` and `mcp-solver-serve`) get a
+  filtered environment: the mcp library's default whitelist (`PATH`, `HOME`,
+  ...), locale, temp-dir, proxy, CA-bundle and native-build variables, and
+  variables starting with `UV_`, `CODER_`, `MCP_SOLVER_`, `XDG_` or `LC_`
+  unless the name contains `KEY`, `TOKEN`, `SECRET`, `PASSWORD` or
+  `CREDENTIAL` (`UV_ENV_FILE` is dropped too). Other variables no longer
+  reach the kernel. This keeps API keys out of model-written code; it is
+  hygiene, not a sandbox.
+- **Behavior Change:** `submit_code` on the toolkit server returns an MCP
+  error result (`isError`) carrying the engine's reason for a rejected
+  program, instead of a normal result with `{"ok": false, ...}`.
+- **New Feature:** `--model` accepts a model config file
+  (`--model my_model.json`) in the engine's format, and aliases resolve
+  through the engine's `load_model_config`, so a local `<alias>.json`
+  overrides a bundled one. A model config may set `base_url` and
+  `api_key_env` (another OpenAI-compatible endpoint and the variable that
+  holds its key). Its `reasoning`, `provider`, `top_k` and `request_timeout`
+  settings are now sent; before they were dropped.
+- **Behavior Change:** `mcp-solver-runfolder --model` resolves aliases and
+  model files like the CLI. A full OpenRouter ID gets no sampling settings
+  (it used to get `temperature 0` and `max_tokens 8192`), a model with
+  `base_url` or `api_key_env` is rejected, and the generated config sets
+  `agent.max_tool_result_chars` to at least twice the backend template's
+  length (minimum 64,000).
+- **Improvement:** `mcp-solver-bench` runs each solve with its own run
+  directory as working directory (path arguments made absolute), saves the
+  solve's stderr to `cli_stderr.txt` there, and copies its last 20 lines
+  into the result row (`stderr_tail`) of a failed or invalid run.
+- **Improvement:** The CLI and the toolkit server check that the engine
+  offers all five tools they use (`python_exec`, `python_reset`,
+  `python_status`, `python_interrupt`, `submit_code`) and name the missing
+  ones together with the required engine version.
+- **Fix:** The pysat and maxsat kernels install `python-sat[pb]` instead of
+  `python-sat` and `pypblib`. The `[pb]` extra installs pindakaas, without
+  which every `pysat.pb.PBEnc` encoding call raises.
+- **Fix:** In dev mode, newly started kernels pick up edits to the helper
+  sources (the uv build cache is keyed on `src/**/*.py`, not only on
+  `pyproject.toml`).
+
 ### [4.2.0] - 2026-11-13
 
 - **Major Change:** Published on PyPI as `agentic-mcp-solver`, since the name

{agentic_mcp_solver-4.2.0 → agentic_mcp_solver-4.3.0}/INSTALL.md

@@ -186,11 +186,10 @@ 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 ipython_mcp engine lacks the tools ...`** (CLI and server)
+Your installed `agentic-python-coder` is older than 3.5.0, 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 pip install "agentic-python-coder>=3.5.0"` (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

{agentic_mcp_solver-4.2.0 → agentic_mcp_solver-4.3.0}/PKG-INFO

@@ -1,23 +1,23 @@
 Metadata-Version: 2.5
 Name: agentic-mcp-solver
-Version: 4.2.0
+Version: 4.3.0
 Summary: LLM-driven constraint solving (SAT, MaxSAT, SMT, CP, ASP) on top of agentic-python-coder
 Author-email: Stefan Szeider <stefan@szeider.net>
 License: MIT
 License-File: LICENSE
 Requires-Python: <3.15,>=3.13
 Provides-Extra: agent
-Requires-Dist: agentic-python-coder>=3.4.4; extra == 'agent'
-Requires-Dist: mcp-minion>=0.2.2; extra == 'agent'
-Requires-Dist: mcp<3,>=1.25; extra == 'agent'
+Requires-Dist: agentic-python-coder>=3.5.0; extra == 'agent'
+Requires-Dist: mcp-minion>=0.3.0; extra == 'agent'
+Requires-Dist: mcp<3,>=2; extra == 'agent'
 Requires-Dist: python-dotenv>=1.0.0; extra == 'agent'
 Provides-Extra: all
-Requires-Dist: agentic-python-coder>=3.4.4; extra == 'all'
+Requires-Dist: agentic-python-coder>=3.5.0; extra == 'all'
 Requires-Dist: clingo>=5.8.0; extra == 'all'
 Requires-Dist: cpmpy>=0.9.24; extra == 'all'
 Requires-Dist: didppy<0.12,>=0.11.1; extra == 'all'
-Requires-Dist: mcp-minion>=0.2.2; extra == 'all'
-Requires-Dist: mcp<3,>=1.25; extra == 'all'
+Requires-Dist: mcp-minion>=0.3.0; extra == 'all'
+Requires-Dist: mcp<3,>=2; extra == 'all'
 Requires-Dist: pytest-asyncio>=0.26; extra == 'all'
 Requires-Dist: pytest>=8.3.5; extra == 'all'
 Requires-Dist: python-dotenv>=1.0.0; extra == 'all'

agentic_mcp_solver-4.3.0/minion/CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+Changes to the `mcp-minion` package. The monorepo's root `CHANGELOG.md`
+tracks `mcp-solver` releases, which version independently of this package.
+
+### [0.3.0] - 2026-11-14
+
+- **Behavior Change:** `MCPManager.call_tool` returns a `ToolOutcome`
+  (`text`, `is_error`, `links`) instead of a JSON string `{"result": ...}` or
+  `{"error": ...}`. An MCP `isError` result and client-side failures (unknown
+  tool, non-object arguments, server not connected, timeout, transport
+  error) come back with `is_error` set; nothing is raised for them.
+  `Tool.execute` returns a `ToolOutcome` too (a string return value is the
+  text, other values are JSON-encoded). The model sees the text, prefixed
+  with `ERROR: ` for an error outcome.
+- **Behavior Change:** Step records (`AgentResult.steps` and the run log)
+  hold each tool call as `{"name", "arguments", "result", "is_error"}`, where
+  `result` is the plain tool text, no longer a JSON envelope. Steps carry
+  `reasoning_details` or `reasoning` when the model returns them, and a step
+  cut off at `max_tokens` carries `truncated: true`. The run log also
+  records `system_prompt` and `kernel_setup`. `extract_last_submission`
+  reads the new records and run logs of 0.2.x.
+- **Behavior Change:** An LLM API failure no longer raises out of
+  `run_async`. The run ends with `AgentResult.error` set (one line with the
+  exception type), the steps and token totals so far, and the answer
+  `[Agent stopped: LLM call failed: ...]`; the CLI then exits with 1. Error
+  responses the SDK parses without raising (HTTP 200 with an error body,
+  `finish_reason: "error"`, malformed or non-JSON bodies) are retried 3
+  times, after 5, 10 and 15 seconds, before the run ends this way.
+- **Behavior Change:** The flat `config.json` format (`modelstring`,
+  top-level `max_steps`, `temperature`, ...) is no longer read; a flat
+  config or any unknown top-level key is an error. New keys in the nested
+  format: `model.reasoning`, `model.provider`, `model.top_k` and
+  `model.extra_body` (sent in the request body), `model.request_timeout`,
+  `agent.max_tool_result_chars`, and `cwd` for an MCP server.
+- **Behavior Change:** Requires the MCP Python SDK 2.x (`mcp>=2,<3`); 1.x
+  is no longer supported.
+- **Behavior Change:** A server's `env` in `mcpServers` is merged over the
+  mcp library's default environment whitelist (`PATH`, `HOME`, ...) instead
+  of over the full parent environment, so other variables (API keys, for
+  instance) reach the server only when listed. A server without `env` gets
+  the whitelist, as before.
+- **Behavior Change:** Tool results longer than
+  `agent.max_tool_result_chars` (default 64,000; `0` disables the cut) reach
+  the model as head and tail around a marker line; step records and the run
+  log keep the full text.
+- **Behavior Change:** With `packages` configured and a server offering
+  `python_reset`, the kernel is set up with those packages at the start of
+  the run, before the first LLM call (previously before the first
+  `python_exec`), and a failed setup ends the run with `AgentResult.error`.
+  The tracked `kernel_id` is added to every kernel tool call that lacks one
+  (`python_exec`, `python_reset`, `python_status`, `python_interrupt`), so a
+  `python_reset` from the model restarts the same kernel; a model reset
+  with its own `packages` list keeps the configured packages.
+- **Behavior Change:** The `reasoning_details` (or `reasoning`) of each
+  assistant message are replayed unmodified in the conversation history, as
+  OpenRouter requires for reasoning models.
+- **Behavior Change:** The agent calls the API through `AsyncOpenAI`, with
+  one client created per run and closed when the run ends, so one `Agent`
+  can run several times and LLM calls no longer block the event loop. A
+  client set on `agent.client` is used for every run and not closed; it
+  must provide an async `chat.completions.create`. The
+  `Agent.SYSTEM_PROMPT_BASE` class attribute is gone; use the module-level
+  `SYSTEM_PROMPT_BASE`.
+- **Behavior Change:** The CLI offers its arithmetic demo tools only when
+  no MCP server is configured.
+- **New Feature:** Server instructions from the MCP `initialize` result
+  appear in the system prompt. Image, audio and blob content renders as a
+  one-line note (type, MIME type, size) instead of base64 or an object repr.
+- **New Feature:** `mcp_minion.find_api_key()` looks the key up in the
+  environment, a run folder's `.env`, extra dotenv files and
+  `~/.mcp-minion`, without loading the files into `os.environ`; the CLI uses
+  it.
+- **Fix:** A rejected `submit_code` call (`{"ok": false, ...}`) is no longer
+  taken as the last submission. A reply cut off at `max_tokens` without
+  tool calls is no longer accepted as the final answer; the model is asked
+  to continue. Missing or empty tool arguments count as `{}`, arguments
+  that are not a JSON object give an error result, and the history echoes
+  valid JSON arguments back to the API.
+
+### [0.2.2] - 2026-11-13
+
+- **New Feature:** Supports the MCP Python SDK 2.x alongside 1.x
+  (`mcp>=1.25.0,<3`): paginated listing through `PaginatedRequestParams`,
+  protocol fields read under both the 2.x snake_case and the 1.x camelCase
+  names, and `read_resource` called with a plain string URI.
+- **Behavior Change:** Requires Python 3.13 or 3.14 (`>=3.13,<3.15`).
+
+### [0.2.1] - 2026-08-04
+
+- **Fix:** Pin `mcp>=1.25.0,<2`. The `mcp` 2.0.0 SDK changed the client API
+  (`ClientSession.list_tools` no longer takes `cursor`), so fresh installs of
+  0.1.0 and 0.2.0 failed to connect to any MCP server. The workspace lockfile
+  masked this by resolving `mcp` 1.28.1.
+
+### [0.2.0] - 2026-08-04
+
+- **New Feature:** Per-run token cap, `agent.max_total_tokens` in
+  `config.json` (absent or `0` = unlimited). The cumulative input+output
+  tokens are checked after each completed step; once they exceed the cap the
+  loop stops, the answer becomes `[Agent stopped: per-run token cap of N
+  exceeded (cumulative M)]`, and the run log records `token_cap_reached`
+  (on the last step and in the result). `max_steps` alone does not bound
+  spending, since one step can be arbitrarily expensive.
+- **Behavior Change:** A configured MCP server that fails to start now aborts
+  the run with a `RuntimeError` naming the server and the underlying error,
+  after closing any servers already started. Previously the failure was a
+  warning on stderr and the agent continued with a reduced tool set, which
+  produced plausible-looking but unusable runs.

agentic_mcp_solver-4.3.0/minion/README.md

@@ -0,0 +1,136 @@
+# mcp-minion
+
+A minimal ReAct agent that drives one or more [MCP](https://modelcontextprotocol.io)
+servers through an OpenAI-compatible API (OpenRouter by default). It reads a
+task from a *run folder*, loops "think → call tool → observe" until the model
+produces a final answer, and writes a complete JSON log of the run.
+
+`mcp-minion` is developed in the [mcp-solver](https://github.com/szeider/mcp-solver)
+monorepo, where it runs solver templates over code-execution MCP servers, but
+it has no dependency on the solver and works with any MCP server. It requires
+Python 3.13 or 3.14 and the MCP Python SDK 2.x.
+
+## Install
+
+```bash
+uv tool install mcp-minion          # the mcp-minion command
+uv add mcp-minion                   # as a library in a uv project
+uv sync --package mcp-minion        # inside the monorepo (workspace member)
+```
+
+The OpenRouter API key is looked up in this order: the `OPENROUTER_API_KEY`
+environment variable, the run folder's `.env`, then `~/.mcp-minion`
+(`OPENROUTER_API_KEY=sk-...`). The files are read, not loaded into the process
+environment; `mcp_minion.find_api_key()` does the same lookup for library users.
+
+## Run folder
+
+| File | Purpose |
+| --- | --- |
+| `config.json` | Model, agent, MCP server and kernel settings (required) |
+| `task.md` | The task for this run (required) |
+| `project.md` | Shared instructions prepended to the task (optional) |
+| `files.system` target | System-prompt body (optional, see below) |
+| `run_*.json` | Per-run JSON log, including the system prompt sent (written automatically) |
+| `submission.py` | Code of the last accepted `submit_code` call, if any |
+| `server.log` | stderr of the MCP servers and their children |
+
+`config.json` uses the nested format; the pre-0.3 flat format
+(`modelstring`, top-level `max_steps`, ...) is rejected with an error:
+
+```json
+{
+  "model": {
+    "name": "google/gemini-3.1-flash-lite-preview",
+    "temperature": 0,
+    "max_tokens": 2048,
+    "reasoning": { "effort": "low" },
+    "request_timeout": 120
+  },
+  "agent": { "max_steps": 10, "max_total_tokens": 500000 },
+  "files": { "system": "system.md" },
+  "packages": ["z3-solver"],
+  "mcpServers": {
+    "ipython": { "command": "ipython_mcp", "args": [], "env": {}, "cwd": "." }
+  }
+}
+```
+
+- **`model.*`** — `name` is the OpenRouter model id. `reasoning`, `provider`,
+  `top_k` and the entries of an optional `extra_body` object go into the
+  request body (`AgentConfig.extra_body`; OpenRouter usage accounting stays
+  on). `request_timeout` is the per-request timeout in seconds. Every other
+  key (`temperature`, `max_tokens`, ...) is passed to the API call as is.
+- **`agent.max_total_tokens`** — cap on the cumulative input+output tokens of
+  a run, checked after each step; the run then stops with
+  `[Agent stopped: per-run token cap of N exceeded (cumulative M)]` and the
+  log records `token_cap_reached`. Absent or `0` means no cap.
+- **`agent.max_tool_result_chars`** — tool results longer than this are cut
+  for the model (see Tool results); default 64000, `0` disables.
+- **`files.system`** — markdown file (relative to the run folder) used as the
+  system prompt. A literal `{tool_sections}` placeholder is replaced by the
+  generated tool list (other braces are left alone); without it the list is
+  appended. Absent: a built-in default prompt.
+- **`mcpServers`** — servers to start, each with `command` and optional
+  `args`, `env` (merged by the mcp library over its default environment
+  whitelist) and `cwd`. A server that fails to start aborts the run. Each
+  server's `instructions` from its initialize result appear in the system
+  prompt under that server's heading. Without any server, the CLI offers four
+  arithmetic demo tools (`add`, `subtract`, `multiply`, `divide`).
+- **`packages`** — for the kernel server
+  [`ipython_mcp`](https://pypi.org/project/agentic-python-coder/) (PyPI
+  package `agentic-python-coder`): before the first LLM call, `mcp-minion`
+  calls `python_reset` with these packages; if that fails the run ends with an
+  error. The returned `kernel_id` is added to every `python_exec`,
+  `python_reset`, `python_status` and `python_interrupt` call that lacks one,
+  so a `python_reset` by the model restarts the same kernel with its packages.
+  If the model's `python_reset` passes its own `packages` list, the configured
+  packages are sent first, followed by the model's entries they do not already
+  cover (same distribution name, ignoring extras, versions and case).
+
+## Tool results
+
+`MCPManager.call_tool` returns a `ToolOutcome(text, is_error, links)`. The
+model sees `text` unchanged (prefixed with `ERROR: ` for errors), cut to
+`agent.max_tool_result_chars` in config.json (`AgentConfig.max_tool_result_chars`,
+default 64000; head and tail kept, `0` disables); the step records and the run log keep the full text as
+`"result"` plus `"is_error"`. Images, audio and blobs appear as one line such
+as `[image mime=image/png bytes=1234]`. A `resource_link` appears as a
+`[resource_link] URI (name)` line; the built-in `read_resource` tool fetches
+it, or any resource a server announced, from its origin server only.
+Reasoning that the model returns (`reasoning_details`, or a plain
+`reasoning` string) is passed back unmodified on the next request and kept in
+the step records and log.
+
+`mcp_minion.extract_last_submission(log_or_steps, tool_name="submit_code")`
+returns the `code` argument of the last accepted submission: one without
+`is_error` whose text is not a JSON object with `"ok": false`. Run logs of
+mcp-minion 0.2 and earlier are read too.
+
+## Example
+
+The package ships a small MCP test server (`echo`, `add`, a resource and
+instructions):
+
+```json
+{
+  "model": { "name": "google/gemini-3.1-flash-lite-preview", "temperature": 0 },
+  "agent": { "max_steps": 5 },
+  "mcpServers": {
+    "test": { "command": "python", "args": ["-m", "mcp_minion.test_mcp_server"] }
+  }
+}
+```
+
+```bash
+mcp-minion path/to/run_folder -v
+```
+
+## Tests
+
+```bash
+cd minion && uv run pytest -q
+```
+
+The end-to-end tests under `minion/e2e_tests/` make real API calls and are
+skipped unless `OPENROUTER_API_KEY` is set.

agentic_mcp_solver-4.3.0/minion/e2e_tests/runs/multi_step/config.json

@@ -0,0 +1,10 @@
+{
+  "model": {
+    "name": "google/gemini-3.1-flash-lite-preview",
+    "temperature": 0,
+    "max_tokens": 2048
+  },
+  "agent": {
+    "max_steps": 10
+  }
+}

agentic_mcp_solver-4.3.0/minion/e2e_tests/runs/no_tools/config.json

@@ -0,0 +1,10 @@
+{
+  "model": {
+    "name": "google/gemini-3.1-flash-lite-preview",
+    "temperature": 0,
+    "max_tokens": 512
+  },
+  "agent": {
+    "max_steps": 3
+  }
+}

agentic_mcp_solver-4.3.0/minion/e2e_tests/runs/simple_add/config.json

@@ -0,0 +1,10 @@
+{
+  "model": {
+    "name": "google/gemini-3.1-flash-lite-preview",
+    "temperature": 0,
+    "max_tokens": 1024
+  },
+  "agent": {
+    "max_steps": 5
+  }
+}

{agentic_mcp_solver-4.2.0 → agentic_mcp_solver-4.3.0}/minion/e2e_tests/test_e2e.py

@@ -129,7 +129,7 @@ class TestLogIntegrity:
 
     def test_log_has_all_fields(self) -> None:
         folder = E2E_RUNS / "simple_add"
-        result, logger = run_agent_from_folder(folder)
+        _result, logger = run_agent_from_folder(folder)
 
         log_data = json.loads(logger.log_path.read_text())
 

{agentic_mcp_solver-4.2.0 → agentic_mcp_solver-4.3.0}/minion/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mcp-minion"
-version = "0.2.2"
+version = "0.3.0"
 description = "A minimal ReAct agent over MCP servers via OpenRouter"
 readme = "README.md"
 license = { text = "MIT" }
@@ -15,7 +15,7 @@ requires-python = ">=3.13,<3.15"
 dependencies = [
     "openai>=1.0.0",
     "python-dotenv>=1.0.0",
-    "mcp>=1.25.0,<3",
+    "mcp>=2,<3",
 ]
 
 [project.optional-dependencies]

{agentic_mcp_solver-4.2.0 → agentic_mcp_solver-4.3.0}/minion/src/mcp_minion/__init__.py

@@ -4,14 +4,16 @@ from importlib.metadata import PackageNotFoundError, version
 
 from mcp_minion.agent import Agent, AgentConfig, AgentResult
 from mcp_minion.artifacts import extract_last_submission
+from mcp_minion.env import find_api_key
 from mcp_minion.logging import RunLogger
-from mcp_minion.mcp_client import MCPManager, MCPResourceInfo, MCPToolInfo
+from mcp_minion.mcp_client import MCPManager, MCPResourceInfo, MCPToolInfo, ToolOutcome
 from mcp_minion.tools import Tool, ToolRegistry, create_default_registry
 
 try:
     __version__ = version("mcp-minion")
-except PackageNotFoundError:  # pragma: no cover - source checkout without install
-    __version__ = "0.2.1"
+except PackageNotFoundError:  # pragma: no cover - source tree without install
+    # A sentinel, not a release number, so it cannot go stale.
+    __version__ = "0+unknown"
 
 __all__ = [
     "Agent",
@@ -22,8 +24,10 @@ __all__ = [
     "MCPToolInfo",
     "RunLogger",
     "Tool",
+    "ToolOutcome",
     "ToolRegistry",
     "__version__",
     "create_default_registry",
     "extract_last_submission",
+    "find_api_key",
 ]