doc updates
This commit is contained in:
@@ -17,9 +17,10 @@
|
||||
`PersistentSessionFactory` exist, and config-built services use the runtime
|
||||
pool for generated workflow node execution while discovery/catalog refreshes
|
||||
still use short-lived SDK adapter sessions.
|
||||
- Unsafe raw public `call_tool` surfaces have been deleted. Remaining work starts
|
||||
at renaming the legacy `transparent_proxy` package to the clearer
|
||||
proxy/provider-layer package.
|
||||
- Unsafe raw public `call_tool` surfaces have been deleted.
|
||||
- The proxy/provider layer has been renamed to `wf_mcp.proxy`; public helper
|
||||
names now use `create_proxy_client`, `create_proxy_server`, and
|
||||
`validate_proxy_config`.
|
||||
|
||||
---
|
||||
|
||||
@@ -44,7 +45,7 @@ This is not a `wf_core` graph problem. It is an MCP runtime lifecycle problem.
|
||||
|
||||
## Current Execution Paths
|
||||
|
||||
### Transparent Proxy Path
|
||||
### Proxy Path
|
||||
|
||||
Used by directly exposed proxied MCP tools in MCP clients:
|
||||
|
||||
@@ -58,7 +59,7 @@ MCP client
|
||||
|
||||
Relevant file:
|
||||
|
||||
- `src/wf_mcp/transparent_proxy/mounts.py`
|
||||
- `src/wf_mcp/proxy/mounts.py`
|
||||
|
||||
Current behavior:
|
||||
|
||||
@@ -101,9 +102,9 @@ Current behavior:
|
||||
- Do not implement Playwright-specific hacks.
|
||||
- Do not claim notification/subscription forwarding is solved.
|
||||
- Do not delete all of `src/wf_mcp/broker` in this pass. That package still owns service/source/catalog/deployment infrastructure.
|
||||
- Do not keep `src/wf_mcp/transparent_proxy` as a long-term package name. That
|
||||
name describes a retired public mode split, not the unified server's mounted
|
||||
upstream proxy/provider layer.
|
||||
- Do not reintroduce the old `transparent_proxy` package name. It described a
|
||||
retired public mode split, not the unified server's mounted upstream
|
||||
proxy/provider layer.
|
||||
- Do not expose a bigger public broker surface while fixing this.
|
||||
|
||||
## Target Design
|
||||
@@ -202,10 +203,9 @@ Retire or hide:
|
||||
- `wf.mcp.call_tool` as planner-visible workflow helper
|
||||
- legacy `call_broker_tool` from public broker mode tests
|
||||
|
||||
### `wf_mcp.transparent_proxy`
|
||||
### `wf_mcp.proxy`
|
||||
|
||||
This package is also legacy-named. The code is still useful, but the name is
|
||||
wrong for the current architecture.
|
||||
This package owns the mounted upstream proxy/provider layer.
|
||||
|
||||
Current useful contents:
|
||||
|
||||
@@ -1137,120 +1137,13 @@ Every remaining mention either:
|
||||
- says historical/debugging-only, or
|
||||
- points to the persistent runtime migration plan.
|
||||
|
||||
## Task 10: Rename `transparent_proxy` To `proxy`
|
||||
## Task 10: Proxy Rename Completed
|
||||
|
||||
**Files:**
|
||||
The old `transparent_proxy` package and `TransparentProxyRuntime` alias are gone.
|
||||
Use `wf_mcp.proxy.ProxyRuntime`, `create_proxy_client`,
|
||||
`create_proxy_server`, and `validate_proxy_config`.
|
||||
|
||||
- Move: `src/wf_mcp/transparent_proxy/admin.py` -> `src/wf_mcp/proxy/admin.py`
|
||||
- Move: `src/wf_mcp/transparent_proxy/mounts.py` -> `src/wf_mcp/proxy/mounts.py`
|
||||
- Move: `src/wf_mcp/transparent_proxy/runtime.py` -> `src/wf_mcp/proxy/runtime.py`
|
||||
- Move: `src/wf_mcp/transparent_proxy/safe_names.py` -> `src/wf_mcp/proxy/safe_names.py`
|
||||
- Move: `src/wf_mcp/transparent_proxy/tools.py` -> `src/wf_mcp/proxy/tools.py`
|
||||
- Modify: `src/wf_mcp/server/core.py`
|
||||
- Modify: `src/wf_mcp/cli.py`
|
||||
- Modify: `docs/wf_mcp_architecture.md`
|
||||
- Modify: tests under `tests/wf_mcp/`
|
||||
|
||||
- [ ] **Step 1: Move the package contents**
|
||||
|
||||
Create `src/wf_mcp/proxy/` and move the active implementation files:
|
||||
|
||||
```text
|
||||
admin.py
|
||||
mounts.py
|
||||
runtime.py
|
||||
safe_names.py
|
||||
tools.py
|
||||
```
|
||||
|
||||
Create `src/wf_mcp/proxy/__init__.py` exporting the runtime names currently
|
||||
used by callers.
|
||||
|
||||
- [ ] **Step 2: Leave a temporary compatibility shim**
|
||||
|
||||
Replace `src/wf_mcp/transparent_proxy/__init__.py` with:
|
||||
|
||||
```python
|
||||
from wf_mcp.proxy import * # noqa: F403
|
||||
```
|
||||
|
||||
Delete all other files from `src/wf_mcp/transparent_proxy/`.
|
||||
|
||||
This makes the old package visibly empty while giving downstream imports one
|
||||
migration window.
|
||||
|
||||
- [ ] **Step 3: Update internal imports**
|
||||
|
||||
Replace internal imports of:
|
||||
|
||||
```text
|
||||
wf_mcp.transparent_proxy
|
||||
```
|
||||
|
||||
with:
|
||||
|
||||
```text
|
||||
wf_mcp.proxy
|
||||
```
|
||||
|
||||
Check with:
|
||||
|
||||
```bash
|
||||
rg -n "transparent_proxy" src tests
|
||||
```
|
||||
|
||||
Expected after this step:
|
||||
|
||||
```text
|
||||
src/wf_mcp/transparent_proxy/__init__.py
|
||||
```
|
||||
|
||||
is the only remaining source import location.
|
||||
|
||||
- [ ] **Step 4: Rename tests if practical**
|
||||
|
||||
Preferred rename:
|
||||
|
||||
```text
|
||||
tests/wf_mcp/test_transparent_proxy.py -> tests/wf_mcp/test_proxy.py
|
||||
```
|
||||
|
||||
If the file is too noisy, keep the filename for one pass but update test names
|
||||
and imports first. The goal is no new test code using "transparent proxy" as the
|
||||
current architecture term.
|
||||
|
||||
- [ ] **Step 5: Update docs**
|
||||
|
||||
In `docs/wf_mcp_architecture.md`, replace the package row with:
|
||||
|
||||
```markdown
|
||||
| `wf_mcp.proxy` | Mount configured upstream MCP servers into the unified server. Owns proxy runtime, admin tools, safe tool-name transforms, and proxy inventory helpers. |
|
||||
```
|
||||
|
||||
Add:
|
||||
|
||||
```markdown
|
||||
`wf_mcp.transparent_proxy` is a compatibility shim only. Do not add new code
|
||||
there.
|
||||
```
|
||||
|
||||
- [ ] **Step 6: Run verification**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
uv run --with pytest pytest tests/wf_mcp -q
|
||||
uv run basedpyright --level error
|
||||
uvx ruff check src/wf_mcp tests/wf_mcp
|
||||
```
|
||||
|
||||
Expected:
|
||||
|
||||
```text
|
||||
passed
|
||||
0 errors
|
||||
ruff clean
|
||||
```
|
||||
The proxy tests now live in `tests/wf_mcp/test_proxy.py`.
|
||||
|
||||
## Task 11: Live Playwright Verification
|
||||
|
||||
@@ -1325,21 +1218,13 @@ Append to `random shit/sonnet46-challenge-cont.md`:
|
||||
|
||||
## Migration Rule
|
||||
|
||||
Until this plan is implemented:
|
||||
|
||||
- Treat `wf.mcp.call_tool` as stateless/debugging-only.
|
||||
- Prefer direct transparent proxy tools for manual upstream testing.
|
||||
- Do not recommend broker raw calls for Playwright workflows.
|
||||
- Do not delete `WfMcpService`; it still owns too much platform infrastructure.
|
||||
- Do not add new code to `wf_mcp.transparent_proxy`; it should become a
|
||||
compatibility shim after the rename to `wf_mcp.proxy`.
|
||||
|
||||
After this plan is implemented:
|
||||
|
||||
- Generated workflow node specs should use persistent MCP runtime.
|
||||
- Public raw call helpers should be hidden, removed, or clearly debug-only.
|
||||
- `transparent_proxy/` should contain only a shim or be removed after one
|
||||
compatibility window.
|
||||
- Public raw call helpers should stay deleted.
|
||||
- Prefer direct proxy tools for manual upstream testing.
|
||||
- Do not recommend broker raw calls for Playwright workflows.
|
||||
- Do not delete `WfMcpService`; it still owns too much platform infrastructure.
|
||||
- `broker/` can be renamed/split safely in a later structural cleanup.
|
||||
|
||||
## Verification Commands
|
||||
|
||||
@@ -8,7 +8,7 @@ projections of those sources.
|
||||
If you need the practical "which thing do I call?" view before the domain model,
|
||||
start with [`wf_mcp_operator_manual.md`](wf_mcp_operator_manual.md).
|
||||
|
||||
This avoids the current trap where broker admin tools, transparent proxy admin
|
||||
This avoids the current trap where broker admin tools, proxy admin
|
||||
tools, workflow node specs, and upstream MCP tools all look like unrelated
|
||||
systems.
|
||||
|
||||
@@ -257,7 +257,7 @@ Current code has several useful pieces but the boundaries are blurred.
|
||||
| `wf_mcp.broker.service.builtins` | local workflow specs | `wf.std` |
|
||||
| `wf_mcp.broker.tools` | compatibility wrapper over shared service-admin registration | `wf.admin.tools` |
|
||||
| `wf_mcp.admin_surface.tools` | shared service-backed admin tool registration | `wf.admin.tools` |
|
||||
| `wf_mcp.transparent_proxy.admin` | proxy-backed public admin tools | `wf.admin.tools` |
|
||||
| `wf_mcp.proxy.admin` | proxy-backed public admin tools | `wf.admin.tools` |
|
||||
| discovered MCP tools | upstream tools and workflow wrappers | connection source |
|
||||
| broker resources/prompts | catalog/status/planning context | likely `wf.admin` or docs sources |
|
||||
|
||||
|
||||
+3
-3
@@ -240,7 +240,7 @@ proxy plane and is the wrong abstraction for stateful MCP servers.
|
||||
|
||||
### Official protocol boundary
|
||||
|
||||
The transparent proxy layer should prefer official MCP boundary types over local mirror models.
|
||||
The proxy layer should prefer official MCP boundary types over local mirror models.
|
||||
|
||||
Use MCP SDK types at the proxy boundary:
|
||||
|
||||
@@ -313,11 +313,11 @@ Implementation should verify whether the installed MCP/FastMCP dependency expose
|
||||
- add the compatible `fastmcp` dependency explicitly
|
||||
- or implement the proxy at a lower MCP server/provider layer
|
||||
|
||||
Do not encode the transparent proxy as a pile of static decorators. The proxy surface is connection/catalog driven and must be able to change after refresh.
|
||||
Do not encode the proxy as a pile of static decorators. The proxy surface is connection/catalog driven and must be able to change after refresh.
|
||||
|
||||
### Sampling and elicitation
|
||||
|
||||
Sampling and elicitation make transparent proxying much harder than simple tool forwarding.
|
||||
Sampling and elicitation make protocol-transparent proxying much harder than simple tool forwarding.
|
||||
|
||||
Simple request flow:
|
||||
|
||||
|
||||
@@ -161,7 +161,7 @@ Generic notification relay does not pass it yet.
|
||||
|
||||
### Continue Building Now
|
||||
|
||||
These areas do not require a perfect transparent proxy:
|
||||
These areas do not require a perfect protocol-transparent proxy:
|
||||
|
||||
1. capability and source inventory surfaced clearly to users and LLM clients
|
||||
2. admin/control UX over configured sources
|
||||
|
||||
@@ -5,7 +5,7 @@ from wf_mcp.models import BrokerConfig
|
||||
|
||||
|
||||
class ProxyAdminRuntime(Protocol):
|
||||
"""Runtime boundary needed by transparent proxy admin handlers."""
|
||||
"""Runtime boundary needed by proxy admin handlers."""
|
||||
|
||||
@property
|
||||
def manager(self) -> ConfigManager | None: ...
|
||||
|
||||
@@ -11,7 +11,7 @@ _SUPPORTED_TRANSPORTS = {"stdio", "http", "streamable-http", "streamable_http",
|
||||
|
||||
|
||||
class ProxyConfigError(ValueError):
|
||||
"""Raised when a broker config cannot safely run as a transparent proxy."""
|
||||
"""Raised when a broker config cannot safely run as a proxy."""
|
||||
|
||||
|
||||
def validate_proxy_config(
|
||||
@@ -33,7 +33,7 @@ def validate_proxy_config(
|
||||
)
|
||||
if errors:
|
||||
joined = "\n".join(f"- {error}" for error in errors)
|
||||
raise ProxyConfigError(f"invalid transparent proxy config:\n{joined}")
|
||||
raise ProxyConfigError(f"invalid proxy config:\n{joined}")
|
||||
|
||||
|
||||
def _validate_connection_ids(
|
||||
|
||||
@@ -70,7 +70,7 @@ def test_fixture_server_emits_observable_protocol_notifications_directly() -> No
|
||||
assert "notifications/message" in methods
|
||||
|
||||
|
||||
def test_transparent_proxy_does_not_relay_upstream_protocol_notifications_yet() -> None:
|
||||
def test_proxy_does_not_relay_upstream_protocol_notifications_yet() -> None:
|
||||
config = BrokerConfig(
|
||||
store_root=local_temp_root() / "protocol_relay_store",
|
||||
connections=[
|
||||
|
||||
Reference in New Issue
Block a user