# Install (PyPI package coming soon — use git install for now)
pip install git+https://github.com/prasad-a-abhishek/mcp-msgdump.git

# Analyze a trace log
mcp-msgdump analyze /tmp/mcp_session.jsonl --format summary

# Run as an MCP proxy (all messages forwarded + logged to stderr)
mcp-msgdump proxy --target localhost:3000 --port 8080

# Library API
from mcp_msgdump import analyze_log, check_schemas, replay_session

report = analyze_log("/tmp/mcp_session.jsonl")
print(report.total_requests)       # e.g. 47
print(report.error_count)          # e.g. 3
print(report.tools_called)          # ['read_file', 'write_file', 'list_dir']

mcp-msgdump [--help]
mcp-msgdump analyze [FILE] [--format {summary,json}]
mcp-msgdump proxy --target HOST:PORT [--port PORT]

from mcp_msgdump import analyze_log

report = analyze_log("/tmp/session.jsonl")
assert report.total_requests == 47
assert report.error_count == 3
assert "read_file" in report.tools_called
assert report.schema_issues == []

from mcp_msgdump import check_schemas

issues = check_schemas("/tmp/session.jsonl")
for issue in issues:
    print(f"[{issue.severity.value}] {issue.tool_name}.{issue.parameter_name}: {issue.message}")

from mcp_msgdump import replay_session

results = replay_session("/tmp/session.jsonl", filter_tool="read_file")
for r in results:
    print(f"#{r.index} {r.tool_name}: {r.params}")

from mcp_msgdump import AnalysisReport, ReplayResult, SchemaIssue, ToolCall, Mismatch, Severity

# AnalysisReport fields:
report.total_requests    # int — count of JSON-RPC requests seen
report.error_count       # int — count of error responses
report.tools_called      # list[str] — unique tool names called
report.slowest_call     # ToolCall | None — slowest tool call by latency_ms
report.schema_mismatches # list[Mismatch] — schema mismatches (v1: always empty)
report.tool_calls        # list[ToolCall] — all tool call records
report.schema_issues     # list[SchemaIssue] — detected schema issues
report.batch_sub_requests # int — count of sub-requests inside batch arrays
report.empty_file       # bool — true if input was empty
report.malformed_lines   # int — count of unparseable lines

# ToolCall fields:
tc.method               # str — JSON-RPC method name (e.g. "tools/call")
tc.params              # dict — parameters passed to the tool
tc.id                  # int | str | None — request ID
tc.latency_ms          # float | None — latency in ms (set when response has duration)
tc.is_notification     # bool — true if id was null (no response expected)
tc.is_error            # bool — true if response contained an error
tc.error_message       # str | None — error message if is_error is True

# ReplayResult fields:
r.index                # int — position in the log
r.method               # str — JSON-RPC method name
r.params               # dict — parameters
r.response             # dict | None — response if available
r.skipped              # bool — true if filtered out by filter_tool
r.skip_reason          # str | None — reason if skipped

# SchemaIssue fields:
issue.tool_name        # str — name of the tool
issue.parameter_name   # str | None — affected parameter name
issue.issue_type       # str — e.g. "untyped", "dangerously_typed", "missing_description"
issue.message          # str — human-readable description
issue.severity         # Severity — Severity.WARNING or Severity.ERROR

# Mismatch fields:
m.tool_name            # str
m.field                # str
m.expected              # Any
m.actual               # Any
m.description          # str | None

pytest -v

{
  "mcpServers": {
    "mcp-msgdump": {
      "command": "python",
      "args": ["-m", "mcp_msgdump", "analyze", "/path/to/session.jsonl"]
    }
  }
}

{
  "mcpServers": {
    "mcp-msgdump": {
      "command": "python",
      "args": ["-m", "mcp_msgdump", "analyze", "/path/to/session.jsonl"]
    }
  }
}

{
  "mcpServers": {
    "mcp-msgdump": {
      "command": "python",
      "args": ["-m", "mcp_msgdump", "analyze", "/path/to/session.jsonl"]
    }
  }
}

{
  "mcpServers": {
    "mcp-msgdump": {
      "command": "python",
      "args": ["-m", "mcp_msgdump", "analyze", "/path/to/session.jsonl"]
    }
  }
}

mcp_servers:
  mcp-msgdump:
    command: python
    args: ["-m", "mcp_msgdump", "analyze", "/path/to/session.jsonl"]