mcp-tuning

# mcp-tuning A **script-first** MCP debugging/testing library for Jupyter notebooks and plain Python scripts. It is designed to help you iterate on MCP servers (implemented in any language) by providing a small, synchronous client API: - Connect via `stdio` (subprocess), `http`, or `sse` - Explore: tools / resources / prompts - Call tools with JSON arguments - Save/replay input-only cases (tool + args) - Export logs / history / last result as JSON for repeatable debugging Start with `examples/notebooks/01_mcp_inspector_demo.ipynb`. ## Requirements - Python 3.12+ - `uv` ## Install (uv) ```powershell uv sync uv sync --extra notebook --extra test ``` ## Run (Jupyter) ```powershell uv run jupyter lab ``` ## Quickstart (stdio) Prefer argv lists for `stdio` servers (avoids shell quoting issues) and make sure the server runs in an environment that has its dependencies installed. ```python from mcp_tuning import connect_stdio # Example 1: connect to the built-in mock server (minimal dependencies) import sys c = connect_stdio([sys.executable, "src/mcp_tuning/_mock_server.py"]) print(c.server_info()) print([t.name for t in c.tools()]) print(c.call("add", {"a": 1, "b": 2}).result) c.close() ``` Connect to the FastMCP example server (requires `mcp` installed in the interpreter that runs the server): ```python from mcp_tuning import connect_stdio c = connect_stdio([".venv/Scripts/python.exe", "examples/servers/simple_stdio_server.py"]) print([t.name for t in c.tools()]) print(c.call("add", {"a": 1, "b": 2}).result) c.close() ``` ## Public API Reference The public API is intentionally small and exported at the top-level `mcp_tuning` package. ### Connect functions - `connect_stdio(command, *, cwd=None, env=None) -> Client` - `command`: `list[str]` (recommended) or `str` - defaults to running the subprocess with the repo root as `cwd` (more reliable in notebooks) - `connect_http(rpc_url, *, headers=None) -> Client` - `connect_sse(*, sse_url, rpc_url, head…