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.
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/.gitignore +4 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/CHANGELOG.md +50 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/PKG-INFO +52 -6
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/README.md +44 -4
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/06-production-standards.md +1 -0
- mcp_debugger-0.2.0/docs/25-90-day-plan-detailed.md +448 -0
- mcp_debugger-0.2.0/docs/adr/0001-reorder-adapters-and-hybrid-attribution.md +18 -0
- mcp_debugger-0.2.0/docs/adr/0002-trace-ingestion-and-dual-protocol.md +25 -0
- mcp_debugger-0.2.0/docs/adr/0003-multi-agent-data-model-and-packaging.md +33 -0
- mcp_debugger-0.2.0/docs/agents/domain.md +51 -0
- mcp_debugger-0.2.0/docs/agents/issue-tracker.md +50 -0
- mcp_debugger-0.2.0/docs/agents/triage-labels.md +15 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/commands.md +111 -7
- mcp_debugger-0.2.0/docs/demo.gif +0 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/replay.md +3 -2
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/tutorials.md +3 -1
- mcp_debugger-0.2.0/docs/web-ui.md +45 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/pyproject.toml +8 -1
- mcp_debugger-0.2.0/scripts/generate_demo_gif.py +387 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/scripts/test_real_servers.py +12 -12
- mcp_debugger-0.2.0/src/mcp_debugger/__init__.py +6 -0
- mcp_debugger-0.2.0/src/mcp_debugger/adapters/__init__.py +13 -0
- mcp_debugger-0.2.0/src/mcp_debugger/adapters/crewai.py +286 -0
- mcp_debugger-0.2.0/src/mcp_debugger/adapters/langchain.py +225 -0
- mcp_debugger-0.2.0/src/mcp_debugger/adapters/openai.py +192 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/analytics.py +59 -36
- mcp_debugger-0.2.0/src/mcp_debugger/attribution/__init__.py +41 -0
- mcp_debugger-0.2.0/src/mcp_debugger/attribution/ablation.py +207 -0
- mcp_debugger-0.2.0/src/mcp_debugger/attribution/classifier.py +366 -0
- mcp_debugger-0.2.0/src/mcp_debugger/attribution/cost.py +337 -0
- mcp_debugger-0.2.0/src/mcp_debugger/attribution/live.py +237 -0
- mcp_debugger-0.2.0/src/mcp_debugger/attribution/models.py +81 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/cli.py +1176 -53
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/config.py +13 -13
- mcp_debugger-0.2.0/src/mcp_debugger/exporters/__init__.py +15 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/exporters/json_exporter.py +19 -19
- mcp_debugger-0.2.0/src/mcp_debugger/exporters/junit_exporter.py +179 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/exporters/markdown_exporter.py +13 -13
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/exporters/otlp_exporter.py +160 -32
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/exporters/otlp_replay_exporter.py +32 -23
- mcp_debugger-0.2.0/src/mcp_debugger/exporters/sarif_exporter.py +204 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/protocol/error_classifier.py +77 -3
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/protocol/schemas.py +10 -9
- mcp_debugger-0.2.0/src/mcp_debugger/protocol/validator.py +728 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/proxy/stdio_proxy.py +79 -12
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/replay/__init__.py +6 -3
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/replay/diff.py +6 -5
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/replay/engine.py +28 -26
- mcp_debugger-0.2.0/src/mcp_debugger/replay/handoff.py +149 -0
- mcp_debugger-0.2.0/src/mcp_debugger/sdk/__init__.py +29 -0
- mcp_debugger-0.2.0/src/mcp_debugger/sdk/context.py +60 -0
- mcp_debugger-0.2.0/src/mcp_debugger/sdk/decorators.py +332 -0
- mcp_debugger-0.2.0/src/mcp_debugger/sdk/handoff.py +268 -0
- mcp_debugger-0.2.0/src/mcp_debugger/sdk/ingestion.py +183 -0
- mcp_debugger-0.2.0/src/mcp_debugger/storage/__init__.py +40 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/storage/database.py +676 -41
- mcp_debugger-0.2.0/src/mcp_debugger/storage/postgres.py +545 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/validate_live.py +3 -4
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/version.py +1 -1
- mcp_debugger-0.2.0/src/mcp_debugger/web/__init__.py +1 -0
- mcp_debugger-0.2.0/src/mcp_debugger/web/app.py +179 -0
- mcp_debugger-0.2.0/src/mcp_debugger/web/static/app.js +281 -0
- mcp_debugger-0.2.0/src/mcp_debugger/web/static/session.js +269 -0
- mcp_debugger-0.2.0/src/mcp_debugger/web/static/style.css +172 -0
- mcp_debugger-0.2.0/src/mcp_debugger/web/templates/base.html +61 -0
- mcp_debugger-0.2.0/src/mcp_debugger/web/templates/session_detail.html +185 -0
- mcp_debugger-0.2.0/src/mcp_debugger/web/templates/sessions.html +173 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/conftest.py +4 -3
- mcp_debugger-0.2.0/tests/test_adapters/test_crewai.py +156 -0
- mcp_debugger-0.2.0/tests/test_adapters/test_langchain.py +174 -0
- mcp_debugger-0.2.0/tests/test_adapters/test_openai.py +138 -0
- mcp_debugger-0.2.0/tests/test_attribution/test_ablation_engine.py +235 -0
- mcp_debugger-0.2.0/tests/test_attribution/test_cost.py +213 -0
- mcp_debugger-0.2.0/tests/test_attribution/test_heuristic_classifier.py +282 -0
- mcp_debugger-0.2.0/tests/test_attribution/test_live_counterfactual.py +163 -0
- mcp_debugger-0.2.0/tests/test_cli/test_agents.py +161 -0
- mcp_debugger-0.2.0/tests/test_cli/test_attribute.py +124 -0
- mcp_debugger-0.2.0/tests/test_cli/test_ci.py +291 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_cli/test_cli_edge_cases.py +462 -520
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_cli/test_export.py +2 -1
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_cli/test_inspect.py +37 -2
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_cli/test_list.py +3 -2
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_cli/test_proxy.py +2 -2
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_cli/test_replay.py +12 -11
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_cli/test_stats.py +45 -5
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_cli/test_validate.py +3 -2
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_exporters/test_json.py +2 -2
- mcp_debugger-0.2.0/tests/test_exporters/test_junit.py +243 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_exporters/test_markdown.py +1 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_exporters/test_otlp.py +216 -4
- mcp_debugger-0.2.0/tests/test_exporters/test_sarif.py +174 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_integration/test_integration.py +9 -9
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_property.py +6 -5
- mcp_debugger-0.2.0/tests/test_protocol/test_error_classifier.py +298 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_protocol/test_validator.py +253 -1
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_proxy/test_stdio_proxy.py +129 -22
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_replay/test_diff.py +2 -1
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_replay/test_engine.py +7 -6
- mcp_debugger-0.2.0/tests/test_replay/test_handoff_replay.py +148 -0
- mcp_debugger-0.2.0/tests/test_sdk/test_decorators.py +248 -0
- mcp_debugger-0.2.0/tests/test_sdk/test_handoff.py +115 -0
- mcp_debugger-0.2.0/tests/test_sdk/test_ingestion.py +131 -0
- mcp_debugger-0.2.0/tests/test_storage/test_agents_database.py +142 -0
- mcp_debugger-0.2.0/tests/test_storage/test_attribution_database.py +113 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_storage/test_database.py +3 -2
- mcp_debugger-0.2.0/tests/test_storage/test_postgres.py +174 -0
- mcp_debugger-0.2.0/tests/test_storage/test_trajectory_database.py +164 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_stress.py +5 -4
- mcp_debugger-0.1.0/docs/04-25-day-plan-detailed.md +0 -232
- mcp_debugger-0.1.0/src/mcp_debugger/__init__.py +0 -5
- mcp_debugger-0.1.0/src/mcp_debugger/exporters/__init__.py +0 -6
- mcp_debugger-0.1.0/src/mcp_debugger/protocol/validator.py +0 -471
- mcp_debugger-0.1.0/tests/__init__.py +0 -0
- mcp_debugger-0.1.0/tests/test_protocol/test_error_classifier.py +0 -142
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/CONTRIBUTING.md +0 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/LICENSE +0 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/00-project-charter.md +0 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/01-architecture-deep.md +0 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/02-data-models-detailed.md +0 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/03-database-schema.md +0 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/05-mcp-protocol-reference.md +0 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/07-glossary.md +0 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/08-faq.md +0 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/AI_INSTRUCTIONS.md +0 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/README.md +0 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/architecture.md +0 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/compatibility.md +0 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/config.md +0 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/contributing.md +0 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/diagrams/README.md +0 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/docs/faq.md +0 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/scripts/check_version.py +0 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/scripts/stress_test.py +1 -1
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/display/__init__.py +0 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/protocol/__init__.py +0 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/proxy/__init__.py +0 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/src/mcp_debugger/py.typed +0 -0
- {mcp_debugger-0.1.0/src/mcp_debugger/storage → mcp_debugger-0.2.0/tests}/__init__.py +0 -0
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/mock_servers/echo_server.py +1 -1
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_cli/test_cli_config.py +1 -1
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_config/test_config.py +2 -2
- {mcp_debugger-0.1.0 → mcp_debugger-0.2.0}/tests/test_protocol/test_schemas.py +3 -3
|
@@ -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.
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
2
|
Name: mcp-debugger
|
|
3
|
-
Version: 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
|
+

|
|
59
|
+
|
|
52
60
|
[](https://pypi.org/project/mcp-debugger/)
|
|
53
61
|
[](https://github.com/sushant-mutnale/mcp-debugger/actions/workflows/ci.yml)
|
|
54
62
|
[](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,
|
|
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
|
-
|
|
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
|
+

|
|
6
|
+
|
|
5
7
|
[](https://pypi.org/project/mcp-debugger/)
|
|
6
8
|
[](https://github.com/sushant-mutnale/mcp-debugger/actions/workflows/ci.yml)
|
|
7
9
|
[](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,
|
|
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
|
-
|
|
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 |
|