mcpmedic 0.1.0__tar.gz

mcpmedic-0.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.5
+Name: mcpmedic
+Version: 0.1.0
+Summary: One command, every MCP audit - session hygiene, wire shapes, name collisions. Zero dependencies.
+Author: ZidoCode
+License: MIT
+Keywords: agent,audit,doctor,jsonrpc,llm,mcp,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# mcp-doctor
+
+**One command, every MCP audit — session hygiene, wire shapes, name collisions.**
+
+[![PyPI](https://img.shields.io/pypi/v/mcpmedic?cacheSeconds=300)](https://pypi.org/project/mcpmedic/)
+[![CI](https://github.com/ZidoCode/mcp-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/ZidoCode/mcp-doctor/actions)
+
+MCP integrations break in three places and none of them crash:
+
+| Where | What breaks | Auditor |
+|---|---|---|
+| **Recorded session** | dangling tool_call_id poisons later requests ([opencode #44852](https://github.com/anomalyco/opencode/issues/44852)), swallowed `isError` ([zeroclaw #7122](https://github.com/zeroclaw-labs/zeroclaw/pull/7122)), error-channel confusion ([memoria #258](https://github.com/matrixorigin/memoria/issues/258)) | `session` — [mcp-session-audit](https://github.com/ZidoCode/mcp-session-audit) |
+| **Advertised listings** | schemas that make strict clients silently reject tools ([gitlab-mcp #286](https://github.com/zereight/gitlab-mcp/issues/286), [langfuse #13804](https://github.com/langfuse/langfuse/issues/13804), [strapi #27395](https://github.com/strapi/strapi/issues/27395)) | `schema` — [mcp-schema-audit](https://github.com/ZidoCode/mcp-schema-audit) |
+| **Tool names** | collision between servers makes the agent call the wrong tool ([VSCode #324992](https://github.com/microsoft/vscode/issues/324992), Copilot #11480) | `collide` — [mcp-collision](https://github.com/ZidoCode/mcp-collision) |
+
+## Install
+
+```
+pip install mcpmedic
+```
+
+## Usage
+
+```
+mcp-doctor check recording.jsonl                  # session + schema, one pass
+mcp-doctor session recording.jsonl                # session hygiene only
+mcp-doctor schema recording.jsonl                 # wire-shape conformance only
+mcp-doctor collide --client claude                # name collisions across installed servers
+```
+
+Input: JSONL of recorded MCP messages — a CI log, a debug dump, a user-reported
+session file. No live server needed.
+
+```jsonl
+{"direction":"request","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25"}}
+{"direction":"response","id":1,"result":{"protocolVersion":"2025-11-25","serverInfo":{"name":"srv","version":"1.0"}}}
+{"direction":"response","id":2,"result":{"tools":[{"name":"search","inputSchema":{"type":"object","properties":{}}}]}}
+```
+
+Exit codes (CI-friendly): **0** clean · **1** warnings · **2** critical.
+
+## Member auditors
+
+- [mcp-session-audit](https://github.com/ZidoCode/mcp-session-audit) — dangling calls, orphan/duplicate responses, isError swallowed, error-as-text, unknown tools
+- [mcp-schema-audit](https://github.com/ZidoCode/mcp-schema-audit) — empty schemas, root type violations, draft-07 tuples, duplicate names, protocol version sanity
+- [mcp-collision](https://github.com/ZidoCode/mcp-collision) — predicts tool-name collisions before your agent does
+
+MIT License.

mcpmedic-0.1.0/README.md

@@ -0,0 +1,48 @@
+# mcp-doctor
+
+**One command, every MCP audit — session hygiene, wire shapes, name collisions.**
+
+[![PyPI](https://img.shields.io/pypi/v/mcpmedic?cacheSeconds=300)](https://pypi.org/project/mcpmedic/)
+[![CI](https://github.com/ZidoCode/mcp-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/ZidoCode/mcp-doctor/actions)
+
+MCP integrations break in three places and none of them crash:
+
+| Where | What breaks | Auditor |
+|---|---|---|
+| **Recorded session** | dangling tool_call_id poisons later requests ([opencode #44852](https://github.com/anomalyco/opencode/issues/44852)), swallowed `isError` ([zeroclaw #7122](https://github.com/zeroclaw-labs/zeroclaw/pull/7122)), error-channel confusion ([memoria #258](https://github.com/matrixorigin/memoria/issues/258)) | `session` — [mcp-session-audit](https://github.com/ZidoCode/mcp-session-audit) |
+| **Advertised listings** | schemas that make strict clients silently reject tools ([gitlab-mcp #286](https://github.com/zereight/gitlab-mcp/issues/286), [langfuse #13804](https://github.com/langfuse/langfuse/issues/13804), [strapi #27395](https://github.com/strapi/strapi/issues/27395)) | `schema` — [mcp-schema-audit](https://github.com/ZidoCode/mcp-schema-audit) |
+| **Tool names** | collision between servers makes the agent call the wrong tool ([VSCode #324992](https://github.com/microsoft/vscode/issues/324992), Copilot #11480) | `collide` — [mcp-collision](https://github.com/ZidoCode/mcp-collision) |
+
+## Install
+
+```
+pip install mcpmedic
+```
+
+## Usage
+
+```
+mcp-doctor check recording.jsonl                  # session + schema, one pass
+mcp-doctor session recording.jsonl                # session hygiene only
+mcp-doctor schema recording.jsonl                 # wire-shape conformance only
+mcp-doctor collide --client claude                # name collisions across installed servers
+```
+
+Input: JSONL of recorded MCP messages — a CI log, a debug dump, a user-reported
+session file. No live server needed.
+
+```jsonl
+{"direction":"request","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25"}}
+{"direction":"response","id":1,"result":{"protocolVersion":"2025-11-25","serverInfo":{"name":"srv","version":"1.0"}}}
+{"direction":"response","id":2,"result":{"tools":[{"name":"search","inputSchema":{"type":"object","properties":{}}}]}}
+```
+
+Exit codes (CI-friendly): **0** clean · **1** warnings · **2** critical.
+
+## Member auditors
+
+- [mcp-session-audit](https://github.com/ZidoCode/mcp-session-audit) — dangling calls, orphan/duplicate responses, isError swallowed, error-as-text, unknown tools
+- [mcp-schema-audit](https://github.com/ZidoCode/mcp-schema-audit) — empty schemas, root type violations, draft-07 tuples, duplicate names, protocol version sanity
+- [mcp-collision](https://github.com/ZidoCode/mcp-collision) — predicts tool-name collisions before your agent does
+
+MIT License.

mcpmedic-0.1.0/ci.yml

@@ -0,0 +1,11 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: pip install pytest && pytest -q

mcpmedic-0.1.0/mcp_collision.py

@@ -0,0 +1,225 @@
+#!/usr/bin/env python3
+"""mcp-collision — predict MCP tool name collisions before your client does.
+
+Multiple MCP servers installed side-by-side can expose tools with the same
+name. Clients react differently: some prefix (server__tool), some silently
+drop, some shadow. The collision is invisible until your agent calls the
+wrong tool (VSCode #324992, CopilotKit #2409, PraisonAI #2711 — and the
+shadowing bug class behind Hermes #72032).
+
+mcp-collision reads your client's MCP config, talks to each server over
+stdio MCP (initialize -> tools/list), collects every tool name, and reports
+exactly which calls would be ambiguous — per sanitization scheme.
+
+Usage:
+  python3 mcp_collision.py scan <config.json> [--client claude|cursor|cline|raw]
+  python3 mcp_collision.py check <tools1.json> <tools2.json> [...]   # pre-dumped lists
+
+Config format: any JSON with a "mcpServers" object (Claude Desktop,
+Cursor .mcp.json, Cline, etc.), stdio servers only (command-based).
+
+Zero dependencies. Python 3.8+.
+"""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+
+
+# ---------------------------------------------------------------- sanitize
+
+def sanitize(client, server, tool):
+    """How a client names a tool from server S with tool name T."""
+    if client == "raw":
+        return tool
+    sep = "__" if client in ("claude", "cline") else "-"
+    name = f"{server}{sep}{tool}"
+    if client == "claude":
+        # Claude Code sanitizes invalid chars per Hermes #72032 class of bugs:
+        # chars outside [a-zA-Z0-9_-] collapse to _, so different raw names
+        # can collapse to the same sanitized name.
+        name = re.sub(r"[^a-zA-Z0-9_-]", "_", name)
+    return name
+
+
+# ---------------------------------------------------------------- mcp stdio
+
+def list_tools(command, cwd=None, env_extra=None, timeout=20):
+    """Spawn an MCP stdio server, initialize, return its tools/list.
+    Returns (tools, error). tools = list of {name, description}."""
+    env = dict(os.environ)
+    if env_extra:
+        env.update(env_extra)
+    try:
+        proc = subprocess.Popen(command, stdout=subprocess.PIPE, stdin=subprocess.PIPE,
+                                stderr=subprocess.DEVNULL, cwd=cwd, env=env, text=True)
+    except OSError as e:
+        return None, f"cannot spawn {command[0]!r}: {e}"
+
+    def send(obj):
+        proc.stdin.write(json.dumps(obj) + "\n")
+        proc.stdin.flush()
+
+    def recv():
+        line = proc.stdout.readline()
+        if not line:
+            return None
+        try:
+            return json.loads(line)
+        except json.JSONDecodeError:
+            return None
+
+    try:
+        send({"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {},
+            "clientInfo": {"name": "mcp-collision", "version": "0.1"}}})
+        resp = recv()
+        if not resp or "result" not in (resp or {}):
+            return None, f"no initialize response ({(resp or {}).get('error', {}).get('message', 'timeout/invalid')})"
+        send({"jsonrpc": "2.0", "method": "notifications/initialized"})
+        send({"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}})
+        # tolerate notifications between response frames
+        for _ in range(10):
+            resp = recv()
+            if resp is None:
+                break
+            if resp.get("id") == 2:
+                break
+        if not resp or resp.get("id") != 2:
+            return None, "no tools/list response"
+        tools = resp["result"].get("tools") or []
+        return tools, None
+    finally:
+        try:
+            proc.stdin.close()
+            proc.wait(timeout=5)
+        except Exception:
+            proc.kill()
+
+
+def load_config(path):
+    """Load an MCP config file, return {server_name: {command: [...], env: {}}}."""
+    with open(path, "r", encoding="utf-8") as f:
+        text = f.read()
+    # tolerate JSONC: strip // and /* */ comments, trailing commas
+    text = re.sub(r"//[^\n]*", "", text)
+    text = re.sub(r"/\*.*?\*/", "", text, flags=re.S)
+    text = re.sub(r",(\s*[}\]])", r"\1", text)
+    cfg = json.loads(text)
+    servers = cfg.get("mcpServers") or cfg.get("mcp_servers") or {}
+    if not isinstance(servers, dict):
+        raise ValueError("mcpServers is not an object")
+    return servers
+
+
+# ---------------------------------------------------------------- analysis
+
+def analyze(tool_map, client):
+    """tool_map: {server: [tool names]}. Returns (collisions, sanitized_names).
+    collisions: {final_name: [server, tool, ...]} with len > 1."""
+    sanitized = {}   # final name -> [(server, raw_tool)]
+    for server, tools in tool_map.items():
+        for t in tools:
+            final = sanitize(client, server, t)
+            sanitized.setdefault(final, []).append((server, t))
+    collisions = {k: v for k, v in sanitized.items() if len(v) > 1}
+    return collisions, sanitized
+
+
+# ---------------------------------------------------------------- CLI
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="mcp-collision",
+                                 description="Predict MCP tool name collisions before your client does.")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p_scan = sub.add_parser("scan", help="scan an MCP config file (live servers)")
+    p_scan.add_argument("config")
+    p_scan.add_argument("--client", default="claude",
+                        choices=["claude", "cursor", "cline", "raw"])
+    p_scan.add_argument("--timeout", type=int, default=20)
+    p_scan.add_argument("--json", action="store_true", help="machine-readable output")
+
+    p_check = sub.add_parser("check", help="check pre-dumped tool name lists")
+    p_check.add_argument("files", nargs="+")
+    p_check.add_argument("--client", default="claude",
+                         choices=["claude", "cursor", "cline", "raw"])
+    p_check.add_argument("--json", action="store_true", help="machine-readable output")
+
+    args = ap.parse_args(argv)
+    args.timeout = max(1, getattr(args, "timeout", 20))
+
+    if args.cmd == "check":
+        tool_map = {}
+        for f in args.files:
+            name = os.path.splitext(os.path.basename(f))[0]
+            with open(f, "r", encoding="utf-8") as fh:
+                data = json.load(fh)
+            tools = data if isinstance(data, list) else data.get("tools", [])
+            tool_map[name] = [t if isinstance(t, str) else t.get("name", "?") for t in tools]
+        return _report(tool_map, args.client, args.json)
+
+    # scan
+    try:
+        servers = load_config(args.config)
+    except OSError as e:
+        print(f"error: cannot read config {args.config}: {e}", file=sys.stderr)
+        return 2
+    except (json.JSONDecodeError, ValueError) as e:
+        print(f"error: invalid config {args.config}: {e}", file=sys.stderr)
+        return 2
+    if not servers:
+        print("no mcpServers found in config")
+        return 0
+
+    tool_map = {}
+    failures = []
+    for name, spec in servers.items():
+        cmd = spec.get("command")
+        if not cmd:
+            failures.append((name, "not a stdio server (no command) — remote servers skipped"))
+            continue
+        command = [cmd] + (spec.get("args") or [])
+        tools, err = list_tools(command, env_extra=spec.get("env"), timeout=args.timeout)
+        if err:
+            failures.append((name, err))
+        else:
+            tool_map[name] = [t.get("name", "?") for t in tools]
+
+    rc = _report(tool_map, args.client, args.json)
+    for name, err in failures:
+        print(f"  skipped {name}: {err}", file=sys.stderr)
+    return rc
+
+
+def _report(tool_map, client, as_json):
+    total = sum(len(v) for v in tool_map.values())
+    collisions, _ = analyze(tool_map, client)
+    if as_json:
+        print(json.dumps({
+            "client": client, "servers": {k: len(v) for k, v in tool_map.items()},
+            "total_tools": total, "collisions": {k: v for k, v in collisions.items()},
+        }, indent=2))
+    else:
+        print(f"client: {client} — {len(tool_map)} servers, {total} tools")
+        for s in sorted(tool_map):
+            print(f"  {s:24s} {len(tool_map[s]):>3} tools")
+        if not collisions:
+            print("\nno collisions detected")
+            return 0
+        print(f"\n{len(collisions)} COLLISION(S):")
+        for final in sorted(collisions):
+            print(f"  {final}")
+            for server, tool in collisions[final]:
+                print(f"    <- {server}: {tool}")
+        print("\nthese calls are ambiguous — your client picks one, you may never know which.")
+    return 2 if collisions else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mcpmedic-0.1.0/mcp_doctor.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+"""mcp-doctor — one command, every MCP audit.
+
+MCP integrations break in three places and none of them crash: the recorded
+session (dangling tool calls, swallowed isError, error-channel confusion),
+the advertised listings (schemas that make strict clients silently reject
+tools), and the tool names themselves (collision between servers that makes
+an agent call the wrong tool). Each of those has a dedicated auditor; this
+is the one door that runs them.
+
+Subcommands:
+  doctor session <recording.jsonl>       session hygiene audit
+  doctor schema  <recording.jsonl>       wire-shape conformance audit
+  doctor collide --client <claude|cursor|cline|raw> [--timeout N]
+                                         tool-name collision scan
+  doctor check   <recording.jsonl>       session + schema in one pass
+
+Each subcommand inherits its module's exit codes (0 clean / 1 warnings /
+2 critical) so CI can gate on any of them.
+"""
+
+import argparse
+import json
+import sys
+
+import mcp_session_audit
+import mcp_schema_audit
+
+VERSION = "0.1.0"
+
+
+def _load_jsonl(path):
+    with open(path, "r", encoding="utf-8", errors="replace") as f:
+        return [ln for ln in (l.strip() for l in f) if ln]
+
+
+def cmd_session(args):
+    return mcp_session_audit.report(args.recording,
+                                    mcp_session_audit.audit(_load_jsonl(args.recording)))
+
+
+def cmd_schema(args):
+    return mcp_schema_audit.report(args.recording,
+                                   mcp_schema_audit.audit(_load_jsonl(args.recording)))
+
+
+def cmd_check(args):
+    """Session + schema on the same recording, one combined report."""
+    lines = _load_jsonl(args.recording)
+    s_findings = mcp_session_audit.audit(list(lines))
+    sch_findings = mcp_schema_audit.audit(list(lines))
+    combined = s_findings + sch_findings
+    print(f"mcp-doctor check: {args.recording} (session + schema)")
+    if not combined:
+        print("  ALL CLEAR — session hygiene and wire shapes are both client-safe.")
+        return 0
+    for sev, code, msg in combined:
+        sym = {"CRITICAL": "[CRITICAL]", "WARNING": "[WARNING ]", "INFO": "[INFO    ]"}[sev]
+        print(f"  {sym} [{code}] {msg}")
+    counts = {"CRITICAL": 0, "WARNING": 0, "INFO": 0}
+    for sev, _, _ in combined:
+        counts[sev] += 1
+    parts = [f"{counts[s]} {s.lower()}" for s in ("CRITICAL", "WARNING", "INFO") if counts[s]]
+    print(f"\n  verdict: {', '.join(parts)}.")
+    if counts["CRITICAL"]:
+        print("  the session or listing will fail in a way the model or client cannot see.")
+        return 2
+    return 1
+
+
+def cmd_collide(args):
+    import mcp_collision
+    argv = ["--client", args.client]
+    if args.timeout:
+        argv += ["--timeout", str(args.timeout)]
+    return mcp_collision.main(argv)
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    ap = argparse.ArgumentParser(
+        prog="mcp-doctor",
+        description="One command, every MCP audit — session hygiene, wire shapes, name collisions.")
+    ap.add_argument("--version", action="version", version=f"mcp-doctor {VERSION}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("session", help="session hygiene audit (dangling calls, swallowed isError)")
+    s.add_argument("recording")
+    s.set_defaults(fn=cmd_session)
+
+    s = sub.add_parser("schema", help="wire-shape conformance audit (client-rejecting schemas)")
+    s.add_argument("recording")
+    s.set_defaults(fn=cmd_schema)
+
+    s = sub.add_parser("check", help="session + schema combined, one pass")
+    s.add_argument("recording")
+    s.set_defaults(fn=cmd_check)
+
+    s = sub.add_parser("collide", help="tool-name collision scan across installed servers")
+    s.add_argument("--client", default="claude", choices=["claude", "cursor", "cline", "raw"])
+    s.add_argument("--timeout", type=int, default=20)
+    s.set_defaults(fn=cmd_collide)
+
+    args = ap.parse_args(argv)
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mcpmedic-0.1.0/mcp_schema_audit.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""mcp-schema-audit — audit recorded MCP listings for client-rejecting wire shapes.
+
+MCP servers publish broken tool listings in ways that are invisible on the
+server side: the endpoint returns 200, no log fires, and the failure happens
+entirely in the client's validation — tools get silently dropped (langfuse
+#13804), the whole tool list is rejected (gitlab-mcp #286, strapi #27395), or
+a dropped schema is replaced with {} and the model has to reverse-engineer
+arguments one failed call at a time (prime-agent #1073). Quality linters
+(mcp-schema-lint, mcp-assert) grade descriptions and naming; none of them
+check the shapes that make strict clients REJECT tools outright.
+
+This tool does. Input: JSONL of recorded MCP messages (same format as
+mcp-session-audit):
+
+  {"direction":"request","id":1,"method":"initialize","params":{...}}
+  {"direction":"response","id":1,"result":{"protocolVersion":"2025-11-25",...}}
+  {"direction":"response","id":2,"result":{"tools":[...]}}
+
+Checks:
+  1. inputSchema missing or {}            — clients reject or drop the tool
+  2. inputSchema.type missing/not "object" — TS SDK rejects (langfuse #13804)
+  3. draft-07 dialect + tuple items:[...]  — strict 2020-12 clients reject
+                                            everything (strapi #27395)
+  4. duplicate tool names
+  5. protocolVersion echoed / negotiated that is not a known MCP revision
+     (go-sdk #1033 echoed 2026-07-28 through the legacy handshake)
+  6. initialize result missing serverInfo name/version
+  7. empty listing — a tools/list result with zero tools
+
+Exit codes: 0 clean, 1 warnings only, 2 any CRITICAL.
+"""
+
+import json
+import sys
+
+CRITICAL = "CRITICAL"
+WARNING = "WARNING"
+INFO = "INFO"
+
+# known MCP protocol revisions (legacy era + modern era)
+KNOWN_VERSIONS = {
+    "2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25",
+    "2026-03-01", "2026-07-28",
+}
+DRAFT07 = "http://json-schema.org/draft-07/schema"
+
+
+def _schema_findings(where, schema, findings):
+    """Validate one tool schema dict for rejection-blocking shapes."""
+    if schema is None:
+        findings.append((CRITICAL, "schema-missing",
+                         f"{where}: inputSchema missing — clients cannot construct "
+                         "arguments; many drop the tool (gitlab-mcp #286)"))
+        return
+    if not isinstance(schema, dict):
+        findings.append((WARNING, "schema-not-object",
+                         f"{where}: inputSchema is {type(schema).__name__}, not an object"))
+        return
+    if not schema:
+        findings.append((CRITICAL, "schema-empty",
+                         f"{where}: inputSchema is {{}} — violates the MCP schema spec; "
+                         "strict clients reject the tool (gitlab-mcp #286, prime-agent #1073)"))
+        return
+    if schema.get("type") != "object":
+        findings.append((CRITICAL, "root-type-not-object",
+                         f"{where}: inputSchema.type is {schema.get('type')!r}, expected "
+                         "'object' — MCP TS SDK rejects the tool (langfuse #13804)"))
+    dialect = schema.get("$schema")
+    if isinstance(dialect, str) and "draft-07" in dialect:
+        # structural draft-07: tuple syntax items:[...] (invalid in 2020-12)
+        def _tuples(node, path="$"):
+            hits = []
+            if isinstance(node, dict):
+                if isinstance(node.get("items"), list):
+                    hits.append(path + ".items")
+                for k, v in node.items():
+                    hits.extend(_tuples(v, f"{path}.{k}"))
+            elif isinstance(node, list):
+                for i, v in enumerate(node):
+                    hits.extend(_tuples(v, f"{path}[{i}]"))
+            return hits
+        tuples = _tuples(schema)
+        if tuples:
+            findings.append((CRITICAL, "draft07-dialect",
+                             f"{where}: advertises draft-07 with tuple syntax "
+                             f"({tuples[0]}) — strict 2020-12 clients reject the tool "
+                             "(strapi #27395, TS SDK #2084)"))
+        else:
+            findings.append((WARNING, "draft07-dialect",
+                             f"{where}: advertises draft-07 — SEP-1613 default is "
+                             "2020-12; strict validators may reject"))
+
+
+def audit(lines):
+    """Audit parsed JSONL lines. Returns list of (severity, code, msg)."""
+    findings = []
+    requested_versions = []  # protocolVersion the client asked for
+    server_version = None
+    server_info = None
+    tool_lists = 0
+    saw_init = False
+    total_tools = 0
+    names = {}
+
+    for n, line in enumerate(lines, 1):
+        if isinstance(line, str):
+            try:
+                line = json.loads(line)
+            except (json.JSONDecodeError, ValueError):
+                findings.append((WARNING, "unparseable-line", f"line {n}: not valid JSON"))
+                continue
+        if not isinstance(line, dict):
+            findings.append((WARNING, "unparseable-line", f"line {n}: not an object"))
+            continue
+
+        method = line.get("method")
+        result = line.get("result")
+        params = line.get("params")
+
+        # client's requested version
+        if method == "initialize" and isinstance(params, dict):
+            rv = params.get("protocolVersion")
+            if rv:
+                requested_versions.append(rv)
+
+        if not isinstance(result, dict):
+            continue
+
+        # initialize result
+        if "serverInfo" in result or "protocolVersion" in result:
+            saw_init = True
+            server_version = result.get("protocolVersion")
+            server_info = result.get("serverInfo")
+            if server_version is not None and str(server_version) not in KNOWN_VERSIONS:
+                findings.append((CRITICAL, "unknown-protocol-version",
+                                 f"line {n}: server negotiated {server_version!r} — not a "
+                                 "known MCP revision; clients will fail to bind session "
+                                 "semantics (go-sdk #1033 echoed a modern era version "
+                                 "through the legacy handshake)"))
+            if requested_versions and server_version is not None:
+                if str(requested_versions[-1]) != str(server_version):
+                    findings.append((INFO, "version-renegotiated",
+                                     f"line {n}: client requested "
+                                     f"{requested_versions[-1]!r}, server answered "
+                                     f"{server_version!r} — legal (MUST respond with a "
+                                     "supported version) but worth confirming intent "
+                                     "(ferrum-edge #2168 hard-errored instead)"))
+
+        # tools/list result
+        tools = result.get("tools")
+        if isinstance(tools, list):
+            tool_lists += 1
+            total_tools += len(tools)
+            if not tools:
+                findings.append((WARNING, "empty-tools",
+                                 f"line {n}: tools/list returned zero tools — server "
+                                 "exposes nothing; most UIs show a dead connector"))
+            for t in tools:
+                if not isinstance(t, dict):
+                    continue
+                name = t.get("name")
+                if not isinstance(name, str) or not name:
+                    findings.append((CRITICAL, "tool-unnamed",
+                                     f"line {n}: tool without a name — uncallable"))
+                    continue
+                if name in names:
+                    findings.append((CRITICAL, "duplicate-tool",
+                                     f"line {n}: duplicate tool name '{name}' (first seen "
+                                     f"line {names[name]}) — only one can be called"))
+                names[name] = n
+                _schema_findings(f"tool '{name}' (line {n})", t.get("inputSchema"),
+                                 findings)
+
+    if saw_init and (not isinstance(server_info, dict) or not server_info.get("name")):
+        findings.append((WARNING, "serverinfo-unnamed",
+                         "initialize result has no serverInfo.name — shows up as a "
+                         "blank connector in logs and UIs"))
+    if not saw_init and (tool_lists or requested_versions):
+        findings.append((WARNING, "no-initialize",
+                         "no initialize result in the recording — can't audit "
+                         "negotiation or serverInfo"))
+
+    return findings
+
+
+SEV_SYM = {CRITICAL: "[CRITICAL]", WARNING: "[WARNING ]", INFO: "[INFO    ]"}
+
+
+def report(path, findings):
+    counts = {CRITICAL: 0, WARNING: 0, INFO: 0}
+    for sev, _, _ in findings:
+        counts[sev] += 1
+    print(f"mcp-schema-audit: {path}")
+    if not findings:
+        print("  ALL CLEAR — every tool schema is client-acceptable, negotiation is sane.")
+        return 0
+    for sev, code, msg in findings:
+        print(f"  {SEV_SYM[sev]} {msg}")
+    parts = [f"{counts[s]} {s.lower()}" for s in (CRITICAL, WARNING, INFO) if counts[s]]
+    print(f"\n  verdict: {', '.join(parts)}.")
+    if counts[CRITICAL]:
+        print("  strict clients will silently drop these tools or refuse the listing entirely.")
+        return 2
+    return 1
+
+
+def load_lines(path):
+    with open(path, "r", encoding="utf-8", errors="replace") as f:
+        return [ln for ln in (l.strip() for l in f) if ln]
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv or argv[0] in ("-h", "--help"):
+        print(__doc__)
+        return 0
+    return report(argv[0], audit(load_lines(argv[0])))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mcpmedic-0.1.0/mcp_session_audit.py

@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+"""mcp-session-audit — audit a recorded MCP session for protocol hygiene failures.
+
+MCP sessions fail in ways that never surface as crashes: a tool call whose
+result was lost mid-batch poisons every later request with dangling
+tool_call_ids (opencode #44852); an isError:true envelope gets swallowed and
+the model reads the error text as output (zeroclaw #7122, claude-agent-sdk
+#717/#564); an execution failure is delivered as a JSON-RPC error so the
+model never learns why its call failed (memoria #258); a validator clobbers
+isError back to success and inflates the success rate (IBM mcp-context-forge
+#4202). All of these are visible in a recorded transcript — if something
+actually looks.
+
+This tool looks. Input: JSONL where each line is one recorded message:
+  {"direction":"request","id":1,"method":"tools/call","params":{...}}
+  {"direction":"response","id":1,"result":{...}}          # or "error":{...}
+(direction defaults to "response" when a line has a result/error and no
+method; bare JSON-RPC batches and raw client/server logs are tolerated.)
+
+Checks:
+  1. dangling tool call  — a request with an id that never got a response
+  2. orphan response     — a response whose id was never requested
+  3. duplicate response  — two responses for the same id
+  4. isError swallowed   — isError:true with no is_error flag upstream and
+                           content that reads as ordinary output
+  5. error-channel confusion — execution failures delivered as JSON-RPC
+                           errors (model never sees the text), or error text
+                           inside a successful result with no isError flag
+  6. unknown tool        — tools/call for a name absent from a recorded
+                           tools/list result
+
+Exit codes: 0 = clean, 1 = warnings only, 2 = any CRITICAL finding.
+"""
+
+import json
+import sys
+
+CRITICAL = "CRITICAL"
+WARNING = "WARNING"
+INFO = "INFO"
+
+ERROR_CODES = {
+    -32700: "parse error",
+    -32600: "invalid request",
+    -32601: "method not found",
+    -32602: "invalid params",
+    -32603: "internal error",
+}
+
+
+def _err_text(result):
+    """Extract text content from a CallToolResult-shaped result."""
+    parts = []
+    content = result.get("content")
+    if isinstance(content, list):
+        for block in content:
+            if isinstance(block, dict) and isinstance(block.get("text"), str):
+                parts.append(block["text"])
+    return "\n".join(parts)
+
+
+def audit(lines):
+    """Audit a list of parsed JSONL lines. Returns list of (severity, code, msg)."""
+    findings = []
+    requests = {}       # id -> method
+    responded = set()   # ids that have any response
+    error_responded = set()
+    known_tools = None
+    exec_failures_as_rpc = 0
+
+    for n, line in enumerate(lines, 1):
+        if isinstance(line, str):
+            try:
+                line = json.loads(line)
+            except (json.JSONDecodeError, ValueError):
+                findings.append((WARNING, "unparseable-line",
+                                 f"line {n}: not valid JSON, skipped"))
+                continue
+        if not isinstance(line, dict):
+            findings.append((WARNING, "unparseable-line",
+                             f"line {n}: not an object, skipped"))
+            continue
+
+        direction = line.get("direction")
+        rid = line.get("id")
+        method = line.get("method")
+
+        # sniff tools/list response for the known-tool set
+        if direction == "response" or (method is None and "result" in line):
+            result = line.get("result")
+            if isinstance(result, dict) and isinstance(result.get("tools"), list):
+                known_tools = {t.get("name") for t in result["tools"]
+                               if isinstance(t, dict)}
+                if rid is not None and rid not in requests:
+                    requests[rid] = "tools/list"
+            elif isinstance(result, dict) and "serverInfo" in result:
+                if rid is not None and rid not in requests:
+                    requests[rid] = "initialize"
+
+        if direction == "request" or method is not None:
+            if method == "tools/list" and rid is not None:
+                requests[rid] = method
+            elif method == "tools/call":
+                if rid is None:
+                    findings.append((WARNING, "notification-no-id",
+                                     f"line {n}: tools/call without an id — "
+                                     "fire-and-forget calls cannot be paired with results"))
+                else:
+                    requests[rid] = method
+                    params = line.get("params")
+                    name = params.get("name") if isinstance(params, dict) else None
+                    if known_tools is not None and name not in known_tools:
+                        findings.append((CRITICAL, "unknown-tool",
+                                         f"line {n}: tools/call for '{name}' — not in the "
+                                         "session's tools/list result (client will hang or "
+                                         "get an unhandled error)"))
+            elif method is not None and rid is not None:
+                requests[rid] = method
+
+        # response shape: has result XOR error
+        has_result = "result" in line
+        has_error = "error" in line
+        if has_result and has_error:
+            findings.append((CRITICAL, "both-result-and-error",
+                             f"line {n}: response carries both 'result' and 'error' — "
+                             "receivers must pick one; behavior undefined"))
+        if not has_result and not has_error and method is None:
+            continue
+        if not has_result and not has_error:
+            continue
+
+        if rid is None:
+            findings.append((WARNING, "response-no-id",
+                             f"line {n}: response without an id — cannot be paired "
+                             "with a request"))
+            continue
+
+        if rid in responded:
+            findings.append((CRITICAL, "duplicate-response",
+                             f"line {n}: second response for id {rid} — clients "
+                             "deserialize one; the other is lost or corrupts state"))
+        responded.add(rid)
+
+        if has_error:
+            error_responded.add(rid)
+            err = line["error"]
+            if not isinstance(err, dict) or "code" not in err or "message" not in err:
+                findings.append((CRITICAL, "malformed-error",
+                                 f"line {n}: 'error' is not a JSON-RPC error object "
+                                 "(needs code + message)"))
+            elif requests.get(rid) == "tools/call":
+                exec_failures_as_rpc += 1
+
+        if has_result and isinstance(line.get("result"), dict):
+            result = line["result"]
+            is_err = result.get("isError")
+            text = _err_text(result)
+            if is_err is True:
+                if not text.strip():
+                    findings.append((WARNING, "iserror-empty",
+                                     f"line {n}: isError:true but content carries no "
+                                     "text — the model gets the failure with no detail "
+                                     "and cannot self-correct"))
+            else:
+                # success-shaped result whose text *reads* like an error
+                low = text.lower()
+                if text and (low.startswith("error") or "unknown tool" in low
+                             or low.startswith("auth failed") or low.startswith("failed")
+                             or " 403 " in low):
+                    findings.append((WARNING, "error-as-text",
+                                     f"line {n}: result looks successful (no isError) "
+                                     f"but text reads as a failure: {text[:60]!r} — "
+                                     "clients that trust isError will read this as "
+                                     "output (mcp-era-probe channel-3 behavior)"))
+
+    # dangling / orphan pairing
+    for rid, method in sorted(requests.items()):
+        if rid not in responded:
+            sev = CRITICAL if method == "tools/call" else WARNING
+            findings.append((sev, "dangling-call",
+                             f"request id {rid} ({method}) never got a response — "
+                             "dangling tool_call_id poisons all later requests "
+                             "(opencode #44852)"))
+    for rid in sorted(responded - set(requests)):
+        if rid not in error_responded or requests:
+            findings.append((WARNING, "orphan-response",
+                             f"response for id {rid} but no matching request — "
+                             "recorder dropped the request or ids desynced"))
+
+    if exec_failures_as_rpc >= 2:
+        findings.append((WARNING, "exec-failure-as-rpc-error",
+                         f"{exec_failures_as_rpc} tools/call failures delivered as "
+                         "JSON-RPC errors — execution failures belong in an isError "
+                         "result so the model can self-correct (memoria #258)"))
+
+    return findings
+
+
+SEV_ORDER = {CRITICAL: 0, WARNING: 1, INFO: 2}
+SEV_SYM = {CRITICAL: "[CRITICAL]", WARNING: "[WARNING ]", INFO: "[INFO    ]"}
+
+
+def report(path, findings):
+    lines = []
+    counts = {s: 0 for s in SEV_ORDER}
+    for sev, code, msg in findings:
+        counts[sev] += 1
+        lines.append(f"  {SEV_SYM[sev]} {msg}")
+    print(f"mcp-session-audit: {path}")
+    if not lines:
+        print("  ALL CLEAR — no dangling calls, no swallowed errors, no channel confusion.")
+        return 0
+    for ln in lines:
+        print(ln)
+    parts = [f"{counts[s]} {s.lower()}" for s in (CRITICAL, WARNING, INFO) if counts[s]]
+    print(f"\n  verdict: {', '.join(parts)}.")
+    if counts[CRITICAL]:
+        print("  the session will hang, poison later requests, or feed errors to the model as output.")
+        return 2
+    return 1
+
+
+def load_lines(path):
+    with open(path, "r", encoding="utf-8", errors="replace") as f:
+        return [ln for ln in (l.strip() for l in f) if ln]
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv or argv[0] in ("-h", "--help"):
+        print(__doc__)
+        return 0
+    path = argv[0]
+    findings = audit(load_lines(path))
+    return report(path, findings)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mcpmedic-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcpmedic"
+version = "0.1.0"
+description = "One command, every MCP audit - session hygiene, wire shapes, name collisions. Zero dependencies."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+authors = [{ name = "ZidoCode" }]
+keywords = ["mcp", "model-context-protocol", "audit", "doctor", "jsonrpc", "llm", "agent"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Quality Assurance",
+]
+
+[project.scripts]
+mcpmedic = "mcp_doctor:main"
+
+[tool.hatch.build.targets.wheel]
+only-include = ["mcp_doctor.py", "mcp_session_audit.py", "mcp_schema_audit.py", "mcp_collision.py"]
+sources = ["."]

mcpmedic-0.1.0/test_mcp_doctor.py

@@ -0,0 +1,110 @@
+"""Tests for mcp-doctor — umbrella CLI over session/schema/collision auditors."""
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+import mcp_doctor
+
+
+def jl(obj):
+    return json.dumps(obj)
+
+
+INIT_OK = {"direction": "response", "id": 1, "result": {
+    "protocolVersion": "2025-11-25", "serverInfo": {"name": "srv", "version": "1.0"}}}
+
+
+def write(path, lines):
+    with open(path, "w") as fh:
+        fh.write("\n".join(lines))
+    return path
+
+
+class TestCLI(unittest.TestCase):
+    def setUp(self):
+        self.d = tempfile.mkdtemp()
+        self.clean = write(os.path.join(self.d, "clean.jsonl"), [
+            jl(INIT_OK),
+            jl({"direction": "request", "id": 2, "method": "tools/call",
+                "params": {"name": "t"}}),
+            jl({"direction": "response", "id": 2,
+                "result": {"content": [{"type": "text", "text": "ok"}]}}),
+            jl({"direction": "response", "id": 3, "result": {"tools": [
+                {"name": "t", "inputSchema": {"type": "object", "properties": {}}}]}}),
+        ])
+        self.dirty = write(os.path.join(self.d, "dirty.jsonl"), [
+            jl(INIT_OK),
+            jl({"direction": "request", "id": 2, "method": "tools/call",
+                "params": {"name": "t"}}),
+            # dangling: no response for id 2
+            jl({"direction": "response", "id": 3, "result": {"tools": [
+                {"name": "t", "inputSchema": {}}  # schema-empty
+            ]}}),
+        ])
+        self.script = os.path.join(os.path.dirname(mcp_doctor.__file__), "mcp_doctor.py")
+
+    def _run(self, *argv):
+        return subprocess.run([sys.executable, self.script, *argv],
+                              capture_output=True, text=True)
+
+    def test_help(self):
+        r = self._run("--help")
+        self.assertEqual(r.returncode, 0)
+        for cmd in ("session", "schema", "check", "collide"):
+            self.assertIn(cmd, r.stdout)
+
+    def test_session_clean(self):
+        r = self._run("session", self.clean)
+        self.assertEqual(r.returncode, 0)
+
+    def test_session_dirty(self):
+        r = self._run("session", self.dirty)
+        self.assertEqual(r.returncode, 2)
+        self.assertIn("dangling", r.stdout)
+
+    def test_schema_dirty(self):
+        r = self._run("schema", self.dirty)
+        self.assertEqual(r.returncode, 2)
+        self.assertIn("gitlab-mcp #286", r.stdout)
+
+    def test_check_clean(self):
+        r = self._run("check", self.clean)
+        self.assertEqual(r.returncode, 0)
+
+    def test_check_dirty_combines(self):
+        r = self._run("check", self.dirty)
+        self.assertEqual(r.returncode, 2)
+        # both audit families fire
+        self.assertIn("dangling", r.stdout)
+        self.assertIn("inputSchema", r.stdout)
+
+    def test_check_counts(self):
+        r = self._run("check", self.dirty)
+        self.assertIn("verdict:", r.stdout)
+
+    def test_no_args_exits_nonzero(self):
+        r = self._run()
+        self.assertNotEqual(r.returncode, 0)
+
+    def test_version(self):
+        r = self._run("--version")
+        self.assertEqual(r.returncode, 0)
+        self.assertIn("0.1.0", r.stdout)
+
+    def test_modules_are_same_auditors(self):
+        # vendored modules must be importable and functional
+        self.assertTrue(hasattr(mcp_doctor.mcp_session_audit, "audit"))
+        self.assertTrue(hasattr(mcp_doctor.mcp_schema_audit, "audit"))
+        f = mcp_doctor.mcp_session_audit.audit([jl({"direction": "request", "id": 1,
+                                                    "method": "tools/call", "params": {}})])
+        self.assertTrue(f)
+
+
+if __name__ == "__main__":
+    unittest.main()