MCPHawk 1.0: DevTools for MCP - #6
Merged
Merged
Conversation
Rebuild MCPHawk around one shared core for the 2026-07-28 spec: - store: sessions/exchanges/messages schema (WAL, multi-process), recorder with request/response pairing, multi round-trip chains, cancellation and identity from both the initialize handshake and modern _meta - capture: stdio shim (wrap), recording reverse proxy (incl. legacy HTTP+SSE endpoint rewriting), rewritten passive sniffer with TCP ordering and an incremental HTTP/1.x + SSE parser - install/uninstall for Claude Desktop, Claude Code, Cursor and VS Code with backups and structural undo; likely-OAuth remote servers are skipped - analysis: context cost, problems (errors, hung, slow, loops), spec lint per protocol era, tool drift between sessions - web API + live updates by tailing the DB; MCPHawk MCP server with six read-only tools returning capped summaries and deep links - secrets masked before they are written - drop the old logger/sniffer/wrapper/web modules and their tests
Replay re-sends a (possibly edited) client request to the same server over stdio or Streamable HTTP, performing the legacy handshake when needed, and records it as its own session for comparison. Refuses requests or commands containing masked secrets. Mutating API calls now require an X-MCPHawk header and a localhost Host, blocking cross-site requests and DNS rebinding.
…pare, setup Rebuilt the Vue app around the v1 API: a DevTools-style waterfall of every call in a run across servers, a detail drawer with rendered tool results, JSON tree, headers, multi round-trip chains and replay, plus context cost, problems, session comparison and a setup page that dry-runs install. Keeps the MCPHawk logo and takes the accent colour from it; fonts are bundled locally. Drops Tailwind, Pinia, axios and headlessui. Also: - pair responses recorded before their request (stdio pumps race) - recognise the v0.x 'mcphawk wrap <cmd>' syntax in install/uninstall - name version-titled client processes (Claude Code) by argv[0] - replace the old examples with a demo that drives three SDK servers
- version 1.0.0, SPDX license metadata, classifiers incl. Python 3.14 - enforce 85% coverage via coverage fail_under - CI: test Python 3.10-3.14, Node 22, check the committed UI build is current - Makefile targets for the new test layout, demo and build - README rewritten for v1, CHANGELOG, new screenshot - keep 'mcphawk web' as a hidden alias of 'mcphawk up'
Runs are now computed at read time: one client's sessions across all its servers (HTTP sessions join the same client's process group), split after 5 minutes without a call. Run keys are <client>@<start> and stay stable. Problems and context cost for a run only count calls inside its window. - sessions.run_key is now client_key (which client process); runs.py owns grouping; new list_runs MCP tool; UI shows 'Agent runs' with client labels (Claude Code, Cursor, ...) and time ranges - mcphawk wrap forwards traffic unchanged if recording fails (bad DB, schema mismatch, disk full) instead of taking the server down - install output says what happens to each server, summarises before asking, and shows paths relative to ~ - demo: a second, later task to show separate runs
- README leads with a one-minute setup (real install output), a section on what agent runs are, and one short section plus screenshot per feature (timeline, inspector/replay, context cost, problems, compare, agent access); images live in docs/images - Setup page leads with which of your servers are recorded, uses client product names and plain status text (ClientTable component) - cost findings format token counts with thousands separators
mcphawk up --otlp streams what MCPHawk records to any OTLP backend (Grafana, Datadog, Honeycomb, ...) using the OpenTelemetry semantic conventions for MCP, configured by the standard OTEL_* variables: - metrics: mcp.client.operation.duration (requests, failures by error.type, latency) plus mcphawk.tool.result/definition.tokens - logs: one record per MCP message, linked to its call's span; payloads only with --otlp-payloads (masked, capped) - traces: one span per call; joins the client's trace when it sends a traceparent in _meta, otherwise one trace per agent run with a root span; multi round-trip retries nest under the first call - /metrics Prometheus endpoint with the same names and labels - mcphawk export --otlp for past runs or sessions - Grafana dashboard in examples/grafana, checked against /metrics - optional extra: pip install 'mcphawk[otel]' Requested on r/mcp: ship MCP client-server logs and request/failure metrics to Grafana/Datadog.
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #6 +/- ##
===========================================
+ Coverage 84.50% 99.22% +14.72%
===========================================
Files 11 34 +23
Lines 1226 3111 +1885
===========================================
+ Hits 1036 3087 +2051
+ Misses 190 24 -166
Flags with carried forward coverage won't be shown. Click here to find out more.
🚀 New features to boost your workflow:
|
- pin ruff==0.16.8 in requirements-dev.txt and install that exact version in the CI lint job so local and CI lint agree - fix RUF059 (unused unpacked variables) in three tests - remove mcphawk/tui/widgets/stats_chart.py, a 0.x leftover committed by accident, and ignore mcphawk/tui/
…WK_URL Found by a smoke test of the packaged wheel: uninstall printed restored servers with a '+', and 'mcphawk mcp' links point at port 8484 unless MCPHAWK_URL says where the UI runs.
The release workflow already requests id-token: write; the upload now uses pypa/gh-action-pypi-publish, so no PyPI token is stored in the repo. Also bump softprops/action-gh-release to v2.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
MCPHawk 1.0: DevTools for MCP
See every call your agent makes, across every MCP server, in one place. Then let your agent see it too.
One command setup.
mcphawk installroutes every MCP server of Claude Desktop, Claude Code, Cursor and VS Code through MCPHawk, with a backup of each config and a cleanmcphawk uninstall.Agent runs. Everything a client does across all its servers lands on one waterfall timeline, split into runs by task, with status, latency and result size for every call.
Call inspector and replay. Rendered tool results, full request and response, headers and shareable links. Edit any call and replay it against the real server.
Context cost. See how many tokens each server and tool adds to every turn, which tools never get used and which results flood the context window.
Problems. JSON-RPC errors, tool failures, unanswered and slow calls, agent loops and spec violations, most severe first.
Built for MCP 2026-07-28. First class support for the stateless spec (multi round-trip requests,
server/discover,Mcp-Methodheaders, cache hints) and the classic handshake era, with spec lint for whichever version a session speaks.Compare. Tools added, removed or changed between two versions of a server, including the token delta, plus how each call behaved.
MCPHawk is an MCP server. Seven read-only tools let Claude Code find failing calls and context hogs on its own and link you straight to them.
OpenTelemetry. Stream metrics, logs and traces over OTLP to Grafana, Datadog or any backend, following the OpenTelemetry conventions for MCP. Includes a Prometheus
/metricsendpoint and a ready made Grafana dashboard.Capture anywhere. A stdio wrapper, an HTTP proxy for local and remote servers including HTTPS, or passive sniffing with zero config changes.
Private by default. Everything stays in a local database, secrets are masked before they are stored and the UI only listens on localhost.
Breaking changes
~/.mcphawk/) and schema; captures from 0.x are not migratedmcphawk webis nowmcphawk up(the old name still works)mcphawk wrap <command>entries keep working and are picked up byinstallanduninstall