lda-wf/docs/historical/superpowers/plans/2026-05-25-stateful-transparent-proxy.md

Stateful Transparent Proxy Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Preserve one upstream MCP session for visible proxy operations made by one connected downstream client, while documenting that generic upstream list/resource notifications are still not relayed.

Architecture: The workflow execution pool already owns background/offline sessions. The transparent proxy should use FastMCP's StatefulProxyClient, which is designed for Playwright-like upstreams and scopes reuse to one downstream MCP session. This slice does not unify interactive proxy sessions with deployment runtimes and does not implement arbitrary notification rebroadcast.

Tech Stack: Python 3.14, FastMCP StatefulProxyClient and FastMCPProxy, pytest fixture MCP server, ruff, basedpyright.

---

Task 1: Prove Stateful Proxy Behavior

Files:

• Modify: tests/fixtures/mcp_echo_server.py

• Modify: tests/wf_mcp/test_proxy.py

• Modify: tests/wf_mcp/test_protocol_relay.py

• Add fixture tools that store and read a value in the upstream server process.

• Add a proxy test that writes the value through one proxied request and reads it through another request in the same downstream client session.

• Change protocol-relay coverage to assert that tools/list_changed, resources/list_changed, prompts/list_changed, and resources/updated are not yet relayed. Keep string-valued logging forwarding as a strict expected-failure tripwire because the installed FastMCP StatefulProxyClient handler currently assumes mapping-valued MCP log data.

• Run the focused tests and confirm they fail before proxy construction changes.

Task 2: Use FastMCP Stateful Proxy Sessions

Files:

• Modify: src/wf_mcp/proxy/mounts.py

• Replace create_proxy(Client(...)) with StatefulProxyClient(...) and FastMCPProxy(client_factory=client.new_stateful, ...).

• Preserve the existing ProxyNamespace and ResourceLinkNamespace transforms exactly as mounted-provider output transforms.

• Add a docstring/comment stating that FastMCP owns the interactive session lifecycle and this is intentionally separate from offline workflow execution sessions.

Task 3: Verification

Files:

• Test: tests/wf_mcp/test_proxy.py

• Test: tests/wf_mcp/test_protocol_relay.py

• Run focused proxy/protocol tests.

• Run uv run pytest -q.

• Run uvx ruff check.

• Run uv run basedpyright --level error.

Scope Boundary

• Interactive visible proxy calls share state within one downstream MCP client session.
• Deployment execution continues to use the owned runtime pool because scheduled/background runs may exist without a downstream client session.
• Generic upstream notification relay remains separate work. FastMCP's stateful path is intended to forward logs/progress/elicitation, but string-valued MCP log data currently exposes an upstream FastMCP handler bug and remains documented with an expected-failure test.