mcp-debugger 0.1.0__py3-none-any.whl

mcp_debugger/exporters/markdown_exporter.py

@@ -0,0 +1,196 @@
+"""Markdown exporter – generates a human-readable session report."""
+
+import json
+from datetime import datetime, timezone
+from typing import Any, Dict, IO, List, Optional
+
+from mcp_debugger.analytics import SessionStats
+
+# Maximum raw-JSON bytes included inside a <details> block per message.
+_RAW_TRUNCATE_BYTES = 4096
+
+
+def _fmt_duration(seconds: Optional[int]) -> str:
+    if seconds is None:
+        return "N/A"
+    m, s = divmod(seconds, 60)
+    return f"{m}m {s}s" if m > 0 else f"{s}s"
+
+
+def _fmt_latency(ms: Optional[float]) -> str:
+    if ms is None:
+        return "—"
+    return f"{ms:.1f}ms"
+
+
+def _direction_arrow(direction: str) -> str:
+    return "→ server" if direction == "client_to_server" else "← client"
+
+
+def _decode_json_field(raw: Any) -> Any:
+    if isinstance(raw, str):
+        try:
+            return json.loads(raw)
+        except (json.JSONDecodeError, ValueError):
+            return raw
+    return raw
+
+
+class MarkdownExporter:
+    """Generate a Markdown session report.
+
+    The report contains:
+
+    * **Metadata** – session header table.
+    * **Summary** – key totals.
+    * **Tool Inventory** – per-tool stats table.
+    * **Errors** – classified errors table.
+    * **Message Log** – one row per message; with ``include_raw=True`` each
+      row is followed by a ``<details>`` block containing the full JSON.
+    """
+
+    def __init__(self, include_raw: bool = False, pretty: bool = False) -> None:
+        """Initialise the exporter.
+
+        Args:
+            include_raw: If ``True``, append a ``<details>`` JSON block for
+                each message.
+            pretty: If ``True``, pretty-print the JSON inside ``<details>``
+                blocks (only relevant when *include_raw* is ``True``).
+        """
+        self.include_raw = include_raw
+        self.pretty = pretty
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def export(
+        self,
+        session: Dict[str, Any],
+        messages: List[Dict[str, Any]],
+        tools: List[Dict[str, Any]],
+        errors: List[Dict[str, Any]],
+        stats: SessionStats,
+        out: IO[str],
+    ) -> None:
+        """Write the full Markdown report to *out*."""
+        session_id = session.get("id", "?")
+        name = session.get("friendly_name") or f"Session #{session_id}"
+
+        out.write(f"# MCP Session Report – {name}\n\n")
+        self._write_metadata(session, stats, out)
+        self._write_summary(stats, out)
+        self._write_tools(stats, out)
+        self._write_errors(errors, out)
+        self._write_message_log(messages, out)
+
+    # ------------------------------------------------------------------
+    # Section writers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _write_metadata(
+        session: Dict[str, Any],
+        stats: SessionStats,
+        out: IO[str],
+    ) -> None:
+        out.write("## Metadata\n\n")
+        out.write("| Property | Value |\n")
+        out.write("| :------- | :---- |\n")
+        rows = [
+            ("Session ID", str(session.get("id", ""))),
+            ("Name", session.get("friendly_name") or "—"),
+            ("Server command", f"`{session.get('server_command', '')}`"),
+            ("Started", str(session.get("started_at") or "—")),
+            ("Ended", str(session.get("ended_at") or "—")),
+            ("Duration", _fmt_duration(stats.duration_seconds)),
+            ("Status", str(session.get("status") or "—")),
+        ]
+        for label, value in rows:
+            out.write(f"| {label} | {value} |\n")
+        out.write("\n")
+
+    @staticmethod
+    def _write_summary(stats: SessionStats, out: IO[str]) -> None:
+        total_errors = sum(stats.errors_by_category.values())
+        total = stats.total_messages
+        error_rate_pct = f"{(total_errors / total * 100):.1f}%" if total > 0 else "0%"
+        out.write("## Summary\n\n")
+        out.write(
+            f"- **Total messages:** {total} "
+            f"({stats.client_to_server_count} → server, "
+            f"{stats.server_to_client_count} ← client)\n"
+        )
+        out.write(f"- **Errors:** {total_errors} ({error_rate_pct} error rate)\n")
+        out.write(f"- **Tools called:** {len(stats.top_tools)}\n")
+        if stats.latency_avg is not None:
+            out.write(f"- **Avg latency:** {_fmt_latency(stats.latency_avg)}\n")
+        out.write("\n")
+
+    @staticmethod
+    def _write_tools(stats: SessionStats, out: IO[str]) -> None:
+        out.write("## Tool Inventory\n\n")
+        if not stats.top_tools:
+            out.write("_No tools discovered in this session._\n\n")
+            return
+        out.write("| Tool | Calls | Avg Latency | Error Rate |\n")
+        out.write("| :--- | :---: | :---: | :---: |\n")
+        for tool in stats.top_tools:
+            avg_lat = _fmt_latency(tool.avg_latency_ms)
+            err_pct = f"{tool.error_rate * 100:.0f}%"
+            out.write(f"| {tool.name} | {tool.calls} | {avg_lat} | {err_pct} |\n")
+        out.write("\n")
+
+    @staticmethod
+    def _write_errors(errors: List[Dict[str, Any]], out: IO[str]) -> None:
+        out.write("## Errors\n\n")
+        if not errors:
+            out.write("_No errors recorded._\n\n")
+            return
+        out.write("| Type | Code | Message | Suggestion |\n")
+        out.write("| :--- | :---: | :--- | :--- |\n")
+        for err in errors:
+            etype = err.get("error_type") or "—"
+            code = str(err.get("error_code") or "—")
+            msg = (err.get("error_message") or "").replace("|", "\\|")
+            sug = (err.get("suggestion") or "—").replace("|", "\\|")
+            out.write(f"| {etype} | {code} | {msg} | {sug} |\n")
+        out.write("\n")
+
+    def _write_message_log(self, messages: List[Dict[str, Any]], out: IO[str]) -> None:
+        out.write("## Message Log\n\n")
+        if not messages:
+            out.write("_No messages recorded._\n\n")
+            return
+
+        out.write("| # | Direction | Method | Timestamp | Latency |\n")
+        out.write("| :- | :-------- | :----- | :-------- | :------ |\n")
+        for i, msg in enumerate(messages, start=1):
+            direction = _direction_arrow(msg.get("direction") or "")
+            method = msg.get("method") or "—"
+            ts_raw = msg.get("timestamp")
+            ts_str: str
+            if isinstance(ts_raw, (int, float)):
+                ts_str = datetime.fromtimestamp(ts_raw / 1000.0, tz=timezone.utc).strftime(
+                    "%H:%M:%S.%f"
+                )[:-3]  # trim to milliseconds
+            else:
+                ts_str = str(ts_raw or "—")
+            latency = _fmt_latency(msg.get("latency_ms"))
+            out.write(f"| {i} | {direction} | `{method}` | {ts_str} | {latency} |\n")
+
+        if self.include_raw:
+            out.write("\n")
+            for i, msg in enumerate(messages, start=1):
+                direction = msg.get("direction") or ""
+                method = msg.get("method") or "message"
+                out.write(f"<details>\n<summary>Message #{i}: {method} ({direction})</summary>\n\n")
+                # Build a clean dict (decode JSON fields)
+                clean: Dict[str, Any] = {
+                    k: _decode_json_field(v) for k, v in msg.items() if k not in ("session_id",)
+                }
+                raw_json = json.dumps(clean, indent=2 if self.pretty else None, default=str)
+                if len(raw_json) > _RAW_TRUNCATE_BYTES:
+                    raw_json = raw_json[:_RAW_TRUNCATE_BYTES] + "\n... [truncated]"
+                out.write(f"```json\n{raw_json}\n```\n\n</details>\n\n")

mcp_debugger/exporters/otlp_exporter.py

@@ -0,0 +1,206 @@
+"""OTLP exporter – converts MCP session messages into OpenTelemetry spans.
+
+Requires the optional ``[export]`` dependency group::
+
+    pip install mcp-debugger[export]
+
+If the ``opentelemetry-sdk`` package is not installed this module raises
+``ImportError`` with a helpful message rather than crashing silently.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional, Tuple
+
+try:
+    from opentelemetry.sdk.resources import Resource
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+    from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+
+    _OTLP_AVAILABLE = True
+except ImportError:  # pragma: no cover
+    _OTLP_AVAILABLE = False
+
+
+def _get_tool_name(params_raw: Optional[str]) -> Optional[str]:
+    """Extract tool name from a serialised ``params`` JSON string."""
+    if not params_raw:
+        return None
+    try:
+        params = json.loads(params_raw)
+        if isinstance(params, dict):
+            return params.get("name")
+    except (json.JSONDecodeError, ValueError):
+        pass
+    return None
+
+
+class OTLPExporter:
+    """Convert a session's messages into OpenTelemetry spans and export them.
+
+    Each request–response pair becomes one span.  Notifications (no ID)
+    become zero-duration spans.  All message spans are children of a root
+    session span so the full timeline is visible in one trace.
+
+    Args:
+        endpoint: OTLP gRPC collector endpoint (default ``http://localhost:4317``).
+        insecure: Disable TLS verification (useful for local testing).
+        service_name: Service name attached to all spans.
+        limit: If given, export only the first *limit* messages.
+    """
+
+    def __init__(
+        self,
+        endpoint: str = "http://localhost:4317",
+        insecure: bool = True,
+        service_name: str = "mcp-debugger",
+        limit: Optional[int] = None,
+    ) -> None:
+        if not _OTLP_AVAILABLE:
+            raise ImportError(
+                "OpenTelemetry SDK is not installed. Run: pip install 'mcp-debugger[export]'"
+            )
+        self.endpoint = endpoint
+        self.insecure = insecure
+        self.service_name = service_name
+        self.limit = limit
+
+    def export(
+        self,
+        session: Dict[str, Any],
+        messages: List[Dict[str, Any]],
+    ) -> int:
+        """Build and export spans for all request–response pairs.
+
+        Returns the number of spans exported (excluding the root span).
+        """
+        msgs = messages[: self.limit] if self.limit is not None else messages
+
+        resource = Resource.create({"service.name": self.service_name})
+        provider = TracerProvider(resource=resource)
+        exporter_obj = OTLPSpanExporter(
+            endpoint=self.endpoint,
+            insecure=self.insecure,
+        )
+        provider.add_span_processor(BatchSpanProcessor(exporter_obj))
+        tracer = provider.get_tracer("mcp-debugger")
+
+        session_id = session.get("id", 0)
+        session_name = session.get("friendly_name") or f"session-{session_id}"
+
+        # --- root session span ---
+        with tracer.start_as_current_span(
+            name=f"mcp-session {session_name}",
+            attributes={
+                "mcp.session.id": str(session_id),
+                "mcp.server.command": str(session.get("server_command") or ""),
+                "mcp.session.status": str(session.get("status") or ""),
+            },
+        ):
+            pairs = self._pair_messages(msgs)
+            span_count = 0
+            for req, resp in pairs:
+                self._emit_span(tracer, req, resp, session)
+                span_count += 1
+
+        provider.shutdown()
+        return span_count
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _pair_messages(
+        messages: List[Dict[str, Any]],
+    ) -> List[Tuple[Dict[str, Any], Optional[Dict[str, Any]]]]:
+        """Match requests with their responses by message_id.
+
+        Notifications (no message_id) are emitted as solo pairs ``(msg, None)``.
+        Responses without a matching request are skipped.
+        """
+        request_map: Dict[str, Dict[str, Any]] = {}
+        pairs: List[Tuple[Dict[str, Any], Optional[Dict[str, Any]]]] = []
+
+        for msg in messages:
+            direction = msg.get("direction")
+            msg_type = msg.get("message_type")
+            msg_id = msg.get("message_id")
+
+            if msg_type == "notification":
+                pairs.append((msg, None))
+            elif msg_type == "request" and direction == "client_to_server":
+                if msg_id:
+                    request_map[msg_id] = msg
+                else:
+                    pairs.append((msg, None))
+            elif msg_type == "response" and direction == "server_to_client":
+                if msg_id and msg_id in request_map:
+                    pairs.append((request_map.pop(msg_id), msg))
+
+        # Any unmatched requests (no response received)
+        for req in request_map.values():
+            pairs.append((req, None))
+
+        return pairs
+
+    def _emit_span(
+        self,
+        tracer: Any,
+        req: Dict[str, Any],
+        resp: Optional[Dict[str, Any]],
+        session: Dict[str, Any],
+    ) -> None:
+        method = req.get("method") or "unknown"
+        span_name = f"mcp.{method}"
+        latency_ms = resp.get("latency_ms") if resp else None
+
+        # Build attributes
+        attrs: Dict[str, Any] = {
+            "mcp.method": method,
+            "mcp.direction": str(req.get("direction") or ""),
+            "mcp.server.command": str(session.get("server_command") or ""),
+        }
+
+        if method == "tools/call":
+            tool_name = _get_tool_name(req.get("params"))
+            if tool_name:
+                attrs["mcp.tool.name"] = tool_name
+
+        has_error = False
+        if resp:
+            if resp.get("error"):
+                has_error = True
+                attrs["mcp.error"] = True
+                err_raw = resp.get("error")
+                if isinstance(err_raw, str):
+                    try:
+                        err_dict = json.loads(err_raw)
+                        code = err_dict.get("code")
+                        if code is not None:
+                            attrs["mcp.error_code"] = int(code)
+                    except (json.JSONDecodeError, ValueError):
+                        pass
+            elif resp.get("result"):
+                try:
+                    result = (
+                        json.loads(resp["result"])
+                        if isinstance(resp["result"], str)
+                        else resp["result"]
+                    )
+                    if isinstance(result, dict) and result.get("isError"):
+                        has_error = True
+                        attrs["mcp.error"] = True
+                except (json.JSONDecodeError, ValueError):
+                    pass
+
+        if not has_error:
+            attrs["mcp.error"] = False
+
+        if latency_ms is not None:
+            attrs["mcp.latency_ms"] = float(latency_ms)
+
+        with tracer.start_as_current_span(span_name, attributes=attrs):
+            pass  # span lifecycle managed by context manager

mcp_debugger/exporters/otlp_replay_exporter.py

@@ -0,0 +1,221 @@
+"""OTLP exporter for replay results.
+
+Converts a :class:`~mcp_debugger.replay.engine.ReplayResult` into
+OpenTelemetry trace spans and exports them to an OTLP collector (e.g. Jaeger,
+Grafana Tempo, or any compatible backend).
+
+Requires the optional ``[otlp]`` dependency group::
+
+    pip install 'mcp-debugger[otlp]'
+
+If the ``opentelemetry-sdk`` package is not installed this module raises
+``ImportError`` with a helpful message rather than crashing silently.
+
+Trace structure
+---------------
+* One trace per replay run.
+* Root span – ``mcp.replay <session_id>`` – carries summary attributes.
+* One child span per replayed message – ``mcp.replay.<method>`` – carries
+  per-message attributes and, for mismatches, a structured diff event.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any, Dict
+
+# ---------------------------------------------------------------------------
+# Optional OpenTelemetry imports – guarded so the module can be imported even
+# when the SDK is not installed.  The actual classes are only used inside
+# OTLPReplayExporter, which refuses to construct itself without the SDK.
+# ---------------------------------------------------------------------------
+try:
+    from opentelemetry import trace as _otel_trace  # noqa: F401
+    from opentelemetry.sdk.resources import Resource
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+    from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
+        OTLPSpanExporter,
+    )
+    from opentelemetry.trace import Status, StatusCode
+
+    _OTLP_AVAILABLE = True
+except ImportError:  # pragma: no cover
+    _OTLP_AVAILABLE = False
+    # Sentinel stubs so patch.object() in tests can always find these names,
+    # even when the SDK is not installed.
+    Resource = None  # type: ignore
+    TracerProvider = None  # type: ignore
+    BatchSpanProcessor = None  # type: ignore
+    OTLPSpanExporter = None  # type: ignore
+    Status = None  # type: ignore
+    StatusCode = None  # type: ignore
+
+if TYPE_CHECKING:  # pragma: no cover
+    from mcp_debugger.replay.engine import ReplayResult, ReplayedMessage
+
+_DIFF_SUMMARY_MAX = 255  # OTLP attribute character limit for diff summaries
+
+
+class OTLPReplayExporter:
+    """Convert a :class:`~mcp_debugger.replay.engine.ReplayResult` into OTLP spans.
+
+    Each replay run becomes a single trace:
+
+    * The root span carries aggregate statistics (total, matches, mismatches,
+      timeouts, errors, match percentage).
+    * Each replayed message becomes a child span carrying per-message data
+      (method, matched, latency, diff summary).  Mismatched messages also
+      receive a structured ``mcp.replay.diff`` event.
+
+    Args:
+        endpoint: OTLP gRPC collector endpoint (default ``http://localhost:4317``).
+        insecure: Disable TLS verification (useful for local testing).
+        service_name: Service name attached to all spans.
+    """
+
+    def __init__(
+        self,
+        endpoint: str = "http://localhost:4317",
+        insecure: bool = True,
+        service_name: str = "mcp-debugger",
+    ) -> None:
+        if not _OTLP_AVAILABLE:
+            raise ImportError(
+                "OpenTelemetry SDK is not installed. Run: pip install 'mcp-debugger[otlp]'"
+            )
+        self.endpoint = endpoint
+        self.insecure = insecure
+        self.service_name = service_name
+
+    def export(self, result: "ReplayResult") -> int:
+        """Export *result* as an OTLP trace.
+
+        Returns the number of child spans (replayed messages) exported, not
+        counting the root span.  Returns 0 if export fails.
+        """
+        resource = Resource.create({"service.name": self.service_name})
+        provider = TracerProvider(resource=resource)
+        otlp_exporter = OTLPSpanExporter(
+            endpoint=self.endpoint,
+            insecure=self.insecure,
+        )
+        provider.add_span_processor(BatchSpanProcessor(otlp_exporter))
+        tracer = provider.get_tracer("mcp-debugger.replay")
+
+        total = result.total_messages_replayed
+        matches = sum(1 for m in result.messages if m.matches)
+        mismatches = result.mismatched_responses
+        timeouts = result.timed_out
+        errors = result.failed_responses
+        match_pct = round(matches / total * 100, 1) if total else 0.0
+        duration_s = (result.ended_at - result.started_at).total_seconds()
+
+        root_attrs: Dict[str, Any] = {
+            "replay.session_id": str(result.session_id),
+            "replay.target_server_command": result.target_server_command,
+            "replay.total_messages": total,
+            "replay.matches": matches,
+            "replay.mismatches": mismatches,
+            "replay.timeouts": timeouts,
+            "replay.errors": errors,
+            "replay.match_percentage": match_pct,
+            "replay.duration_seconds": round(duration_s, 3),
+        }
+        if result.replay_id is not None:
+            root_attrs["replay.id"] = str(result.replay_id)
+
+        span_count = 0
+
+        with tracer.start_as_current_span(
+            name=f"mcp.replay session-{result.session_id}",
+            attributes=root_attrs,
+        ) as root_span:
+            # Mark root span as error if there were any mismatches or timeouts
+            if mismatches > 0 or timeouts > 0 or errors > 0:
+                root_span.set_status(
+                    Status(StatusCode.ERROR, f"{mismatches} mismatch(es), {timeouts} timeout(s)")
+                )
+
+            for msg in result.messages:
+                self._emit_message_span(tracer, msg)
+                span_count += 1
+
+        provider.force_flush()
+        provider.shutdown()
+        return span_count
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _emit_message_span(
+        self,
+        tracer: Any,
+        msg: "ReplayedMessage",
+    ) -> None:
+        """Create a child span for a single replayed message."""
+        method = msg.method or "unknown"
+        span_name = f"mcp.replay.{method}"
+
+        attrs: Dict[str, Any] = {
+            "mcp.method": method,
+            "mcp.direction": "client_to_server",
+            "mcp.replay.original_message_id": str(msg.original_message_id),
+            "mcp.replay.matched": msg.matches,
+            "mcp.replay.latency_ms": round(msg.latency_ms, 3),
+        }
+
+        # Extract tool name for tools/call spans
+        if method == "tools/call" and msg.request_sent:
+            params = msg.request_sent.get("params")
+            if isinstance(params, dict):
+                tool_name = params.get("name")
+            elif isinstance(params, str):
+                try:
+                    tool_name = json.loads(params).get("name")
+                except (json.JSONDecodeError, ValueError):
+                    tool_name = None
+            else:
+                tool_name = None
+            if tool_name:
+                attrs["mcp.tool.name"] = str(tool_name)
+
+        # Truncated diff summary for quick scanning in trace UIs
+        if msg.diff_text:
+            attrs["mcp.replay.diff_summary"] = msg.diff_text[:_DIFF_SUMMARY_MAX]
+
+        if msg.error:
+            attrs["mcp.replay.error"] = msg.error[:_DIFF_SUMMARY_MAX]
+
+        with tracer.start_as_current_span(span_name, attributes=attrs) as span:
+            if not msg.matches or msg.error:
+                description = msg.error or f"Response mismatch for {method}"
+                span.set_status(Status(StatusCode.ERROR, description))
+
+            # Add structured diff event for mismatched messages
+            if not msg.matches and msg.diff:
+                try:
+                    diff_json = json.dumps(
+                        [d.model_dump() for d in msg.diff],
+                        separators=(",", ":"),
+                    )
+                    # Truncate to a safe size for OTLP event payloads
+                    span.add_event(
+                        "mcp.replay.diff",
+                        attributes={"diff": diff_json[:1024]},
+                    )
+                except Exception:
+                    # Never let serialisation errors break the export
+                    pass
+
+            # Add original and replayed response hashes for grouping
+            if msg.original_response is not None:
+                try:
+                    orig_str = json.dumps(msg.original_response, sort_keys=True)
+                    span.set_attribute(
+                        "mcp.replay.original_response_hash",
+                        str(hash(orig_str) & 0xFFFFFFFF),
+                    )
+                except Exception:
+                    pass