BitDive MCP Server

Python MCP server for BitDive trace analysis, request reproduction, and regression management.

This repository exposes BitDive monitoring and QA operations to MCP clients such as Cursor, Claude Desktop, and other agent runtimes. The implementation lives in server.py and connects to the BitDive Monitoring API while adding its own formatting, normalization, and comparison logic on top.

Use this repository from the python-mcp-server branch.

Demo

Watch the BitDive product demo on YouTube:

• https://www.youtube.com/watch?v=WqtLXcODz8I

Overview

This server is not just a thin API proxy.

It wraps BitDive API endpoints and makes them usable for agent workflows:

• compact heatmap summaries for discovery
• readable trace summaries instead of raw JSON only
• Bash and PowerShell reproduction commands from captured requests
• before/after trace comparison with payload and contract drift reporting
• SQL normalization and volatile-field filtering to reduce noisy diffs
• automatic secret redaction and chronological child-call ordering on trace paths
• test-group inspection and regression-management flows

What It Is For

Use this server when an AI agent or developer needs to:

• discover which module, service, class, or entrypoint is active
• fetch recent or historical traces
• inspect a trace without manually parsing BitDive JSON
• reproduce a captured web request locally
• compare two traces after a code change
• track how behavior evolved across multiple runs
• inspect and update BitDive test groups

Tool Inventory

The current server exposes 24 MCP tools.

Tool names follow their intent: discovery tools (you do not have an id yet) start with get_*_heatmap / list_* / find_* / search_*; inspect tools (you already have a call_id) start with get_trace*; compare tools diff traces.

Group	Tools	When to use
Discovery (heatmaps)	get_system_heatmap, get_module_heatmap, get_service_heatmap	Don't know where to look yet; find a class/method and its metrics
Discovery (calls/methods)	list_recent_calls, find_calls_by_method, search_methods, search_methods_detailed	Get call_ids or locate a method by keyword
Inspect one trace (needs call_id)	get_trace_overview, get_trace, get_trace_raw, get_trace_subtree	Read a known trace: overview → full de-noised → raw → single subtree
Compare	compare_traces, compare_traces_over_time	Before/after diff, or a chronological series
Reproduce	get_replay_command	Rebuild a curl/PowerShell command to replay a request
Utility	resolve_call_ids	Map call_ids to short Class.method names
Tests	create_test_group, list_test_groups, list_test_group_classes, list_test_group_methods, build_test_payload, delete_test_group, set_test_group_enabled, regenerate_test, get_test_results	Manage and inspect record-and-replay test groups

Typical Workflow

1. Discover — get_system_heatmap or list_recent_calls to find a method or fresh call_id.
2. Inspect — get_trace_overview for a quick tree; get_trace for full de-noised payloads (default for deep analysis).
3. Compare — compare_traces for before/after; open get_trace when the diff needs payload proof.
4. Reproduce — get_replay_command, run it, wait ~45s, then list_recent_calls again.