modern-python-guidance 0.1.0__tar.gz → 0.1.1__tar.gz

{modern_python_guidance-0.1.0 → modern_python_guidance-0.1.1}/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.1] — 2026-05-25
+
+### Added
+
+- Built-in MCP server (`mpg mcp`) exposing all 4 commands as tools over JSON-RPC 2.0 stdio transport — zero additional dependencies
+- Setup: `claude mcp add mpg -- mpg mcp` for Claude Code, or add to `.mcp.json` manually
+- 4 MCP tools: `search_guides`, `retrieve_guides`, `list_guides`, `detect_python_version`
+- CWD confinement for `detect_python_version` (rejects absolute paths, traversal, symlink escape)
+- Resilient message parsing: malformed messages are skipped instead of crashing the server
+- JSON-RPC 2.0 notification compliance (no response for messages without `id`)
+- 19 subprocess-based integration tests for MCP server
+
 ## [0.1.0] — 2026-05-24
 
 Initial release.
@@ -18,4 +30,5 @@ Initial release.
 - Strict YAML-subset frontmatter parser (no PyYAML dependency)
 - GitHub Actions CI (pytest + ruff on Python 3.11, 3.12, 3.13)
 
+[0.1.1]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.1.1
 [0.1.0]: https://github.com/yottayoshida/modern-python-guidance/releases/tag/v0.1.0

{modern_python_guidance-0.1.0 → modern_python_guidance-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modern-python-guidance
-Version: 0.1.0
+Version: 0.1.1
 Summary: Version-aware BAD/GOOD pattern guides that help AI coding agents generate modern Python
 Project-URL: Homepage, https://github.com/yottayoshida/modern-python-guidance
 Project-URL: Repository, https://github.com/yottayoshida/modern-python-guidance
@@ -110,6 +110,40 @@ mpg list --python-version 3.9
 # Excludes: TaskGroup (3.11+), match/case (3.10+), etc.
 ```
 
+## MCP server
+
+mpg includes a built-in [MCP](https://modelcontextprotocol.io) server that exposes all 4 commands as tools. AI agents (Claude Code, Cursor, Gemini CLI, etc.) can discover and call them directly.
+
+### Setup with Claude Code
+
+```bash
+claude mcp add mpg -- mpg mcp
+```
+
+Or add to `.mcp.json` manually:
+
+```json
+{
+  "mcpServers": {
+    "mpg": {
+      "command": "mpg",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+### Available tools
+
+| Tool | Description |
+|------|-------------|
+| `search_guides` | Search guides by keyword with fuzzy matching |
+| `retrieve_guides` | Get full BAD/GOOD content by guide ID |
+| `list_guides` | Browse all guides, filter by category/version |
+| `detect_python_version` | Auto-detect project Python version |
+
+The MCP server uses stdio transport (JSON-RPC 2.0) and adds zero additional dependencies.
+
 ## Agent Skills integration
 
 This project doubles as a [Claude Code Agent Skills](https://docs.anthropic.com/en/docs/claude-code) plugin. Install it into your project's `.claude/skills/` to give Claude automatic access to modern Python patterns when writing or reviewing code.
@@ -139,7 +173,8 @@ ruff check src/ tests/
 
 ```
 src/modern_python_guidance/
-├── cli.py              # Entry point (search, retrieve, list, detect-version)
+├── cli.py              # Entry point (search, retrieve, list, detect-version, mcp)
+├── mcp_server.py       # MCP server (JSON-RPC 2.0 over stdio)
 ├── frontmatter.py      # YAML-subset parser (no PyYAML dependency)
 ├── guide_index.py      # Guide discovery and indexing
 ├── search.py           # Weighted keyword search + fuzzy fallback

{modern_python_guidance-0.1.0 → modern_python_guidance-0.1.1}/README.md

@@ -81,6 +81,40 @@ mpg list --python-version 3.9
 # Excludes: TaskGroup (3.11+), match/case (3.10+), etc.
 ```
 
+## MCP server
+
+mpg includes a built-in [MCP](https://modelcontextprotocol.io) server that exposes all 4 commands as tools. AI agents (Claude Code, Cursor, Gemini CLI, etc.) can discover and call them directly.
+
+### Setup with Claude Code
+
+```bash
+claude mcp add mpg -- mpg mcp
+```
+
+Or add to `.mcp.json` manually:
+
+```json
+{
+  "mcpServers": {
+    "mpg": {
+      "command": "mpg",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+### Available tools
+
+| Tool | Description |
+|------|-------------|
+| `search_guides` | Search guides by keyword with fuzzy matching |
+| `retrieve_guides` | Get full BAD/GOOD content by guide ID |
+| `list_guides` | Browse all guides, filter by category/version |
+| `detect_python_version` | Auto-detect project Python version |
+
+The MCP server uses stdio transport (JSON-RPC 2.0) and adds zero additional dependencies.
+
 ## Agent Skills integration
 
 This project doubles as a [Claude Code Agent Skills](https://docs.anthropic.com/en/docs/claude-code) plugin. Install it into your project's `.claude/skills/` to give Claude automatic access to modern Python patterns when writing or reviewing code.
@@ -110,7 +144,8 @@ ruff check src/ tests/
 
 ```
 src/modern_python_guidance/
-├── cli.py              # Entry point (search, retrieve, list, detect-version)
+├── cli.py              # Entry point (search, retrieve, list, detect-version, mcp)
+├── mcp_server.py       # MCP server (JSON-RPC 2.0 over stdio)
 ├── frontmatter.py      # YAML-subset parser (no PyYAML dependency)
 ├── guide_index.py      # Guide discovery and indexing
 ├── search.py           # Weighted keyword search + fuzzy fallback

{modern_python_guidance-0.1.0 → modern_python_guidance-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "modern-python-guidance"
-version = "0.1.0"
+version = "0.1.1"
 description = "Version-aware BAD/GOOD pattern guides that help AI coding agents generate modern Python"
 readme = "README.md"
 license = "Apache-2.0"

{modern_python_guidance-0.1.0 → modern_python_guidance-0.1.1}/src/modern_python_guidance/__init__.py

@@ -1,3 +1,3 @@
 """Modern Python Guidance — version-aware BAD/GOOD pattern guides for AI coding agents."""
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"

{modern_python_guidance-0.1.0 → modern_python_guidance-0.1.1}/src/modern_python_guidance/cli.py

@@ -62,6 +62,9 @@ def main(argv: list[str] | None = None) -> None:
     p_detect = subparsers.add_parser("detect-version", help="Detect project Python version")
     p_detect.add_argument("--project-dir", type=Path, help="Project directory (default: cwd)")
 
+    # mcp
+    subparsers.add_parser("mcp", help="Start MCP server (JSON-RPC over stdio)")
+
     args = parser.parse_args(argv)
 
     if args.command is None:
@@ -81,6 +84,8 @@ def main(argv: list[str] | None = None) -> None:
             _cmd_list(args)
         elif args.command == "detect-version":
             _cmd_detect_version(args)
+        elif args.command == "mcp":
+            _cmd_mcp()
     except BrokenPipeError:
         sys.exit(0)
 
@@ -200,3 +205,9 @@ def _cmd_list(args: argparse.Namespace) -> None:
 def _cmd_detect_version(args: argparse.Namespace) -> None:
     version = detect_version(project_dir=args.project_dir)
     print(version)
+
+
+def _cmd_mcp() -> None:
+    from modern_python_guidance.mcp_server import serve
+
+    serve()

modern_python_guidance-0.1.1/src/modern_python_guidance/mcp_server.py

@@ -0,0 +1,398 @@
+"""MCP server — JSON-RPC 2.0 over stdio, zero external dependencies."""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from pathlib import Path
+
+from modern_python_guidance import __version__
+from modern_python_guidance.compat import VERSION_RE
+from modern_python_guidance.guide_index import GuideIndex, build_index
+from modern_python_guidance.retrieve import retrieve
+from modern_python_guidance.search import search
+from modern_python_guidance.version_detect import detect_version
+
+log = logging.getLogger(__name__)
+
+_index: GuideIndex | None = None
+
+
+def _get_index() -> GuideIndex:
+    global _index
+    if _index is None:
+        _index = build_index()
+    return _index
+
+
+# --- JSON-RPC framing (Content-Length, LSP-style) ---
+
+
+class _Skip(Exception):
+    """Raised to skip a malformed message without terminating the server."""
+
+
+def _read_message(stream: object = None) -> dict | None:
+    buf = stream or sys.stdin.buffer
+    headers: dict[str, str] = {}
+    while True:
+        line = buf.readline()
+        if not line:
+            return None
+        line_str = line.decode("utf-8", errors="replace").rstrip("\r\n")
+        if line_str == "":
+            break
+        if ":" in line_str:
+            key, _, value = line_str.partition(":")
+            headers[key.strip().lower()] = value.strip()
+
+    raw_length = headers.get("content-length", "0")
+    try:
+        length = int(raw_length)
+    except ValueError as exc:
+        raise _Skip(f"invalid Content-Length: {raw_length!r}") from exc
+    if length == 0:
+        raise _Skip("missing or zero Content-Length")
+    body = buf.read(length)
+    try:
+        return json.loads(body)
+    except json.JSONDecodeError as exc:
+        raise _Skip(f"invalid JSON body: {exc}") from exc
+
+
+def _write_message(msg: dict, stream: object = None) -> None:
+    out = stream or sys.stdout.buffer
+    body = json.dumps(msg, ensure_ascii=False).encode("utf-8")
+    header = f"Content-Length: {len(body)}\r\n\r\n".encode()
+    out.write(header)
+    out.write(body)
+    out.flush()
+
+
+def _error_response(req_id: int | str | None, code: int, message: str) -> dict:
+    return {"jsonrpc": "2.0", "id": req_id, "error": {"code": code, "message": message}}
+
+
+def _result_response(req_id: int | str | None, result: dict) -> dict:
+    return {"jsonrpc": "2.0", "id": req_id, "result": result}
+
+
+def _tool_result(text: str, *, is_error: bool = False) -> dict:
+    result: dict = {"content": [{"type": "text", "text": text}]}
+    if is_error:
+        result["isError"] = True
+    return result
+
+
+# --- Tool schemas ---
+
+TOOLS = [
+    {
+        "name": "search_guides",
+        "description": (
+            "Search modern Python pattern guides by keyword. Returns guide IDs, titles, "
+            "scores, and token estimates. Use this to discover which guides exist before "
+            "retrieving full content. Supports fuzzy matching when exact matches fail."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "Search keywords (e.g. 'typing list', 'pydantic v2', 'httpx')",
+                },
+                "python_version": {
+                    "type": "string",
+                    "description": (
+                        "Filter by Python version (e.g. '3.12'). "
+                        "Only returns guides applicable to this version."
+                    ),
+                    "pattern": r"^\d+\.\d+$",
+                },
+                "category": {
+                    "type": "string",
+                    "description": "Filter by category (e.g. 'stdlib', 'pydantic', 'fastapi')",
+                },
+                "limit": {
+                    "type": "integer",
+                    "description": "Maximum results to return (1-50, default: 10)",
+                    "minimum": 1,
+                    "maximum": 50,
+                    "default": 10,
+                },
+            },
+            "required": ["query"],
+        },
+    },
+    {
+        "name": "retrieve_guides",
+        "description": (
+            "Retrieve full content of one or more guides by ID. Returns the complete "
+            "BAD/GOOD pattern with explanation, version compatibility, and token estimate. "
+            "Call search_guides first to find guide IDs."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "guide_ids": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Guide IDs to retrieve (max 30)",
+                    "maxItems": 30,
+                },
+                "python_version": {
+                    "type": "string",
+                    "description": "Target Python version for compatibility check (e.g. '3.12')",
+                    "pattern": r"^\d+\.\d+$",
+                },
+            },
+            "required": ["guide_ids"],
+        },
+    },
+    {
+        "name": "list_guides",
+        "description": (
+            "List all available guides with metadata. Returns IDs, titles, categories, "
+            "layers, and Python version requirements. Use to browse the full catalog "
+            "or filter by category/version."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "category": {
+                    "type": "string",
+                    "description": "Filter by category (e.g. 'stdlib', 'pydantic')",
+                },
+                "python_version": {
+                    "type": "string",
+                    "description": "Filter by Python version compatibility (e.g. '3.13')",
+                    "pattern": r"^\d+\.\d+$",
+                },
+            },
+        },
+    },
+    {
+        "name": "detect_python_version",
+        "description": (
+            "Detect the target Python version for a project by reading pyproject.toml "
+            "and .python-version. Returns a version string like '3.12'. Use this to "
+            "determine which version to pass to search_guides and retrieve_guides."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "project_dir": {
+                    "type": "string",
+                    "description": (
+                        "Relative path to project directory (relative to server CWD). "
+                        "Defaults to current directory. Absolute paths are rejected."
+                    ),
+                },
+            },
+        },
+    },
+]
+
+
+# --- CWD confinement ---
+
+
+def _confine_path(project_dir_str: str | None) -> Path | str:
+    """Validate project_dir stays within CWD. Returns Path on success, error string on failure."""
+    cwd = Path.cwd()
+    if cwd == Path("/"):
+        return "Cannot detect version: server working directory is root"
+
+    if project_dir_str is None:
+        return cwd
+
+    if Path(project_dir_str).is_absolute():
+        return "project_dir must be a relative path"
+
+    resolved = (cwd / project_dir_str).resolve()
+    try:
+        resolved.relative_to(cwd.resolve())
+    except ValueError:
+        return "project_dir must stay within the server working directory"
+
+    if not resolved.is_dir():
+        return "directory not found"
+
+    return resolved
+
+
+# --- Tool dispatch ---
+
+
+def _handle_tool_call(name: str, arguments: dict) -> dict:
+    try:
+        if name == "search_guides":
+            return _tool_search(arguments)
+        if name == "retrieve_guides":
+            return _tool_retrieve(arguments)
+        if name == "list_guides":
+            return _tool_list(arguments)
+        if name == "detect_python_version":
+            return _tool_detect_version(arguments)
+        return _tool_result(f"Unknown tool: {name}", is_error=True)
+    except Exception:
+        log.exception("Tool execution error")
+        return _tool_result("Internal error during tool execution", is_error=True)
+
+
+def _validate_python_version(pv: str | None) -> str | None:
+    if pv is not None and not VERSION_RE.match(pv):
+        return f"Invalid python_version format: expected N.N (e.g. 3.12), got '{pv}'"
+    return None
+
+
+def _tool_search(arguments: dict) -> dict:
+    query = arguments.get("query", "")
+    if not query:
+        return _tool_result("query is required", is_error=True)
+
+    pv = arguments.get("python_version")
+    err = _validate_python_version(pv)
+    if err:
+        return _tool_result(err, is_error=True)
+
+    limit = max(1, min(50, arguments.get("limit", 10)))
+    category = arguments.get("category")
+
+    index = _get_index()
+    results = search(index, query, python_version=pv, category=category, limit=limit)
+
+    out = [
+        {
+            "id": r.guide_id,
+            "title": r.meta.title,
+            "category": r.meta.category,
+            "layer": r.meta.layer,
+            "score": r.score,
+            "token_estimate": r.token_estimate,
+            "fuzzy": r.fuzzy,
+        }
+        for r in results
+    ]
+    return _tool_result(json.dumps(out, indent=2, ensure_ascii=False))
+
+
+def _tool_retrieve(arguments: dict) -> dict:
+    guide_ids = arguments.get("guide_ids", [])
+    if not guide_ids:
+        return _tool_result("guide_ids is required and must not be empty", is_error=True)
+    if len(guide_ids) > 30:
+        return _tool_result("guide_ids exceeds maximum of 30", is_error=True)
+
+    pv = arguments.get("python_version")
+    err = _validate_python_version(pv)
+    if err:
+        return _tool_result(err, is_error=True)
+
+    index = _get_index()
+    results = retrieve(index, guide_ids, python_version=pv)
+    return _tool_result(json.dumps(results, indent=2, ensure_ascii=False))
+
+
+def _tool_list(arguments: dict) -> dict:
+    pv = arguments.get("python_version")
+    err = _validate_python_version(pv)
+    if err:
+        return _tool_result(err, is_error=True)
+
+    category = arguments.get("category")
+    index = _get_index()
+    metas = index.all_meta()
+
+    if category:
+        metas = [m for m in metas if m.category == category]
+    if pv:
+        from modern_python_guidance.compat import version_compatible
+
+        metas = [m for m in metas if version_compatible(m.python, pv)]
+
+    metas.sort(key=lambda m: (m.layer, m.category, m.id))
+
+    out = [
+        {
+            "id": m.id,
+            "title": m.title,
+            "category": m.category,
+            "layer": m.layer,
+            "python": m.python,
+            "frequency": m.frequency,
+        }
+        for m in metas
+    ]
+    return _tool_result(json.dumps(out, indent=2, ensure_ascii=False))
+
+
+def _tool_detect_version(arguments: dict) -> dict:
+    project_dir_str = arguments.get("project_dir")
+    result = _confine_path(project_dir_str)
+    if isinstance(result, str):
+        return _tool_result(result, is_error=True)
+
+    version = detect_version(project_dir=result)
+    return _tool_result(json.dumps({"python_version": version}))
+
+
+# --- Server main loop ---
+
+PROTOCOL_VERSION = "2024-11-05"
+
+
+def _handle_request(msg: dict) -> dict | None:
+    method = msg.get("method", "")
+    req_id = msg.get("id")
+    params = msg.get("params", {})
+    is_notification = "id" not in msg
+
+    if method == "notifications/initialized":
+        return None
+
+    if method == "initialize":
+        result = _result_response(req_id, {
+            "protocolVersion": PROTOCOL_VERSION,
+            "capabilities": {"tools": {}},
+            "serverInfo": {"name": "modern-python-guidance", "version": __version__},
+        })
+        return None if is_notification else result
+
+    if method == "tools/list":
+        result = _result_response(req_id, {"tools": TOOLS})
+        return None if is_notification else result
+
+    if method == "tools/call":
+        tool_name = params.get("name", "")
+        arguments = params.get("arguments", {})
+        tool_result = _handle_tool_call(tool_name, arguments)
+        result = _result_response(req_id, tool_result)
+        return None if is_notification else result
+
+    if not is_notification:
+        return _error_response(req_id, -32601, f"Method not found: {method}")
+
+    return None
+
+
+def serve(*, stdin: object = None, stdout: object = None) -> None:
+    logging.basicConfig(stream=sys.stderr, level=logging.WARNING, format="%(message)s")
+
+    while True:
+        try:
+            msg = _read_message(stdin)
+        except _Skip as exc:
+            log.warning("Skipping malformed message: %s", exc)
+            continue
+        if msg is None:
+            break
+
+        response = _handle_request(msg)
+        if response is not None:
+            _write_message(response, stdout)
+
+
+if __name__ == "__main__":
+    serve()

{modern_python_guidance-0.1.0 → modern_python_guidance-0.1.1}/tests/test_cli_integration.py

@@ -6,6 +6,8 @@ import json
 import subprocess
 import sys
 
+from modern_python_guidance import __version__
+
 BIN = [sys.executable, "-m", "modern_python_guidance"]
 
 
@@ -146,4 +148,4 @@ class TestVersion:
     def test_version_flag(self):
         r = run_cli("--version")
         assert "modern-python-guidance" in r.stdout
-        assert "0.1.0" in r.stdout
+        assert __version__ in r.stdout

modern_python_guidance-0.1.1/tests/test_mcp_server.py

@@ -0,0 +1,304 @@
+"""MCP server integration tests — subprocess-based stdio communication."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+
+BIN = [sys.executable, "-m", "modern_python_guidance", "mcp"]
+
+
+def _encode_message(msg: dict) -> bytes:
+    body = json.dumps(msg).encode("utf-8")
+    return f"Content-Length: {len(body)}\r\n\r\n".encode() + body
+
+
+def _decode_messages(data: bytes) -> list[dict]:
+    messages = []
+    pos = 0
+    while pos < len(data):
+        header_end = data.find(b"\r\n\r\n", pos)
+        if header_end == -1:
+            break
+        header_block = data[pos:header_end].decode("utf-8")
+        content_length = 0
+        for line in header_block.split("\r\n"):
+            if line.lower().startswith("content-length:"):
+                content_length = int(line.split(":", 1)[1].strip())
+        body_start = header_end + 4
+        body = data[body_start : body_start + content_length]
+        messages.append(json.loads(body))
+        pos = body_start + content_length
+    return messages
+
+
+def _build_session(*requests: dict) -> bytes:
+    return b"".join(_encode_message(r) for r in requests)
+
+
+def _run_mcp(*requests: dict, timeout: int = 10) -> list[dict]:
+    stdin_data = _build_session(*requests)
+    proc = subprocess.run(
+        BIN,
+        input=stdin_data,
+        capture_output=True,
+        timeout=timeout,
+    )
+    assert proc.returncode == 0, f"stderr: {proc.stderr.decode()}"
+    return _decode_messages(proc.stdout)
+
+
+def _init_handshake() -> list[dict]:
+    return [
+        {"jsonrpc": "2.0", "id": 0, "method": "initialize", "params": {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {},
+            "clientInfo": {"name": "test", "version": "0.0.1"},
+        }},
+        {"jsonrpc": "2.0", "method": "notifications/initialized"},
+    ]
+
+
+class TestInitialize:
+    def test_initialize_returns_capabilities(self):
+        responses = _run_mcp(*_init_handshake())
+        assert len(responses) == 1
+        result = responses[0]["result"]
+        assert result["protocolVersion"] == "2024-11-05"
+        assert "tools" in result["capabilities"]
+        assert result["serverInfo"]["name"] == "modern-python-guidance"
+
+
+class TestToolsList:
+    def test_lists_four_tools(self):
+        responses = _run_mcp(
+            *_init_handshake(),
+            {"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}},
+        )
+        tools_response = responses[1]
+        tools = tools_response["result"]["tools"]
+        names = {t["name"] for t in tools}
+        expected = {"search_guides", "retrieve_guides", "list_guides", "detect_python_version"}
+        assert names == expected
+
+    def test_schemas_have_required_fields(self):
+        responses = _run_mcp(
+            *_init_handshake(),
+            {"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}},
+        )
+        tools = responses[1]["result"]["tools"]
+        for tool in tools:
+            assert "name" in tool
+            assert "description" in tool
+            assert "inputSchema" in tool
+            assert tool["inputSchema"]["type"] == "object"
+
+
+class TestSearchGuides:
+    def test_search_returns_results(self):
+        responses = _run_mcp(
+            *_init_handshake(),
+            {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {
+                "name": "search_guides",
+                "arguments": {"query": "typing list"},
+            }},
+        )
+        result = responses[1]["result"]
+        assert "isError" not in result
+        data = json.loads(result["content"][0]["text"])
+        assert isinstance(data, list)
+        assert len(data) >= 1
+
+    def test_search_empty_query(self):
+        responses = _run_mcp(
+            *_init_handshake(),
+            {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {
+                "name": "search_guides",
+                "arguments": {"query": ""},
+            }},
+        )
+        result = responses[1]["result"]
+        assert result["isError"] is True
+
+    def test_search_with_version_filter(self):
+        responses = _run_mcp(
+            *_init_handshake(),
+            {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {
+                "name": "search_guides",
+                "arguments": {"query": "typing", "python_version": "3.12"},
+            }},
+        )
+        result = responses[1]["result"]
+        assert "isError" not in result
+
+    def test_search_invalid_version_format(self):
+        responses = _run_mcp(
+            *_init_handshake(),
+            {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {
+                "name": "search_guides",
+                "arguments": {"query": "typing", "python_version": "invalid"},
+            }},
+        )
+        result = responses[1]["result"]
+        assert result["isError"] is True
+
+    def test_search_limit_clamped(self):
+        responses = _run_mcp(
+            *_init_handshake(),
+            {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {
+                "name": "search_guides",
+                "arguments": {"query": "typing", "limit": 100},
+            }},
+        )
+        result = responses[1]["result"]
+        assert "isError" not in result
+        data = json.loads(result["content"][0]["text"])
+        assert len(data) <= 50
+
+
+class TestRetrieveGuides:
+    def test_retrieve_single_guide(self):
+        responses = _run_mcp(
+            *_init_handshake(),
+            {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {
+                "name": "retrieve_guides",
+                "arguments": {"guide_ids": ["use-builtin-generics"]},
+            }},
+        )
+        result = responses[1]["result"]
+        assert "isError" not in result
+        data = json.loads(result["content"][0]["text"])
+        assert len(data) == 1
+        assert data[0]["id"] == "use-builtin-generics"
+
+    def test_retrieve_empty_ids(self):
+        responses = _run_mcp(
+            *_init_handshake(),
+            {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {
+                "name": "retrieve_guides",
+                "arguments": {"guide_ids": []},
+            }},
+        )
+        result = responses[1]["result"]
+        assert result["isError"] is True
+
+    def test_retrieve_nonexistent_id(self):
+        responses = _run_mcp(
+            *_init_handshake(),
+            {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {
+                "name": "retrieve_guides",
+                "arguments": {"guide_ids": ["nonexistent-guide-xyz"]},
+            }},
+        )
+        result = responses[1]["result"]
+        assert "isError" not in result
+        data = json.loads(result["content"][0]["text"])
+        assert data == []
+
+
+class TestListGuides:
+    def test_list_all_guides(self):
+        responses = _run_mcp(
+            *_init_handshake(),
+            {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {
+                "name": "list_guides",
+                "arguments": {},
+            }},
+        )
+        result = responses[1]["result"]
+        assert "isError" not in result
+        data = json.loads(result["content"][0]["text"])
+        assert isinstance(data, list)
+        assert len(data) >= 1
+
+    def test_list_with_category_filter(self):
+        responses = _run_mcp(
+            *_init_handshake(),
+            {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {
+                "name": "list_guides",
+                "arguments": {"category": "stdlib"},
+            }},
+        )
+        result = responses[1]["result"]
+        data = json.loads(result["content"][0]["text"])
+        for guide in data:
+            assert guide["category"] == "stdlib"
+
+
+class TestDetectPythonVersion:
+    def test_detect_version_default(self):
+        responses = _run_mcp(
+            *_init_handshake(),
+            {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {
+                "name": "detect_python_version",
+                "arguments": {},
+            }},
+        )
+        result = responses[1]["result"]
+        assert "isError" not in result
+        data = json.loads(result["content"][0]["text"])
+        assert "python_version" in data
+
+    def test_detect_version_rejects_absolute_path(self):
+        responses = _run_mcp(
+            *_init_handshake(),
+            {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {
+                "name": "detect_python_version",
+                "arguments": {"project_dir": "/etc"},
+            }},
+        )
+        result = responses[1]["result"]
+        assert result["isError"] is True
+        assert "/etc" not in result["content"][0]["text"]
+
+    def test_detect_version_rejects_traversal(self):
+        responses = _run_mcp(
+            *_init_handshake(),
+            {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {
+                "name": "detect_python_version",
+                "arguments": {"project_dir": "../../.."},
+            }},
+        )
+        result = responses[1]["result"]
+        assert result["isError"] is True
+
+
+class TestProtocol:
+    def test_unknown_method_returns_error(self):
+        responses = _run_mcp(
+            *_init_handshake(),
+            {"jsonrpc": "2.0", "id": 1, "method": "unknown/method", "params": {}},
+        )
+        error = responses[1].get("error")
+        assert error is not None
+        assert error["code"] == -32601
+
+    def test_unknown_tool_returns_tool_error(self):
+        responses = _run_mcp(
+            *_init_handshake(),
+            {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {
+                "name": "nonexistent_tool",
+                "arguments": {},
+            }},
+        )
+        result = responses[1]["result"]
+        assert result["isError"] is True
+
+
+class TestStdoutPollution:
+    def test_no_non_jsonrpc_output(self):
+        stdin_data = _build_session(
+            *_init_handshake(),
+            {"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}},
+        )
+        proc = subprocess.run(BIN, input=stdin_data, capture_output=True, timeout=10)
+        decoded = _decode_messages(proc.stdout)
+        total_expected_bytes = sum(
+            len(f"Content-Length: {len(json.dumps(m).encode())}\r\n\r\n".encode())
+            + len(json.dumps(m).encode())
+            for m in decoded
+        )
+        assert len(proc.stdout) == total_expected_bytes, (
+            f"stdout contains {len(proc.stdout) - total_expected_bytes} extra bytes"
+        )