Skip to content

ROADMAP.md

Latest commit

 

History

History
273 lines (208 loc) · 8.6 KB

ROADMAP.md

File metadata and controls

273 lines (208 loc) · 8.6 KB
Raw

proxy-mcp Roadmap

Last updated: 2026-04-19
Current shipped baseline: v2.2.0 (commit e93804f)

Current Baseline (Already Shipped)

These are implemented and in the repo now:

  • Optional persistent session capture (preview and full body modes)
  • Session querying over indexed persisted traffic
  • HAR export from full session or filtered subset
  • Session recovery flow for truncated/unclean writes
  • Session MCP tools:
    • proxy_session_start
    • proxy_session_stop
    • proxy_session_status
    • proxy_list_sessions
    • proxy_get_session
    • proxy_query_session
    • proxy_search_session_bodies
    • proxy_get_session_exchange
    • proxy_export_har
    • proxy_import_har
    • proxy_replay_session
    • proxy_delete_session
    • proxy_session_recover
  • Session resources/templates:
    • proxy://sessions
    • proxy://sessions/{session_id}/summary
    • proxy://sessions/{session_id}/timeline
    • proxy://sessions/{session_id}/findings
  • Browser discovery resources:
    • proxy://browser/primary
    • proxy://browser/targets

Roadmap Principles

  • Scraping and reverse-engineering utility first
  • MCP-native interfaces first (tools/resources/templates)
  • Query-first UX for AI agents (avoid huge payload dumping)
  • Crash resilience and operability over “nice to have” UI polish
  • No default privacy-redaction workflow in roadmap scope

Phase 1 (High ROI / Next)

1) Replay Engine (proxy_replay_session) — SHIPPED in 2.x

Implemented at src/tools/sessions.ts (proxy_replay_session). Ships with:

  • Filter-based selection (hostname_contains, url_contains, status_code, exchange_ids)
  • mode: "dry_run" (plan-only, no outbound) and mode: "execute"
  • target_base_url override (redirect replay to staging/local)
  • limit / offset / timeout_ms controls
  • Per-request result capture on execute

Deferred (not blocking POC workflows):

  • proxy_replay_status streaming status (currently returns all results synchronously)
  • proxy://replay/{replay_id}/summary resource (dedicated replay run tracking)
  • Variable substitution ({timestamp}, {nonce}, captured token refs) — currently replays recorded bodies verbatim

2) Session Diffing (proxy_diff_sessions)

Problem solved:

  • Quickly identify what changed between “works” and “fails” captures.

Planned interface additions:

  • Tool: proxy_diff_sessions
  • Resource template: proxy://sessions/{session_id}/diff/{other_id}

Functional requirements:

  • Compare headers, query params, status codes, body field deltas
  • Volatility scoring for candidate signature/auth fields
  • Endpoint-level and field-level diff summaries

Edge cases/failure modes:

  • Different request ordering and different request counts
  • Dynamic IDs/timestamps creating noisy diffs

Acceptance criteria:

  • Produces endpoint diff summary and top changed fields
  • Can suppress known dynamic fields via ignore patterns

Effort: M
Dependencies: replay + query output schema alignment

3) Decoder Pipeline (proxy_decode_exchange)

Problem solved:

  • Make encoded/compressed payloads searchable and understandable.

Planned interface additions:

  • Tool: proxy_decode_exchange
  • Tool: proxy_list_decoders

Functional requirements:

  • Built-in decoders: gzip, br, deflate, base64-json, msgpack
  • Plugin decoder interface for protobuf/custom payloads
  • Store decoded preview artifacts per exchange

Edge cases/failure modes:

  • Binary blobs mistaken for text
  • Decoder false positives

Acceptance criteria:

  • Decoded views appear in tool output for supported formats
  • Decoder failures are explicit and non-fatal

Effort: M
Dependencies: persisted exchange retrieval (already shipped)

Phase 2 (Coverage Expansion)

4) WebSocket/SSE Capture

Problem solved:

  • Cover real-time targets that do not expose key data via plain HTTP.

Planned interface additions:

  • Tool: proxy_list_ws_streams
  • Tool: proxy_get_ws_frames
  • Resource template: proxy://sessions/{session_id}/ws

Functional requirements:

  • Capture WS open/close events and frame metadata
  • Capture SSE streams with event segmentation
  • Index by host/path/channel and searchable payload snippets

Acceptance criteria:

  • WS/SSE streams visible in session summaries
  • Query by stream/channel returns frame/event timelines

Effort: L
Dependencies: capture layer extensions in proxy engine

5) Flow Template Generation

Problem solved:

  • Convert captured traffic into reusable execution templates.

Planned interface additions:

  • Tool: proxy_generate_flow_template
  • Resource template: proxy://sessions/{session_id}/templates

Functional requirements:

  • Build step graph from observed call dependencies
  • Mark dynamic placeholders automatically
  • Export templates as JSON for replay tool consumption

Acceptance criteria:

  • One-click template generated from selected request slice
  • Template replays successfully with variable input map

Effort: M
Dependencies: replay engine, session indexing

6) CDP Convenience Bridge — OBSOLETED in 2.0.0

Superseded by the cloakbrowser + Playwright rewrite. The browser interceptor now exposes a Playwright Page directly — no external CDP attach is needed. If external CDP/Playwright attach becomes a use case again, a future tool could launch cloakbrowser with --remote-debugging-port in args.

Phase 3 (Reliability + Scale)

7) Durability/Checkpoint Upgrade

Problem solved:

  • Reduce recovery time and data loss risk for long sessions.

Planned interface additions:

  • Tool: proxy_session_checkpoint
  • Tool: proxy_session_verify_integrity

Functional requirements:

  • Chunked append logs with checksums
  • Explicit checkpoint markers
  • Faster startup index rebuild path

Acceptance criteria:

  • Recovery handles very large sessions predictably
  • Integrity verification reports corruption boundaries

Effort: M
Dependencies: current session-store internals

8) Distributed Replay Workers

Problem solved:

  • Scale replay beyond one process.

Planned interface additions:

  • Tool: proxy_replay_enqueue
  • Tool: proxy_replay_worker_status

Functional requirements:

  • Queue-backed replay jobs
  • Multiple workers consuming common jobs
  • Aggregate run metrics and failure reporting

Acceptance criteria:

  • Multi-worker runs complete with deterministic job accounting

Effort: L
Dependencies: replay engine stable

9) Replay Parity Verification

Problem solved:

  • Ensure replayed flows still match expected semantics.

Planned interface additions:

  • Tool: proxy_replay_verify
  • Resource: proxy://replay/{replay_id}/parity

Functional requirements:

  • Compare replay outputs to baseline by schema/key fields
  • Report drift severity by endpoint

Acceptance criteria:

  • Produces pass/fail and drift summaries for a replay run

Effort: M
Dependencies: replay engine + diff logic

Prioritized Backlog

Priority Feature Phase Effort Dependencies Status
P1 Replay engine 1 M Session query (shipped) Shipped (v2.x, minus replay-status + variable substitution)
P2 Session diffing 1 M Replay/query schema Planned
P3 Decoder pipeline 1 M Persisted exchange access (shipped) Planned
P4 WebSocket/SSE capture 2 L Capture layer extensions Planned
P5 Flow template generation 2 M Replay + indexing Planned
P6 CDP convenience bridge 2 S CDP resources (shipped) Planned
P7 Durability checkpoints 3 M Session-store internals Planned
P8 Distributed replay workers 3 L Replay engine stable Planned
P9 Replay parity verification 3 M Replay + diff logic Planned

Milestones

  • M1: Replay + diff usable for one real target flow
  • M2: Decoder + WS/SSE coverage for modern apps
  • M3: Durability and scale features production-ready

Testing Strategy by Phase

Phase 1:

  • Replay correctness tests (ordering, retries, rate limits)
  • Diff regression fixtures (known changed/unchanged captures)
  • Decoder fixture corpus tests (valid/invalid payloads)

Phase 2:

  • WS/SSE capture integration tests with synthetic stream server
  • Template generation round-trip tests (capture -> template -> replay)
  • CDP convenience attach smoke test

Phase 3:

  • Crash-recovery stress tests on large sessions
  • Replay queue worker concurrency and idempotency tests
  • Parity verification tests against baseline fixtures

Issue Mapping (Execution Discipline)

Create one GitHub issue per roadmap feature with:

  • Problem statement
  • Public MCP interface additions
  • Data/storage impacts
  • Edge cases and failure modes
  • Acceptance criteria
  • Test plan
  • Dependencies/blockers

Issue naming convention:

  • [roadmap][phase-N] <feature-name>

Example:

  • [roadmap][phase-1] replay-engine
  • [roadmap][phase-1] session-diff