mcp-debugger 0.1.0__tar.gz → 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (142) hide show
  1. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/.gitignore +4 -0
  2. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/CHANGELOG.md +50 -0
  3. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/PKG-INFO +52 -6
  4. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/README.md +44 -4
  5. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/06-production-standards.md +1 -0
  6. mcp_debugger-0.2.0/docs/25-90-day-plan-detailed.md +448 -0
  7. mcp_debugger-0.2.0/docs/adr/0001-reorder-adapters-and-hybrid-attribution.md +18 -0
  8. mcp_debugger-0.2.0/docs/adr/0002-trace-ingestion-and-dual-protocol.md +25 -0
  9. mcp_debugger-0.2.0/docs/adr/0003-multi-agent-data-model-and-packaging.md +33 -0
  10. mcp_debugger-0.2.0/docs/agents/domain.md +51 -0
  11. mcp_debugger-0.2.0/docs/agents/issue-tracker.md +50 -0
  12. mcp_debugger-0.2.0/docs/agents/triage-labels.md +15 -0
  13. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/commands.md +111 -7
  14. mcp_debugger-0.2.0/docs/demo.gif +0 -0
  15. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/replay.md +3 -2
  16. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/tutorials.md +3 -1
  17. mcp_debugger-0.2.0/docs/web-ui.md +45 -0
  18. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/pyproject.toml +8 -1
  19. mcp_debugger-0.2.0/scripts/generate_demo_gif.py +387 -0
  20. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/scripts/test_real_servers.py +12 -12
  21. mcp_debugger-0.2.0/src/mcp_debugger/__init__.py +6 -0
  22. mcp_debugger-0.2.0/src/mcp_debugger/adapters/__init__.py +13 -0
  23. mcp_debugger-0.2.0/src/mcp_debugger/adapters/crewai.py +286 -0
  24. mcp_debugger-0.2.0/src/mcp_debugger/adapters/langchain.py +225 -0
  25. mcp_debugger-0.2.0/src/mcp_debugger/adapters/openai.py +192 -0
  26. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/analytics.py +59 -36
  27. mcp_debugger-0.2.0/src/mcp_debugger/attribution/__init__.py +41 -0
  28. mcp_debugger-0.2.0/src/mcp_debugger/attribution/ablation.py +207 -0
  29. mcp_debugger-0.2.0/src/mcp_debugger/attribution/classifier.py +366 -0
  30. mcp_debugger-0.2.0/src/mcp_debugger/attribution/cost.py +337 -0
  31. mcp_debugger-0.2.0/src/mcp_debugger/attribution/live.py +237 -0
  32. mcp_debugger-0.2.0/src/mcp_debugger/attribution/models.py +81 -0
  33. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/cli.py +1176 -53
  34. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/config.py +13 -13
  35. mcp_debugger-0.2.0/src/mcp_debugger/exporters/__init__.py +15 -0
  36. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/exporters/json_exporter.py +19 -19
  37. mcp_debugger-0.2.0/src/mcp_debugger/exporters/junit_exporter.py +179 -0
  38. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/exporters/markdown_exporter.py +13 -13
  39. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/exporters/otlp_exporter.py +160 -32
  40. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/exporters/otlp_replay_exporter.py +32 -23
  41. mcp_debugger-0.2.0/src/mcp_debugger/exporters/sarif_exporter.py +204 -0
  42. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/protocol/error_classifier.py +77 -3
  43. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/protocol/schemas.py +10 -9
  44. mcp_debugger-0.2.0/src/mcp_debugger/protocol/validator.py +728 -0
  45. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/proxy/stdio_proxy.py +79 -12
  46. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/replay/__init__.py +6 -3
  47. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/replay/diff.py +6 -5
  48. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/replay/engine.py +28 -26
  49. mcp_debugger-0.2.0/src/mcp_debugger/replay/handoff.py +149 -0
  50. mcp_debugger-0.2.0/src/mcp_debugger/sdk/__init__.py +29 -0
  51. mcp_debugger-0.2.0/src/mcp_debugger/sdk/context.py +60 -0
  52. mcp_debugger-0.2.0/src/mcp_debugger/sdk/decorators.py +332 -0
  53. mcp_debugger-0.2.0/src/mcp_debugger/sdk/handoff.py +268 -0
  54. mcp_debugger-0.2.0/src/mcp_debugger/sdk/ingestion.py +183 -0
  55. mcp_debugger-0.2.0/src/mcp_debugger/storage/__init__.py +40 -0
  56. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/storage/database.py +676 -41
  57. mcp_debugger-0.2.0/src/mcp_debugger/storage/postgres.py +545 -0
  58. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/validate_live.py +3 -4
  59. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/version.py +1 -1
  60. mcp_debugger-0.2.0/src/mcp_debugger/web/__init__.py +1 -0
  61. mcp_debugger-0.2.0/src/mcp_debugger/web/app.py +179 -0
  62. mcp_debugger-0.2.0/src/mcp_debugger/web/static/app.js +281 -0
  63. mcp_debugger-0.2.0/src/mcp_debugger/web/static/session.js +269 -0
  64. mcp_debugger-0.2.0/src/mcp_debugger/web/static/style.css +172 -0
  65. mcp_debugger-0.2.0/src/mcp_debugger/web/templates/base.html +61 -0
  66. mcp_debugger-0.2.0/src/mcp_debugger/web/templates/session_detail.html +185 -0
  67. mcp_debugger-0.2.0/src/mcp_debugger/web/templates/sessions.html +173 -0
  68. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/conftest.py +4 -3
  69. mcp_debugger-0.2.0/tests/test_adapters/test_crewai.py +156 -0
  70. mcp_debugger-0.2.0/tests/test_adapters/test_langchain.py +174 -0
  71. mcp_debugger-0.2.0/tests/test_adapters/test_openai.py +138 -0
  72. mcp_debugger-0.2.0/tests/test_attribution/test_ablation_engine.py +235 -0
  73. mcp_debugger-0.2.0/tests/test_attribution/test_cost.py +213 -0
  74. mcp_debugger-0.2.0/tests/test_attribution/test_heuristic_classifier.py +282 -0
  75. mcp_debugger-0.2.0/tests/test_attribution/test_live_counterfactual.py +163 -0
  76. mcp_debugger-0.2.0/tests/test_cli/test_agents.py +161 -0
  77. mcp_debugger-0.2.0/tests/test_cli/test_attribute.py +124 -0
  78. mcp_debugger-0.2.0/tests/test_cli/test_ci.py +291 -0
  79. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_cli/test_cli_edge_cases.py +462 -520
  80. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_cli/test_export.py +2 -1
  81. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_cli/test_inspect.py +37 -2
  82. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_cli/test_list.py +3 -2
  83. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_cli/test_proxy.py +2 -2
  84. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_cli/test_replay.py +12 -11
  85. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_cli/test_stats.py +45 -5
  86. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_cli/test_validate.py +3 -2
  87. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_exporters/test_json.py +2 -2
  88. mcp_debugger-0.2.0/tests/test_exporters/test_junit.py +243 -0
  89. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_exporters/test_markdown.py +1 -0
  90. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_exporters/test_otlp.py +216 -4
  91. mcp_debugger-0.2.0/tests/test_exporters/test_sarif.py +174 -0
  92. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_integration/test_integration.py +9 -9
  93. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_property.py +6 -5
  94. mcp_debugger-0.2.0/tests/test_protocol/test_error_classifier.py +298 -0
  95. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_protocol/test_validator.py +253 -1
  96. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_proxy/test_stdio_proxy.py +129 -22
  97. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_replay/test_diff.py +2 -1
  98. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_replay/test_engine.py +7 -6
  99. mcp_debugger-0.2.0/tests/test_replay/test_handoff_replay.py +148 -0
  100. mcp_debugger-0.2.0/tests/test_sdk/test_decorators.py +248 -0
  101. mcp_debugger-0.2.0/tests/test_sdk/test_handoff.py +115 -0
  102. mcp_debugger-0.2.0/tests/test_sdk/test_ingestion.py +131 -0
  103. mcp_debugger-0.2.0/tests/test_storage/test_agents_database.py +142 -0
  104. mcp_debugger-0.2.0/tests/test_storage/test_attribution_database.py +113 -0
  105. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_storage/test_database.py +3 -2
  106. mcp_debugger-0.2.0/tests/test_storage/test_postgres.py +174 -0
  107. mcp_debugger-0.2.0/tests/test_storage/test_trajectory_database.py +164 -0
  108. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_stress.py +5 -4
  109. mcp_debugger-0.1.0/docs/04-25-day-plan-detailed.md +0 -232
  110. mcp_debugger-0.1.0/src/mcp_debugger/__init__.py +0 -5
  111. mcp_debugger-0.1.0/src/mcp_debugger/exporters/__init__.py +0 -6
  112. mcp_debugger-0.1.0/src/mcp_debugger/protocol/validator.py +0 -471
  113. mcp_debugger-0.1.0/tests/__init__.py +0 -0
  114. mcp_debugger-0.1.0/tests/test_protocol/test_error_classifier.py +0 -142
  115. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/CONTRIBUTING.md +0 -0
  116. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/LICENSE +0 -0
  117. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/00-project-charter.md +0 -0
  118. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/01-architecture-deep.md +0 -0
  119. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/02-data-models-detailed.md +0 -0
  120. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/03-database-schema.md +0 -0
  121. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/05-mcp-protocol-reference.md +0 -0
  122. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/07-glossary.md +0 -0
  123. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/08-faq.md +0 -0
  124. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/AI_INSTRUCTIONS.md +0 -0
  125. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/README.md +0 -0
  126. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/architecture.md +0 -0
  127. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/compatibility.md +0 -0
  128. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/config.md +0 -0
  129. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/contributing.md +0 -0
  130. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/diagrams/README.md +0 -0
  131. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/faq.md +0 -0
  132. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/scripts/check_version.py +0 -0
  133. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/scripts/stress_test.py +1 -1
  134. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/display/__init__.py +0 -0
  135. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/protocol/__init__.py +0 -0
  136. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/proxy/__init__.py +0 -0
  137. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/py.typed +0 -0
  138. {mcp_debugger-0.1.0/src/mcp_debugger/storage → mcp_debugger-0.2.0/tests}/__init__.py +0 -0
  139. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/mock_servers/echo_server.py +1 -1
  140. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_cli/test_cli_config.py +1 -1
  141. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_config/test_config.py +2 -2
  142. {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_protocol/test_schemas.py +3 -3
@@ -16,3 +16,7 @@ __pycache__/
16
16
  *.log
17
17
  *.tmp
18
18
  *.pid
19
+ scratch/
20
+ *.sarif
21
+ *.xml
22
+
@@ -7,6 +7,56 @@ Versioning follows [Semantic Versioning](https://semver.org/).
7
7
 
8
8
  ---
9
9
 
10
+ ## [0.2.0] — 2026-11-22
11
+
12
+ Major release introducing Causal Failure Attribution, Multi-Agent Hierarchy & Handoff Tracking, Cassette-Backed Handoff Replay, Enterprise CI/CD Gates, Compliance Exporters (SARIF & JUnit XML), Token Cost Attribution, and PostgreSQL Team Storage.
13
+
14
+ ### Added
15
+
16
+ #### Causal Failure Attribution & Step Ablation
17
+ - `mcp-debugger attribute <session_id>`: isolate root cause step and Point-of-Commitment (PoC) using counterfactual step ablation.
18
+ - `AblationEngine`: offline VCR cassette perturbation with empty results and tool errors.
19
+ - `LiveCounterfactualEngine`: preflight cost estimator, live token sampling, and counterfactual branch re-execution.
20
+ - `FailureClassifier`: heuristic rules classifying failure boundaries (`agent`, `tool`, `protocol`, `none`).
21
+
22
+ #### Multi-Agent Hierarchy & Handoff Tracking
23
+ - `mcp-debugger agents <session_id>`: visualize agent delegation hierarchy with interactive Rich trees (`--tree`), handoff transitions (`--handoffs`), and JSON export (`--json`).
24
+ - Relational `agents` schema and `steps.agent_id` tracking foreign key hierarchy.
25
+ - SDK context tracking: `@trace_handoff` and `trace_handoff_context` capturing context state diffs (`added`, `removed`, `modified`).
26
+ - Multi-agent framework adapters: `CrewAITracker` / `trace_crewai`, `LangChainTracker` / `trace_langchain`, and `OpenAITracker` / `trace_openai`.
27
+
28
+ #### Cassette-Backed Handoff Replay
29
+ - `HandoffReplayEngine` (ADR 0003): re-execute downstream agents against static upstream execution history cassettes without non-deterministic divergence or re-execution cost.
30
+
31
+ #### Enterprise CI/CD Quality Gates
32
+ - `mcp-debugger ci <sessions...>`: tiered build gating across multiple session IDs or database files.
33
+ - Deterministic exit codes: exit 1 on protocol schema violations, tool execution errors, and replay regressions; exit 0 with non-blocking latency/cost warnings unless `--strict` is enabled.
34
+ - SARIF v2.1.0 exporter (`--sarif`): maps protocol violations, causal PoC findings, and replay regressions for native GitHub Code Scanning integration.
35
+ - JUnit XML exporter (`--junit`): standard test report XML (`<testsuites>`, `<testsuite>`, `<testcase>`) for CI/CD runners (GitHub Actions, Jenkins, GitLab CI).
36
+
37
+ #### Token & Cost Attribution Engine
38
+ - `CostCalculator`: model pricing registry supporting GPT-4o, Claude 3.5 Sonnet, Gemini 1.5/2.0, DeepSeek V3/R1, and custom models.
39
+ - Per-step token accounting and per-agent rollups with orchestrator/worker categorization and cost share percentages.
40
+ - Automated anomaly detection for token spikes (>3x step average) and budget exceedance (`--max-cost`).
41
+ - Integrated into `mcp-debugger stats` and `mcp-debugger ci`.
42
+
43
+ #### Team Storage & PostgreSQL Backend
44
+ - `PostgresDatabase` (ADR 0003): optional PostgreSQL backend using `asyncpg` with connection pooling.
45
+ - Unified backend routing via `get_database()` supporting `MCP_DEBUGGER_DATABASE_URL` and `config.toml` with zero-config fallback to local SQLite.
46
+ - Relational schemas for `sessions`, `messages`, `steps`, `agents`, `attributions`, `tools`, `errors`, and `replays`.
47
+
48
+ ---
49
+
50
+ ## [0.1.1] — 2026-06-29
51
+
52
+ ### Added
53
+ - Created programmatically generated terminal demo GIF and embedded in README.
54
+ - Added scripts/generate_demo_gif.py.
55
+
56
+ ### Fixed
57
+ - Fixed command prompt encoding and icon mapping issues for Windows environment.
58
+ - Resolved PyPI release duplicate release issue by bumping to 0.1.1.
59
+
10
60
  ## [0.1.0] — 2026-06-29
11
61
 
12
62
  Initial release. Full-featured MCP session debugger with proxy recording, inspection, validation, replay, export, and analytics.
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: mcp-debugger
3
- Version: 0.1.0
3
+ Version: 0.2.0
4
4
  Summary: Transparent proxy to debug, record, validate, and replay MCP (Model Context Protocol) sessions
5
5
  Project-URL: Homepage, https://github.com/sushant-mutnale/mcp-debugger
6
6
  Project-URL: Repository, https://github.com/sushant-mutnale/mcp-debugger
@@ -24,11 +24,15 @@ Classifier: Topic :: Software Development :: Testing
24
24
  Classifier: Topic :: System :: Monitoring
25
25
  Requires-Python: >=3.11
26
26
  Requires-Dist: aiosqlite>=0.19.0
27
+ Requires-Dist: fastapi>=0.110.0
28
+ Requires-Dist: jinja2>=3.1.0
27
29
  Requires-Dist: jsonschema>=4.0.0
28
30
  Requires-Dist: pydantic>=2.5.0
31
+ Requires-Dist: python-multipart>=0.0.9
29
32
  Requires-Dist: rich>=13.7.0
30
33
  Requires-Dist: tomli>=2.0.1; python_version < '3.11'
31
34
  Requires-Dist: typer>=0.9.0
35
+ Requires-Dist: uvicorn>=0.27.0
32
36
  Provides-Extra: dev
33
37
  Requires-Dist: hypothesis>=6.0.0; extra == 'dev'
34
38
  Requires-Dist: mypy>=1.7.0; extra == 'dev'
@@ -43,12 +47,16 @@ Provides-Extra: otlp
43
47
  Requires-Dist: opentelemetry-api>=1.20.0; extra == 'otlp'
44
48
  Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == 'otlp'
45
49
  Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'otlp'
50
+ Provides-Extra: postgres
51
+ Requires-Dist: asyncpg>=0.29.0; extra == 'postgres'
46
52
  Description-Content-Type: text/markdown
47
53
 
48
54
  # mcp-debugger
49
55
 
50
56
  > Transparent proxy to **debug, record, validate, and replay** MCP (Model Context Protocol) sessions.
51
57
 
58
+ ![mcp-debugger demo](https://raw.githubusercontent.com/sushant-mutnale/mcp-debugger/main/docs/demo.gif)
59
+
52
60
  [![PyPI version](https://img.shields.io/pypi/v/mcp-debugger.svg)](https://pypi.org/project/mcp-debugger/)
53
61
  [![CI](https://github.com/sushant-mutnale/mcp-debugger/actions/workflows/ci.yml/badge.svg)](https://github.com/sushant-mutnale/mcp-debugger/actions/workflows/ci.yml)
54
62
  [![Python versions](https://img.shields.io/pypi/pyversions/mcp-debugger.svg)](https://pypi.org/project/mcp-debugger/)
@@ -63,11 +71,17 @@ Description-Content-Type: text/markdown
63
71
  |---|---|
64
72
  | 🔍 **Record** | Capture every JSON-RPC message between an MCP client and server |
65
73
  | 📋 **Inspect** | Browse messages with syntax-highlighted, formatted terminal output |
74
+ | 🌐 **Web UI** | Visual interface for managing and inspecting recorded MCP sessions in the browser |
75
+ | 🎯 **Causal Attribution** | Pinpoint failure boundaries (`agent`, `tool`, `protocol`) and isolate Point-of-Commitment via counterfactual step ablation |
76
+ | 🤖 **Multi-Agent Trees** | Relational hierarchy trees and inter-agent handoff tracking with context state diffs |
77
+ | 🛡️ **CI/CD Quality Gates** | Automated test gates with deterministic exit codes, SARIF v2.1.0, and JUnit XML exporters |
78
+ | 💰 **Cost Attribution** | Per-step and per-agent token/dollar accounting with anomaly and budget exceedance flags |
66
79
  | ✅ **Validate** | Check MCP protocol compliance — handshake order, method names, schemas |
67
80
  | 🔄 **Replay** | Regression-test server changes by replaying recorded sessions |
68
81
  | 📊 **Stats** | Visualise tool usage, latency trends, and error rates |
69
82
  | 🔀 **Compare** | Delta reports between two sessions (latency, errors, tool calls) |
70
- | 📤 **Export** | JSON, Markdown, or OpenTelemetry (OTLP) traces |
83
+ | 📤 **Export** | JSON, Markdown, OpenTelemetry (OTLP), SARIF, or JUnit XML reports |
84
+ | 🗄️ **Team Storage** | Zero-config local SQLite with optional PostgreSQL backend (`asyncpg`) |
71
85
  | ⚙️ **Config** | Persistent user preferences — aliases, timeouts, defaults |
72
86
  | 🩺 **Doctor** | Environment diagnostics — Python version, SQLite, Node.js, paths |
73
87
  | 🚀 **Local-first** | No cloud, no signup — all data stays on your machine |
@@ -80,10 +94,14 @@ Description-Content-Type: text/markdown
80
94
  pip install mcp-debugger
81
95
  ```
82
96
 
83
- With optional OpenTelemetry (OTLP) export support:
97
+ Optional extensions:
84
98
 
85
99
  ```bash
100
+ # OpenTelemetry (OTLP) export
86
101
  pip install "mcp-debugger[otlp]"
102
+
103
+ # PostgreSQL team storage backend
104
+ pip install "mcp-debugger[postgres]"
87
105
  ```
88
106
 
89
107
  **Requirements:** Python 3.11+, Node.js (for `npx`-based MCP servers)
@@ -126,10 +144,37 @@ mcp-debugger validate --server "npx -y @modelcontextprotocol/server-filesystem /
126
144
  mcp-debugger replay 1 --server "npx -y @modelcontextprotocol/server-filesystem /tmp"
127
145
  ```
128
146
 
129
- ### 6. Export to Markdown
130
-
147
+ ### 6. Export to Markdown, SARIF, or JUnit
131
148
  ```bash
132
149
  mcp-debugger export 1 --format markdown --output session-report.md
150
+ mcp-debugger export 1 --sarif code-scanning.sarif
151
+ ```
152
+
153
+ ### 7. Inspect Multi-Agent Hierarchy & Handoffs
154
+ ```bash
155
+ # Visual agent delegation tree
156
+ mcp-debugger agents 1
157
+
158
+ # Inter-agent handoffs table with state diffs
159
+ mcp-debugger agents 1 --handoffs
160
+ ```
161
+
162
+ ### 8. Causal Failure Attribution
163
+ ```bash
164
+ # Isolate Point-of-Commitment and root cause
165
+ mcp-debugger attribute 1
166
+ ```
167
+
168
+ ### 9. Statistical Dashboard & Token Costs
169
+ ```bash
170
+ # View tool usage, latency sparklines, and per-agent token costs
171
+ mcp-debugger stats 1
172
+ ```
173
+
174
+ ### 10. Automated CI/CD Quality Gates
175
+ ```bash
176
+ # Enforce compliance gates with budget thresholds and test reports
177
+ mcp-debugger ci 1 --max-cost 2.50 --junit junit-report.xml
133
178
  ```
134
179
 
135
180
  ---
@@ -164,6 +209,7 @@ Every message between Claude and your server is now recorded transparently.
164
209
  | Document | Description |
165
210
  |---|---|
166
211
  | [Command Reference](docs/commands.md) | Every CLI command with all options and examples |
212
+ | [Web UI](docs/web-ui.md) | How to use the built-in browser interface |
167
213
  | [Architecture](docs/architecture.md) | How it works — components, data flow, sequence diagrams |
168
214
  | [Tutorials](docs/tutorials.md) | Step-by-step workflows for common use cases |
169
215
  | [Configuration](docs/config.md) | All config keys, defaults, and examples |
@@ -2,6 +2,8 @@
2
2
 
3
3
  > Transparent proxy to **debug, record, validate, and replay** MCP (Model Context Protocol) sessions.
4
4
 
5
+ ![mcp-debugger demo](https://raw.githubusercontent.com/sushant-mutnale/mcp-debugger/main/docs/demo.gif)
6
+
5
7
  [![PyPI version](https://img.shields.io/pypi/v/mcp-debugger.svg)](https://pypi.org/project/mcp-debugger/)
6
8
  [![CI](https://github.com/sushant-mutnale/mcp-debugger/actions/workflows/ci.yml/badge.svg)](https://github.com/sushant-mutnale/mcp-debugger/actions/workflows/ci.yml)
7
9
  [![Python versions](https://img.shields.io/pypi/pyversions/mcp-debugger.svg)](https://pypi.org/project/mcp-debugger/)
@@ -16,11 +18,17 @@
16
18
  |---|---|
17
19
  | 🔍 **Record** | Capture every JSON-RPC message between an MCP client and server |
18
20
  | 📋 **Inspect** | Browse messages with syntax-highlighted, formatted terminal output |
21
+ | 🌐 **Web UI** | Visual interface for managing and inspecting recorded MCP sessions in the browser |
22
+ | 🎯 **Causal Attribution** | Pinpoint failure boundaries (`agent`, `tool`, `protocol`) and isolate Point-of-Commitment via counterfactual step ablation |
23
+ | 🤖 **Multi-Agent Trees** | Relational hierarchy trees and inter-agent handoff tracking with context state diffs |
24
+ | 🛡️ **CI/CD Quality Gates** | Automated test gates with deterministic exit codes, SARIF v2.1.0, and JUnit XML exporters |
25
+ | 💰 **Cost Attribution** | Per-step and per-agent token/dollar accounting with anomaly and budget exceedance flags |
19
26
  | ✅ **Validate** | Check MCP protocol compliance — handshake order, method names, schemas |
20
27
  | 🔄 **Replay** | Regression-test server changes by replaying recorded sessions |
21
28
  | 📊 **Stats** | Visualise tool usage, latency trends, and error rates |
22
29
  | 🔀 **Compare** | Delta reports between two sessions (latency, errors, tool calls) |
23
- | 📤 **Export** | JSON, Markdown, or OpenTelemetry (OTLP) traces |
30
+ | 📤 **Export** | JSON, Markdown, OpenTelemetry (OTLP), SARIF, or JUnit XML reports |
31
+ | 🗄️ **Team Storage** | Zero-config local SQLite with optional PostgreSQL backend (`asyncpg`) |
24
32
  | ⚙️ **Config** | Persistent user preferences — aliases, timeouts, defaults |
25
33
  | 🩺 **Doctor** | Environment diagnostics — Python version, SQLite, Node.js, paths |
26
34
  | 🚀 **Local-first** | No cloud, no signup — all data stays on your machine |
@@ -33,10 +41,14 @@
33
41
  pip install mcp-debugger
34
42
  ```
35
43
 
36
- With optional OpenTelemetry (OTLP) export support:
44
+ Optional extensions:
37
45
 
38
46
  ```bash
47
+ # OpenTelemetry (OTLP) export
39
48
  pip install "mcp-debugger[otlp]"
49
+
50
+ # PostgreSQL team storage backend
51
+ pip install "mcp-debugger[postgres]"
40
52
  ```
41
53
 
42
54
  **Requirements:** Python 3.11+, Node.js (for `npx`-based MCP servers)
@@ -79,10 +91,37 @@ mcp-debugger validate --server "npx -y @modelcontextprotocol/server-filesystem /
79
91
  mcp-debugger replay 1 --server "npx -y @modelcontextprotocol/server-filesystem /tmp"
80
92
  ```
81
93
 
82
- ### 6. Export to Markdown
83
-
94
+ ### 6. Export to Markdown, SARIF, or JUnit
84
95
  ```bash
85
96
  mcp-debugger export 1 --format markdown --output session-report.md
97
+ mcp-debugger export 1 --sarif code-scanning.sarif
98
+ ```
99
+
100
+ ### 7. Inspect Multi-Agent Hierarchy & Handoffs
101
+ ```bash
102
+ # Visual agent delegation tree
103
+ mcp-debugger agents 1
104
+
105
+ # Inter-agent handoffs table with state diffs
106
+ mcp-debugger agents 1 --handoffs
107
+ ```
108
+
109
+ ### 8. Causal Failure Attribution
110
+ ```bash
111
+ # Isolate Point-of-Commitment and root cause
112
+ mcp-debugger attribute 1
113
+ ```
114
+
115
+ ### 9. Statistical Dashboard & Token Costs
116
+ ```bash
117
+ # View tool usage, latency sparklines, and per-agent token costs
118
+ mcp-debugger stats 1
119
+ ```
120
+
121
+ ### 10. Automated CI/CD Quality Gates
122
+ ```bash
123
+ # Enforce compliance gates with budget thresholds and test reports
124
+ mcp-debugger ci 1 --max-cost 2.50 --junit junit-report.xml
86
125
  ```
87
126
 
88
127
  ---
@@ -117,6 +156,7 @@ Every message between Claude and your server is now recorded transparently.
117
156
  | Document | Description |
118
157
  |---|---|
119
158
  | [Command Reference](docs/commands.md) | Every CLI command with all options and examples |
159
+ | [Web UI](docs/web-ui.md) | How to use the built-in browser interface |
120
160
  | [Architecture](docs/architecture.md) | How it works — components, data flow, sequence diagrams |
121
161
  | [Tutorials](docs/tutorials.md) | Step-by-step workflows for common use cases |
122
162
  | [Configuration](docs/config.md) | All config keys, defaults, and examples |
@@ -11,6 +11,7 @@ To maintain transparency and ensure pipes are not polluted, the codebase adheres
11
11
  - **Logger Instantiation**: Instantiated at module level using:
12
12
  ```python
13
13
  import logging
14
+
14
15
  logger = logging.getLogger(__name__)
15
16
  ```
16
17
  - **Stream Isolation**: