another bug report has hit the fastmcp
also docs. codex tried a hell ton, and then deleted them all.
This commit is contained in:
@@ -0,0 +1,175 @@
|
||||
# wf_mcp Proxy Reality And Roadmap
|
||||
|
||||
This document is the current practical position for `wf-mcp` proxy work after
|
||||
the first live protocol investigations. It is intentionally more opinionated
|
||||
than [`mcp_protocol_proxy_inventory.md`](mcp_protocol_proxy_inventory.md),
|
||||
which remains the fact log.
|
||||
|
||||
## Current Position
|
||||
|
||||
`wf-mcp` should keep using FastMCP as its proxy foundation.
|
||||
|
||||
FastMCP is already giving us substantial value:
|
||||
|
||||
- ordinary proxied tools work
|
||||
- listed resources and resource templates work
|
||||
- resource reads through namespaced URIs work
|
||||
- proxy mounting, transforms, and client/server plumbing are real leverage
|
||||
- selected advanced forwarding paths already exist upstream, including roots,
|
||||
sampling, elicitation, logging, and progress
|
||||
|
||||
But FastMCP proxying is not currently a fully transparent MCP relay. We should
|
||||
not block the rest of the product on making it one.
|
||||
|
||||
## What Works Today
|
||||
|
||||
### Proxy Surface
|
||||
|
||||
- normal `tools/list` and `tools/call`
|
||||
- tool title, description, and JSON-schema metadata
|
||||
- listed resource and resource-template namespacing
|
||||
- namespaced resource reads
|
||||
- current dotted tool names and slash-separated resource URI namespaces
|
||||
|
||||
### Local wf-mcp Behavior
|
||||
|
||||
- local admin reload emits downstream list-changed notifications for the current
|
||||
request session
|
||||
- internal event projection for local tool/resource/prompt changes exists
|
||||
- unchanged mounted connections are reused across reload through
|
||||
`ProxyMountRegistry`
|
||||
|
||||
### Local Workarounds We Intentionally Own
|
||||
|
||||
- tool-returned `ResourceLink` URIs are rewritten by
|
||||
`wf_mcp.proxy_results`
|
||||
|
||||
This workaround is worth owning because it is bounded, local, well-tested, and
|
||||
deletable if FastMCP gains a general result-transform hook later.
|
||||
|
||||
## Confirmed Gaps
|
||||
|
||||
### 1. Generic upstream notifications are not relayed downstream
|
||||
|
||||
Confirmed on 2026-05-16 with fixture-backed tests and the runnable
|
||||
`docs/f/` repros.
|
||||
|
||||
The upstream-side client sees:
|
||||
|
||||
- `notifications/tools/list_changed`
|
||||
- `notifications/resources/list_changed`
|
||||
- `notifications/prompts/list_changed`
|
||||
- `notifications/resources/updated`
|
||||
- `notifications/message`
|
||||
|
||||
The downstream client connected through the proxy sees none of them.
|
||||
|
||||
This is currently tracked upstream as:
|
||||
|
||||
- `PrefectHQ/fastmcp#4161`
|
||||
|
||||
The closest related upstream issue found so far is:
|
||||
|
||||
- `PrefectHQ/fastmcp#4124`
|
||||
- downstream cancellation is not propagated upstream
|
||||
|
||||
Together, these suggest FastMCP's proxy layer forwards selected protocol
|
||||
features but is not yet a general bidirectional protocol relay.
|
||||
|
||||
### 2. Tool-returned ResourceLinks were not rewritten
|
||||
|
||||
FastMCP namespaced listed resources correctly, but ordinary `ResourceLink`
|
||||
content inside proxied tool results kept raw upstream URIs.
|
||||
|
||||
This is currently tracked upstream as:
|
||||
|
||||
- `PrefectHQ/fastmcp#4154`
|
||||
|
||||
We already have the local workaround described above.
|
||||
|
||||
### 3. Session resource behavior is still unresolved
|
||||
|
||||
The Everything server's session resource returned by
|
||||
`gzip-file-as-resource` was not readable through the proxy during the live
|
||||
probe. Direct reading also failed in that Codex session, so this is not yet
|
||||
classified as a proxy bug.
|
||||
|
||||
### 4. Tasks remain unsupported
|
||||
|
||||
Task-required tools are discoverable but not usable through our current surface.
|
||||
This is a real protocol-support gap, not an ordinary tool-call issue.
|
||||
|
||||
## What Is Probably Not Worth Owning Yet
|
||||
|
||||
Do **not** rush to implement a custom full protocol relay for:
|
||||
|
||||
- generic upstream notification forwarding
|
||||
- cancellation propagation
|
||||
- resource subscription ownership
|
||||
- task execution
|
||||
- broad replacement of FastMCP proxy internals
|
||||
|
||||
Those are cross-cutting lifecycle problems. They touch request identity,
|
||||
session ownership, namespace projection, reconnect behavior, and possibly
|
||||
transport-specific semantics. A small local workaround here would likely turn
|
||||
into a second proxy framework by accident.
|
||||
|
||||
## Decision Rule For Local Workarounds
|
||||
|
||||
Own a local workaround only when all are true:
|
||||
|
||||
1. the gap blocks near-term product work
|
||||
2. the behavior boundary is narrow and testable
|
||||
3. the workaround can live in one isolated module family
|
||||
4. deleting it later will be cheap if upstream support lands
|
||||
|
||||
`ResourceLink` rewriting passed that test.
|
||||
|
||||
Generic notification relay does not pass it yet.
|
||||
|
||||
## Roadmap From Here
|
||||
|
||||
### Continue Building Now
|
||||
|
||||
These areas do not require a perfect transparent proxy:
|
||||
|
||||
1. capability and source inventory surfaced clearly to users and LLM clients
|
||||
2. admin/control UX over configured sources
|
||||
3. workflow artifacts, deployments, and dependency validation
|
||||
4. `wf.std` and `wf.mcp` authoring/runtime affordances
|
||||
5. LLM-facing workflow construction using existing sources
|
||||
|
||||
These keep compounding even if upstream proxy transparency remains imperfect for
|
||||
a while.
|
||||
|
||||
### Keep Investigating Selectively
|
||||
|
||||
Continue protocol investigation only where it changes near-term design:
|
||||
|
||||
1. which upstream capabilities are safe to expose publicly
|
||||
2. what per-source capability metadata the admin surface should show
|
||||
3. whether session resources matter to workflows we actually want soon
|
||||
4. whether a specific advanced FastMCP forwarding path is needed by a real
|
||||
source before we depend on it
|
||||
|
||||
### Revisit Later
|
||||
|
||||
Come back to deeper proxy work when one of these becomes true:
|
||||
|
||||
- FastMCP ships official support we can adopt
|
||||
- a concrete user-facing workflow needs the missing protocol feature
|
||||
- the missing feature becomes small enough to isolate cleanly
|
||||
|
||||
## Near-Term Recommended Next Work
|
||||
|
||||
The best next repo work is **not** another proxy internals expedition.
|
||||
|
||||
Recommended order:
|
||||
|
||||
1. expose richer source/capability inventory through the public/admin surfaces
|
||||
2. keep per-source protocol support visible rather than pretending all mounted
|
||||
sources are equivalent
|
||||
3. continue the workflow/platform layer that consumes those sources
|
||||
|
||||
That preserves the long-term proxy ambition without letting it dominate the
|
||||
project before the upstream foundation is ready.
|
||||
Reference in New Issue
Block a user