53 lines
3.1 KiB
Markdown
53 lines
3.1 KiB
Markdown
# 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.
|