mcp-minion 0.1.0__tar.gz

mcp_minion-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+# Run logs written inside run folders by the agent
+run_*.json
+
+# Tool caches
+.ruff_cache/
+.pytest_cache/
+
+# Local env / secrets
+.env

mcp_minion-0.1.0/LICENSE

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

mcp_minion-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: mcp-minion
+Version: 0.1.0
+Summary: A minimal ReAct agent over MCP servers via OpenRouter
+Author-email: Stefan Szeider <stefan@szeider.net>
+License: MIT
+License-File: LICENSE
+Requires-Python: <3.14,>=3.13
+Requires-Dist: mcp>=1.25.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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 is used to run solver templates over code-execution MCP
+servers, but it has no dependency on the solver and works with any MCP server.
+
+## Install
+
+From the monorepo (workspace member):
+
+```bash
+uv sync --package mcp-minion
+```
+
+Or standalone:
+
+```bash
+pip install -e minion
+```
+
+Set an OpenRouter API key, either in `~/.mcp-minion` or in a run folder's `.env`:
+
+```
+OPENROUTER_API_KEY=sk-...
+```
+
+## Run-folder config
+
+A run folder holds everything for a single run:
+
+| File | Required | Purpose |
+| --- | --- | --- |
+| `config.json` | yes | Model, agent, MCP server, and kernel settings |
+| `task.md` | yes | The specific task for this run |
+| `project.md` | no | Shared instructions prepended to the task |
+| `files.system` target | no | System-prompt body (see below) |
+| `run_*.json` | auto | Per-run JSON log (written automatically) |
+
+`config.json` (nested format):
+
+```json
+{
+  "model": {
+    "name": "google/gemini-2.5-flash",
+    "temperature": 0,
+    "max_tokens": 2048
+  },
+  "agent": { "max_steps": 10 },
+  "files": { "system": "system.md" },
+  "packages": ["z3-solver"],
+  "mcpServers": {
+    "ipython": { "command": "ipython_mcp", "args": [] }
+  }
+}
+```
+
+Key options:
+
+- **`files.system`** — path (relative to the run folder) to a markdown file
+  whose contents become the system prompt. If the file contains the literal
+  placeholder `{tool_sections}`, the generated per-server tool list is spliced
+  in at that spot (via a literal replace, so other `{`/`}` in the file — e.g.
+  ASP templates — are left untouched); otherwise the tool list is appended
+  after the file contents. When `files.system` is absent, a built-in default
+  system prompt is used.
+- **`packages`** — packages to preinstall in a code-execution kernel. On the
+  first call to a `python_exec` tool, if no `python_reset` has happened yet,
+  `mcp-minion` automatically calls `python_reset` with these packages and
+  reuses any returned `kernel_id` for subsequent `python_exec` calls.
+
+## Examples
+
+### Bundled test server
+
+The package ships a tiny MCP server exposing `echo` and `add`:
+
+```json
+{
+  "model": { "name": "google/gemini-2.5-flash", "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
+```
+
+### IPython code execution
+
+With an [`ipython_mcp`](https://pypi.org/project/ipython-mcp/) server available:
+
+```json
+{
+  "model": { "name": "google/gemini-2.5-flash", "temperature": 0 },
+  "agent": { "max_steps": 5 },
+  "mcpServers": {
+    "ipython": { "command": "ipython_mcp", "args": [] }
+  }
+}
+```
+
+`task.md`:
+
+```
+Use the python_exec tool to compute sum(range(1, 11)) and report the result.
+```
+
+## Artifacts
+
+`mcp_minion.artifacts.extract_last_submission(log_or_steps, tool_name="submit_code")`
+returns the `code` argument of the last *successful* call to a submission tool,
+so callers can persist an agent's final code alongside the run log.
+
+## Tests
+
+```bash
+uv run --with-editable ./minion --with pytest --with pytest-asyncio \
+    python -m pytest minion/tests -q
+```
+
+The end-to-end tests under `minion/e2e_tests/` make real API calls and are
+skipped unless `OPENROUTER_API_KEY` is set.

mcp_minion-0.1.0/README.md

@@ -0,0 +1,133 @@
+# 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 is used to run solver templates over code-execution MCP
+servers, but it has no dependency on the solver and works with any MCP server.
+
+## Install
+
+From the monorepo (workspace member):
+
+```bash
+uv sync --package mcp-minion
+```
+
+Or standalone:
+
+```bash
+pip install -e minion
+```
+
+Set an OpenRouter API key, either in `~/.mcp-minion` or in a run folder's `.env`:
+
+```
+OPENROUTER_API_KEY=sk-...
+```
+
+## Run-folder config
+
+A run folder holds everything for a single run:
+
+| File | Required | Purpose |
+| --- | --- | --- |
+| `config.json` | yes | Model, agent, MCP server, and kernel settings |
+| `task.md` | yes | The specific task for this run |
+| `project.md` | no | Shared instructions prepended to the task |
+| `files.system` target | no | System-prompt body (see below) |
+| `run_*.json` | auto | Per-run JSON log (written automatically) |
+
+`config.json` (nested format):
+
+```json
+{
+  "model": {
+    "name": "google/gemini-2.5-flash",
+    "temperature": 0,
+    "max_tokens": 2048
+  },
+  "agent": { "max_steps": 10 },
+  "files": { "system": "system.md" },
+  "packages": ["z3-solver"],
+  "mcpServers": {
+    "ipython": { "command": "ipython_mcp", "args": [] }
+  }
+}
+```
+
+Key options:
+
+- **`files.system`** — path (relative to the run folder) to a markdown file
+  whose contents become the system prompt. If the file contains the literal
+  placeholder `{tool_sections}`, the generated per-server tool list is spliced
+  in at that spot (via a literal replace, so other `{`/`}` in the file — e.g.
+  ASP templates — are left untouched); otherwise the tool list is appended
+  after the file contents. When `files.system` is absent, a built-in default
+  system prompt is used.
+- **`packages`** — packages to preinstall in a code-execution kernel. On the
+  first call to a `python_exec` tool, if no `python_reset` has happened yet,
+  `mcp-minion` automatically calls `python_reset` with these packages and
+  reuses any returned `kernel_id` for subsequent `python_exec` calls.
+
+## Examples
+
+### Bundled test server
+
+The package ships a tiny MCP server exposing `echo` and `add`:
+
+```json
+{
+  "model": { "name": "google/gemini-2.5-flash", "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
+```
+
+### IPython code execution
+
+With an [`ipython_mcp`](https://pypi.org/project/ipython-mcp/) server available:
+
+```json
+{
+  "model": { "name": "google/gemini-2.5-flash", "temperature": 0 },
+  "agent": { "max_steps": 5 },
+  "mcpServers": {
+    "ipython": { "command": "ipython_mcp", "args": [] }
+  }
+}
+```
+
+`task.md`:
+
+```
+Use the python_exec tool to compute sum(range(1, 11)) and report the result.
+```
+
+## Artifacts
+
+`mcp_minion.artifacts.extract_last_submission(log_or_steps, tool_name="submit_code")`
+returns the `code` argument of the last *successful* call to a submission tool,
+so callers can persist an agent's final code alongside the run log.
+
+## Tests
+
+```bash
+uv run --with-editable ./minion --with pytest --with pytest-asyncio \
+    python -m pytest minion/tests -q
+```
+
+The end-to-end tests under `minion/e2e_tests/` make real API calls and are
+skipped unless `OPENROUTER_API_KEY` is set.

mcp_minion-0.1.0/e2e_tests/runs/mcp_ipython/config.json

@@ -0,0 +1,16 @@
+{
+  "model": {
+    "name": "google/gemini-3.1-flash-lite-preview",
+    "temperature": 0,
+    "max_tokens": 2048
+  },
+  "agent": {
+    "max_steps": 5
+  },
+  "mcpServers": {
+    "ipython": {
+      "command": "ipython_mcp",
+      "args": []
+    }
+  }
+}

mcp_minion-0.1.0/e2e_tests/runs/mcp_ipython/task.md

@@ -0,0 +1 @@
+Use the python_exec tool to compute sum(range(1, 11)) and report the result.

mcp_minion-0.1.0/e2e_tests/runs/multi_step/config.json

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

mcp_minion-0.1.0/e2e_tests/runs/multi_step/task.md

@@ -0,0 +1 @@
+Calculate (8 * 7) + (12 - 5). Show the intermediate results.

mcp_minion-0.1.0/e2e_tests/runs/no_tools/config.json

@@ -0,0 +1,6 @@
+{
+  "modelstring": "google/gemini-3.1-flash-lite-preview",
+  "max_steps": 3,
+  "temperature": 0,
+  "max_tokens": 512
+}

mcp_minion-0.1.0/e2e_tests/runs/no_tools/task.md

@@ -0,0 +1 @@
+What is 2 + 2? Answer directly without using any tools - this is a simple test.

mcp_minion-0.1.0/e2e_tests/runs/simple_add/config.json

@@ -0,0 +1,6 @@
+{
+  "modelstring": "google/gemini-3.1-flash-lite-preview",
+  "max_steps": 5,
+  "temperature": 0,
+  "max_tokens": 1024
+}

mcp_minion-0.1.0/e2e_tests/runs/simple_add/task.md

@@ -0,0 +1 @@
+What is 15 + 27? Use the add tool to calculate this.

mcp_minion-0.1.0/e2e_tests/test_e2e.py

@@ -0,0 +1,174 @@
+"""End-to-end tests using google/gemini-2.5-flash-lite.
+
+These tests make real API calls and require OPENROUTER_API_KEY to be set.
+Run with: uv run pytest e2e_tests/ -v
+"""
+
+import json
+import os
+from pathlib import Path
+
+import pytest
+from dotenv import load_dotenv
+
+from mcp_minion.agent import Agent
+from mcp_minion.cli import load_run_folder
+from mcp_minion.logging import RunLogger
+from mcp_minion.mcp_client import MCPManager
+from mcp_minion.tools import create_default_registry
+
+# Load environment variables
+load_dotenv()
+
+# Skip all tests if no API key
+pytestmark = pytest.mark.skipif(
+    not os.getenv("OPENROUTER_API_KEY"),
+    reason="OPENROUTER_API_KEY not set",
+)
+
+# Path to e2e test run folders
+E2E_RUNS = Path(__file__).parent / "runs"
+
+
+def run_agent_from_folder(folder: Path) -> tuple:
+    """Run agent from a folder and return (result, logger)."""
+    api_key = os.getenv("OPENROUTER_API_KEY")
+    config, mcp_servers, prompt = load_run_folder(folder)
+    logger = RunLogger(log_dir=folder)
+    tools = create_default_registry()
+    if mcp_servers:
+        return _run_with_mcp(api_key, config, mcp_servers, prompt, tools, logger)
+    agent = Agent(api_key=api_key, tools=tools, config=config, logger=logger)
+    result = agent.run(prompt)
+    return result, logger
+
+
+async def _run_with_mcp_async(api_key, config, mcp_servers, prompt, tools, logger):
+    """Run agent with MCP servers."""
+    mcp_manager = MCPManager(mcp_servers)
+    async with mcp_manager:
+        agent = Agent(
+            api_key=api_key,
+            tools=tools,
+            config=config,
+            logger=logger,
+            mcp_manager=mcp_manager,
+        )
+        result = await agent.run_async(prompt)
+    return result, logger
+
+
+def _run_with_mcp(api_key, config, mcp_servers, prompt, tools, logger):
+    """Sync wrapper for MCP agent run."""
+    import asyncio
+
+    return asyncio.run(
+        _run_with_mcp_async(api_key, config, mcp_servers, prompt, tools, logger)
+    )
+
+
+class TestSimpleAdd:
+    """Test simple addition using the add tool."""
+
+    def test_simple_add(self) -> None:
+        folder = E2E_RUNS / "simple_add"
+        result, logger = run_agent_from_folder(folder)
+
+        # Check that the answer contains 42 (15 + 27)
+        assert "42" in result.answer
+
+        # Check that at least one tool call was made
+        assert result.tool_calls_made >= 1
+
+        # Verify log file was created and is valid
+        log_data = json.loads(logger.log_path.read_text())
+        assert log_data["status"] == "completed"
+
+
+class TestMultiStep:
+    """Test multi-step calculation requiring multiple tool calls."""
+
+    def test_multi_step_calculation(self) -> None:
+        folder = E2E_RUNS / "multi_step"
+        result, logger = run_agent_from_folder(folder)
+
+        # (8 * 7) + (12 - 5) = 56 + 7 = 63
+        assert "63" in result.answer
+
+        # Should make multiple tool calls
+        assert result.tool_calls_made >= 2
+
+        # Verify log contains multiple steps
+        log_data = json.loads(logger.log_path.read_text())
+        assert log_data["status"] == "completed"
+
+        # Count total tool calls in log
+        total_tool_calls = sum(
+            len(step.get("tool_calls", [])) for step in log_data["steps"]
+        )
+        assert total_tool_calls >= 2
+
+
+class TestNoTools:
+    """Test question that model can answer directly without tools."""
+
+    def test_no_tools_needed(self) -> None:
+        folder = E2E_RUNS / "no_tools"
+        result, logger = run_agent_from_folder(folder)
+
+        # Should answer with "4" (or use a tool anyway - both are acceptable)
+        assert "4" in result.answer
+
+        # Verify log
+        log_data = json.loads(logger.log_path.read_text())
+        assert log_data["status"] == "completed"
+
+
+class TestLogIntegrity:
+    """Test that logs are complete and well-formed."""
+
+    def test_log_has_all_fields(self) -> None:
+        folder = E2E_RUNS / "simple_add"
+        result, logger = run_agent_from_folder(folder)
+
+        log_data = json.loads(logger.log_path.read_text())
+
+        # Check required top-level fields
+        assert "run_id" in log_data
+        assert "started_at" in log_data
+        assert "completed_at" in log_data
+        assert "status" in log_data
+        assert "config" in log_data
+        assert "prompt" in log_data
+        assert "steps" in log_data
+        assert "result" in log_data
+
+        # Check config was logged
+        assert "model" in log_data["config"]
+        assert "max_steps" in log_data["config"]
+
+        # Check prompt was logged
+        assert len(log_data["prompt"]) > 0
+
+        # Check steps have required fields
+        for step in log_data["steps"]:
+            assert "step" in step
+            assert "started_at" in step
+
+
+class TestMCPIPython:
+    """Test MCP integration with the IPython code execution server."""
+
+    def test_ipython_code_execution(self) -> None:
+        folder = E2E_RUNS / "mcp_ipython"
+        result, logger = run_agent_from_folder(folder)
+
+        # sum(range(1, 11)) = 55
+        assert "55" in result.answer
+
+        # Should have made at least one tool call
+        assert result.tool_calls_made >= 1
+
+        # Verify log
+        log_data = json.loads(logger.log_path.read_text())
+        assert log_data["status"] == "completed"

mcp_minion-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-minion"
+version = "0.1.0"
+description = "A minimal ReAct agent over MCP servers via OpenRouter"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Stefan Szeider", email = "stefan@szeider.net" },
+]
+requires-python = ">=3.13,<3.14"
+dependencies = [
+    "openai>=1.0.0",
+    "python-dotenv>=1.0.0",
+    "mcp>=1.25.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+]
+
+[project.scripts]
+mcp-minion = "mcp_minion.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_minion"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py313"
+line-length = 88
+fix = true
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "F",   # Pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "SIM", # flake8-simplify
+    "RUF", # Ruff-specific rules
+]
+ignore = [
+    "E501", # line length (formatter handles this)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S101"]
+"e2e_tests/*" = ["S101"]
+"__init__.py" = ["F401"]

mcp_minion-0.1.0/src/mcp_minion/__init__.py

@@ -0,0 +1,29 @@
+"""mcp-minion: a minimal ReAct agent over MCP servers via OpenRouter."""
+
+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.logging import RunLogger
+from mcp_minion.mcp_client import MCPManager, MCPResourceInfo, MCPToolInfo
+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.1.0"
+
+__all__ = [
+    "Agent",
+    "AgentConfig",
+    "AgentResult",
+    "MCPManager",
+    "MCPResourceInfo",
+    "MCPToolInfo",
+    "RunLogger",
+    "Tool",
+    "ToolRegistry",
+    "__version__",
+    "create_default_registry",
+    "extract_last_submission",
+]