refactor: add mcp source client facade
This commit is contained in:
@@ -0,0 +1,724 @@
|
||||
# MCP Source Client Facade 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:** Introduce a shared `McpSourceClient` facade around MCP SDK `ClientSession` operations, then make the one-shot `McpSdkAdapter` delegate to it without changing behavior.
|
||||
|
||||
**Architecture:** `open_mcp_session()` still owns transport opening and initialization. `McpSourceClient` owns MCP operation calls plus conversion/serialization from SDK models into workflow/source-provider DTOs. `McpSdkAdapter` remains one-shot but stops handling raw `ClientSession` operations directly; persistent runtime expansion is explicitly deferred.
|
||||
|
||||
**Tech Stack:** Python 3.14, MCP Python SDK, Pydantic, pytest/pytest-asyncio, ruff, basedpyright.
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
- Create `src/wf_sources_mcp/client/source_client.py`
|
||||
- `McpSourceClient` dataclass wrapping `ClientSession` and `McpSourceConnection`.
|
||||
- Methods mirror `BackendAdapter` operations except they do not accept `connection`/`auth`.
|
||||
- Converts tools/resources/prompts/tool results and serializes resource/prompt/raw method payloads.
|
||||
- Modify `src/wf_sources_mcp/client/__init__.py`
|
||||
- Export `McpSourceClient`.
|
||||
- Modify `src/wf_sources_mcp/sdk/adapter.py`
|
||||
- `_session()` becomes `_client()` and yields `McpSourceClient`.
|
||||
- Public methods delegate to client methods.
|
||||
- Add `tests/wf_sources_mcp/test_source_client.py`
|
||||
- Direct facade tests for all operation families.
|
||||
- Modify `tests/wf_sources_mcp/test_sdk_adapter.py`
|
||||
- Keep adapter tests; adjust only if needed for `_client()` naming.
|
||||
- Update docs:
|
||||
- `docs/current_roadmap.md`
|
||||
- `docs/superpowers/specs/2026-06-03-long-lived-workflow-api-boundary.md`
|
||||
|
||||
## Hard Boundaries
|
||||
|
||||
- Do not change `BackendAdapter` signatures.
|
||||
- Do not change `McpSdkAdapter` output shapes.
|
||||
- Do not expand `PersistentMcpSession` beyond `call_tool` in this slice.
|
||||
- Do not change `open_mcp_session()` transport behavior.
|
||||
- Do not import `wf_mcp` from `src/wf_sources_mcp/**`.
|
||||
- Do not manually call `__aexit__`; context-manager ownership stays with `async with`.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Add Direct Facade Tests
|
||||
|
||||
**Files:**
|
||||
- Create: `tests/wf_sources_mcp/test_source_client.py`
|
||||
|
||||
- [ ] **Step 1: Create tests for the facade behavior**
|
||||
|
||||
Create `tests/wf_sources_mcp/test_source_client.py`:
|
||||
|
||||
```python
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
import pytest
|
||||
from mcp import ClientResult
|
||||
from mcp.types import (
|
||||
CallToolResult,
|
||||
ClientNotification,
|
||||
ClientRequest,
|
||||
ListPromptsResult,
|
||||
ListResourcesResult,
|
||||
ListToolsResult,
|
||||
Prompt,
|
||||
Resource,
|
||||
TextContent,
|
||||
Tool,
|
||||
)
|
||||
from pydantic import AnyUrl
|
||||
|
||||
from wf_sources_mcp.client import McpSourceClient
|
||||
from wf_sources_mcp.connections import McpSourceConnection
|
||||
from wf_sources_mcp.transports import StdioSourceTransport
|
||||
|
||||
|
||||
def _connection() -> McpSourceConnection:
|
||||
return McpSourceConnection(
|
||||
id="demo.personal",
|
||||
provider="demo",
|
||||
account="personal",
|
||||
transport=StdioSourceTransport(command="fake"),
|
||||
)
|
||||
|
||||
|
||||
class _FakeSession:
|
||||
def __init__(self) -> None:
|
||||
self.requests: list[ClientRequest] = []
|
||||
self.notifications: list[ClientNotification] = []
|
||||
|
||||
async def list_tools(self) -> ListToolsResult:
|
||||
return ListToolsResult(
|
||||
tools=[
|
||||
Tool(
|
||||
name="echo",
|
||||
title="Echo",
|
||||
description="Echo text.",
|
||||
inputSchema={"type": "object", "properties": {}},
|
||||
)
|
||||
]
|
||||
)
|
||||
|
||||
async def list_resources(self) -> ListResourcesResult:
|
||||
return ListResourcesResult(
|
||||
resources=[
|
||||
Resource(
|
||||
uri=AnyUrl("fixture://docs/welcome"),
|
||||
name="resource.welcome",
|
||||
title="Welcome",
|
||||
description="Welcome resource.",
|
||||
mimeType="text/plain",
|
||||
)
|
||||
]
|
||||
)
|
||||
|
||||
async def list_prompts(self) -> ListPromptsResult:
|
||||
return ListPromptsResult(
|
||||
prompts=[
|
||||
Prompt(
|
||||
name="prompt.summarize",
|
||||
title="Summarize",
|
||||
description="Summarize input.",
|
||||
arguments=[],
|
||||
)
|
||||
]
|
||||
)
|
||||
|
||||
async def read_resource(self, uri: AnyUrl) -> Any:
|
||||
return type(
|
||||
"ReadResourceResult",
|
||||
(),
|
||||
{
|
||||
"model_dump": lambda _self, **_kwargs: {
|
||||
"contents": [{"uri": str(uri), "text": "hello"}]
|
||||
}
|
||||
},
|
||||
)()
|
||||
|
||||
async def get_prompt(
|
||||
self,
|
||||
prompt_name: str,
|
||||
arguments: dict[str, str] | None = None,
|
||||
) -> Any:
|
||||
return type(
|
||||
"GetPromptResult",
|
||||
(),
|
||||
{
|
||||
"model_dump": lambda _self, **_kwargs: {
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": {
|
||||
"type": "text",
|
||||
"text": f"{prompt_name}:{arguments or {}}",
|
||||
},
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
)()
|
||||
|
||||
async def send_request(
|
||||
self,
|
||||
request: ClientRequest,
|
||||
result_type: type[ClientResult],
|
||||
) -> Any:
|
||||
assert result_type is ClientResult
|
||||
self.requests.append(request)
|
||||
return type(
|
||||
"ClientResultModel",
|
||||
(),
|
||||
{"model_dump": lambda _self, **_kwargs: {"ok": True}},
|
||||
)()
|
||||
|
||||
async def send_notification(self, notification: ClientNotification) -> None:
|
||||
self.notifications.append(notification)
|
||||
|
||||
async def call_tool(
|
||||
self,
|
||||
tool_name: str,
|
||||
payload: dict[str, Any],
|
||||
) -> CallToolResult:
|
||||
return CallToolResult(
|
||||
content=[TextContent(type="text", text="ok")],
|
||||
structuredContent={"tool": tool_name, "payload": payload},
|
||||
)
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_source_client_lists_catalog_items_and_metadata() -> None:
|
||||
source_client = McpSourceClient(session=_FakeSession(), connection=_connection())
|
||||
|
||||
tools = await source_client.list_tools()
|
||||
resources = await source_client.list_resources()
|
||||
prompts = await source_client.list_prompts()
|
||||
metadata = await source_client.get_connection_metadata()
|
||||
|
||||
assert tools[0].name == "echo"
|
||||
assert resources[0].uri == "fixture://docs/welcome"
|
||||
assert prompts[0].name == "prompt.summarize"
|
||||
assert metadata == {"server": "demo", "transport": "stdio"}
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_source_client_reads_resources_and_prompts_as_payloads() -> None:
|
||||
source_client = McpSourceClient(session=_FakeSession(), connection=_connection())
|
||||
|
||||
resource_payload = await source_client.read_resource("fixture://docs/welcome")
|
||||
prompt_payload = await source_client.get_prompt(
|
||||
"prompt.summarize",
|
||||
{"text": "hello"},
|
||||
)
|
||||
|
||||
assert resource_payload["contents"][0]["text"] == "hello"
|
||||
assert prompt_payload["messages"][0]["content"]["text"] == (
|
||||
"prompt.summarize:{'text': 'hello'}"
|
||||
)
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_source_client_invokes_methods_and_notifications() -> None:
|
||||
session = _FakeSession()
|
||||
source_client = McpSourceClient(session=session, connection=_connection())
|
||||
|
||||
result = await source_client.invoke_method("ping")
|
||||
await source_client.send_notification("notifications/initialized")
|
||||
|
||||
assert result == {"ok": True}
|
||||
assert session.requests, "invoke_method should send a request"
|
||||
assert session.notifications, "send_notification should send a notification"
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_source_client_call_tool_normalizes_result() -> None:
|
||||
source_client = McpSourceClient(session=_FakeSession(), connection=_connection())
|
||||
|
||||
result = await source_client.call_tool("echo", {"text": "hello"})
|
||||
|
||||
assert result.outcome == "ok"
|
||||
assert result.output == {
|
||||
"tool": "echo",
|
||||
"payload": {"text": "hello"},
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run tests to confirm missing class**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
uv run pytest tests/wf_sources_mcp/test_source_client.py -q
|
||||
```
|
||||
|
||||
Expected: fail with import error for `McpSourceClient`.
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Implement `McpSourceClient`
|
||||
|
||||
**Files:**
|
||||
- Create: `src/wf_sources_mcp/client/source_client.py`
|
||||
- Modify: `src/wf_sources_mcp/client/__init__.py`
|
||||
|
||||
- [ ] **Step 1: Add the facade implementation**
|
||||
|
||||
Create `src/wf_sources_mcp/client/source_client.py`:
|
||||
|
||||
```python
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass
|
||||
from typing import Any
|
||||
|
||||
from mcp import ClientResult
|
||||
from mcp.client.session import ClientSession
|
||||
from mcp.types import (
|
||||
ClientNotification,
|
||||
ClientRequest,
|
||||
ListPromptsResult,
|
||||
ListResourcesResult,
|
||||
ListToolsResult,
|
||||
)
|
||||
from pydantic import AnyUrl
|
||||
|
||||
from wf_sources_mcp.catalog import DiscoveredPrompt, DiscoveredResource, DiscoveredTool
|
||||
from wf_sources_mcp.connections import McpSourceConnection
|
||||
from wf_sources_mcp.sdk.converters import (
|
||||
prompt_to_discovered,
|
||||
resource_to_discovered,
|
||||
tool_result_to_call_result,
|
||||
tool_to_discovered,
|
||||
)
|
||||
from wf_sources_mcp.sdk.protocols import ToolCallResult
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class McpSourceClient:
|
||||
"""Operation facade over an initialized MCP SDK ClientSession.
|
||||
|
||||
This class owns SDK operation calls and conversion to wf_sources_mcp DTOs.
|
||||
It does not own transport lifetime. One-shot callers enter it through
|
||||
`open_mcp_session`; persistent runtime owners may wrap the session inside
|
||||
their owner task in a later slice.
|
||||
"""
|
||||
|
||||
session: ClientSession
|
||||
connection: McpSourceConnection
|
||||
|
||||
async def list_tools(self) -> list[DiscoveredTool]:
|
||||
result: ListToolsResult = await self.session.list_tools()
|
||||
return [tool_to_discovered(tool) for tool in result.tools]
|
||||
|
||||
async def list_resources(self) -> list[DiscoveredResource]:
|
||||
result: ListResourcesResult = await self.session.list_resources()
|
||||
return [resource_to_discovered(resource) for resource in result.resources]
|
||||
|
||||
async def list_prompts(self) -> list[DiscoveredPrompt]:
|
||||
result: ListPromptsResult = await self.session.list_prompts()
|
||||
return [prompt_to_discovered(prompt) for prompt in result.prompts]
|
||||
|
||||
async def get_connection_metadata(self) -> dict[str, Any]:
|
||||
transport = self.connection.transport
|
||||
return {
|
||||
"server": self.connection.provider,
|
||||
"transport": transport.kind if transport is not None else None,
|
||||
}
|
||||
|
||||
async def read_resource(self, uri: str) -> dict[str, Any]:
|
||||
result = await self.session.read_resource(AnyUrl(uri))
|
||||
return result.model_dump(by_alias=True, mode="json", exclude_none=True)
|
||||
|
||||
async def get_prompt(
|
||||
self,
|
||||
prompt_name: str,
|
||||
arguments: dict[str, str] | None = None,
|
||||
) -> dict[str, Any]:
|
||||
result = await self.session.get_prompt(prompt_name, arguments)
|
||||
return result.model_dump(by_alias=True, mode="json", exclude_none=True)
|
||||
|
||||
async def invoke_method(
|
||||
self,
|
||||
method: str,
|
||||
params: dict[str, Any] | None = None,
|
||||
) -> dict[str, Any]:
|
||||
result = await self.session.send_request(
|
||||
ClientRequest.model_validate({"method": method, "params": params}),
|
||||
ClientResult,
|
||||
)
|
||||
return result.model_dump(by_alias=True, mode="json", exclude_none=True)
|
||||
|
||||
async def send_notification(
|
||||
self,
|
||||
method: str,
|
||||
params: dict[str, Any] | None = None,
|
||||
) -> None:
|
||||
await self.session.send_notification(
|
||||
ClientNotification.model_validate({"method": method, "params": params})
|
||||
)
|
||||
|
||||
async def call_tool(
|
||||
self,
|
||||
tool_name: str,
|
||||
payload: dict[str, Any],
|
||||
) -> ToolCallResult:
|
||||
result = await self.session.call_tool(tool_name, payload)
|
||||
return tool_result_to_call_result(result)
|
||||
|
||||
|
||||
__all__ = ["McpSourceClient"]
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Export the facade from the client package**
|
||||
|
||||
Modify `src/wf_sources_mcp/client/__init__.py`:
|
||||
|
||||
```python
|
||||
"""MCP source client helpers."""
|
||||
|
||||
from .source_client import McpSourceClient
|
||||
from .transport import open_mcp_session
|
||||
|
||||
__all__ = ["McpSourceClient", "open_mcp_session"]
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Run direct facade tests**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
uv run pytest tests/wf_sources_mcp/test_source_client.py -q
|
||||
```
|
||||
|
||||
Expected: pass.
|
||||
|
||||
---
|
||||
|
||||
### Task 3: Delegate `McpSdkAdapter` to the Facade
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/wf_sources_mcp/sdk/adapter.py`
|
||||
- Test: `tests/wf_sources_mcp/test_sdk_adapter.py`
|
||||
|
||||
- [ ] **Step 1: Replace raw session operation logic in adapter**
|
||||
|
||||
Replace `src/wf_sources_mcp/sdk/adapter.py` with:
|
||||
|
||||
```python
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import AsyncIterator
|
||||
from contextlib import asynccontextmanager
|
||||
from typing import Any
|
||||
|
||||
from wf_sources_mcp.auth import AuthRecord
|
||||
from wf_sources_mcp.catalog import DiscoveredPrompt, DiscoveredResource, DiscoveredTool
|
||||
from wf_sources_mcp.client import McpSourceClient, open_mcp_session
|
||||
from wf_sources_mcp.connections import McpSourceConnection
|
||||
|
||||
from .protocols import BackendAdapter, ToolCallResult
|
||||
|
||||
|
||||
class McpSdkAdapter(BackendAdapter):
|
||||
"""One-shot MCP client adapter for upstream MCP source operations.
|
||||
|
||||
This adapter intentionally opens a fresh SDK session per operation. It
|
||||
delegates all MCP operation/conversion details to `McpSourceClient` so the
|
||||
same operation facade can later be used inside persistent runtime owners.
|
||||
"""
|
||||
|
||||
@asynccontextmanager
|
||||
async def _client(
|
||||
self,
|
||||
connection: McpSourceConnection,
|
||||
auth: AuthRecord | None,
|
||||
) -> AsyncIterator[McpSourceClient]:
|
||||
async with open_mcp_session(connection, auth) as session:
|
||||
yield McpSourceClient(session=session, connection=connection)
|
||||
|
||||
async def list_tools(
|
||||
self,
|
||||
connection: McpSourceConnection,
|
||||
auth: AuthRecord | None,
|
||||
) -> list[DiscoveredTool]:
|
||||
async with self._client(connection, auth) as client:
|
||||
return await client.list_tools()
|
||||
|
||||
async def list_resources(
|
||||
self,
|
||||
connection: McpSourceConnection,
|
||||
auth: AuthRecord | None,
|
||||
) -> list[DiscoveredResource]:
|
||||
async with self._client(connection, auth) as client:
|
||||
return await client.list_resources()
|
||||
|
||||
async def list_prompts(
|
||||
self,
|
||||
connection: McpSourceConnection,
|
||||
auth: AuthRecord | None,
|
||||
) -> list[DiscoveredPrompt]:
|
||||
async with self._client(connection, auth) as client:
|
||||
return await client.list_prompts()
|
||||
|
||||
async def get_connection_metadata(
|
||||
self,
|
||||
connection: McpSourceConnection,
|
||||
auth: AuthRecord | None,
|
||||
) -> dict[str, Any]:
|
||||
async with self._client(connection, auth) as client:
|
||||
return await client.get_connection_metadata()
|
||||
|
||||
async def read_resource(
|
||||
self,
|
||||
connection: McpSourceConnection,
|
||||
auth: AuthRecord | None,
|
||||
uri: str,
|
||||
) -> dict[str, Any]:
|
||||
async with self._client(connection, auth) as client:
|
||||
return await client.read_resource(uri)
|
||||
|
||||
async def get_prompt(
|
||||
self,
|
||||
connection: McpSourceConnection,
|
||||
auth: AuthRecord | None,
|
||||
prompt_name: str,
|
||||
arguments: dict[str, str] | None = None,
|
||||
) -> dict[str, Any]:
|
||||
async with self._client(connection, auth) as client:
|
||||
return await client.get_prompt(prompt_name, arguments)
|
||||
|
||||
async def invoke_method(
|
||||
self,
|
||||
connection: McpSourceConnection,
|
||||
auth: AuthRecord | None,
|
||||
method: str,
|
||||
params: dict[str, Any] | None = None,
|
||||
) -> dict[str, Any]:
|
||||
async with self._client(connection, auth) as client:
|
||||
return await client.invoke_method(method, params)
|
||||
|
||||
async def send_notification(
|
||||
self,
|
||||
connection: McpSourceConnection,
|
||||
auth: AuthRecord | None,
|
||||
method: str,
|
||||
params: dict[str, Any] | None = None,
|
||||
) -> None:
|
||||
async with self._client(connection, auth) as client:
|
||||
await client.send_notification(method, params)
|
||||
|
||||
async def call_tool(
|
||||
self,
|
||||
connection: McpSourceConnection,
|
||||
auth: AuthRecord | None,
|
||||
tool_name: str,
|
||||
payload: dict[str, Any],
|
||||
) -> ToolCallResult:
|
||||
async with self._client(connection, auth) as client:
|
||||
return await client.call_tool(tool_name, payload)
|
||||
|
||||
|
||||
__all__ = ["McpSdkAdapter"]
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Update adapter test fake hook name**
|
||||
|
||||
In `tests/wf_sources_mcp/test_sdk_adapter.py`, if the fake subclass overrides `_session`, change it to override `_client` instead:
|
||||
|
||||
```python
|
||||
class _ClientContext:
|
||||
def __init__(self, client: McpSourceClient) -> None:
|
||||
self.client = client
|
||||
|
||||
async def __aenter__(self) -> McpSourceClient:
|
||||
return self.client
|
||||
|
||||
async def __aexit__(
|
||||
self,
|
||||
exc_type: type[BaseException] | None,
|
||||
exc: BaseException | None,
|
||||
tb: object | None,
|
||||
) -> None:
|
||||
return None
|
||||
|
||||
|
||||
class _FakeAdapter(McpSdkAdapter):
|
||||
def __init__(self, session: _FakeSession) -> None:
|
||||
self.fake_session = session
|
||||
|
||||
def _client(self, connection: McpSourceConnection, auth: object | None):
|
||||
assert connection.id == "demo.personal"
|
||||
assert auth is None
|
||||
return _ClientContext(
|
||||
McpSourceClient(session=self.fake_session, connection=connection)
|
||||
)
|
||||
```
|
||||
|
||||
Also add this import near the top of the file:
|
||||
|
||||
```python
|
||||
from wf_sources_mcp.client import McpSourceClient
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Run adapter and facade tests**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
uv run pytest tests/wf_sources_mcp/test_source_client.py tests/wf_sources_mcp/test_sdk_adapter.py -q
|
||||
```
|
||||
|
||||
Expected: pass.
|
||||
|
||||
---
|
||||
|
||||
### Task 4: Verify Persistent Runtime Is Not Expanded
|
||||
|
||||
**Files:**
|
||||
- Modify only if needed: `src/wf_sources_mcp/runtime/session.py`
|
||||
- Test: `tests/wf_sources_mcp/test_runtime.py`
|
||||
|
||||
- [ ] **Step 1: Inspect runtime session remains tool-call-only**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
rg -n "def (list_tools|list_resources|list_prompts|read_resource|get_prompt|invoke_method|send_notification)" src/wf_sources_mcp/runtime
|
||||
```
|
||||
|
||||
Expected: no matches.
|
||||
|
||||
- [ ] **Step 2: Add or preserve code seam comment if needed**
|
||||
|
||||
If `src/wf_sources_mcp/runtime/session.py` does not already make the boundary clear, update the class docstring to include:
|
||||
|
||||
```python
|
||||
"""Long-lived MCP execution handle for one configured connection.
|
||||
|
||||
Production sessions use `call_callback` because MCP transports are entered
|
||||
inside an AnyIO cancel scope and must be called and closed by that same
|
||||
owner task. `client` remains available for simple injected/fake sessions in
|
||||
tests. `call_tool()` always normalizes SDK results for workflow nodes.
|
||||
|
||||
This runtime intentionally exposes only tool calls for now. Shared
|
||||
non-tool operations live on `McpSourceClient`; routing them through the
|
||||
owner task is a separate runtime-expansion slice.
|
||||
"""
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Run runtime tests**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
uv run pytest tests/wf_sources_mcp/test_runtime.py tests/wf_mcp/test_stateful_runtime.py -q
|
||||
```
|
||||
|
||||
Expected: pass.
|
||||
|
||||
---
|
||||
|
||||
### Task 5: Update Docs
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/current_roadmap.md`
|
||||
- Modify: `docs/superpowers/specs/2026-06-03-long-lived-workflow-api-boundary.md`
|
||||
- Move after completion: `docs/superpowers/plans/2026-06-07-mcp-source-client-facade.md` to `docs/historical/superpowers/plans/2026-06-07-mcp-source-client-facade.md`
|
||||
|
||||
- [ ] **Step 1: Update roadmap**
|
||||
|
||||
In `docs/current_roadmap.md`, under the MCP upstream source runtime cleanup bullets, add:
|
||||
|
||||
```markdown
|
||||
- Completed: shared `McpSourceClient` facade introduced in
|
||||
`wf_sources_mcp.client`. The one-shot SDK adapter delegates MCP operation
|
||||
calls and conversion through the facade; persistent runtime remains
|
||||
tool-call-only until a separate owner-task routing slice.
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Update long-lived API boundary spec**
|
||||
|
||||
In `docs/superpowers/specs/2026-06-03-long-lived-workflow-api-boundary.md`, in the numbered `wf_sources_mcp` implementation status list after the adapter move item, add:
|
||||
|
||||
```markdown
|
||||
9. Complete: shared `McpSourceClient` facade introduced in
|
||||
`wf_sources_mcp.client`. `McpSdkAdapter` now delegates operation handling to
|
||||
this facade. Persistent runtime still exposes only `call_tool`; expanding it
|
||||
requires a separate owner-task request routing slice.
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Archive completed plan after implementation**
|
||||
|
||||
Run only after all code/tests pass:
|
||||
|
||||
```bash
|
||||
git mv docs/superpowers/plans/2026-06-07-mcp-source-client-facade.md docs/historical/superpowers/plans/2026-06-07-mcp-source-client-facade.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 6: Final Verification
|
||||
|
||||
**Files:**
|
||||
- All changed files.
|
||||
|
||||
- [ ] **Step 1: Run focused tests**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
uv run pytest tests/wf_sources_mcp tests/wf_mcp/test_sdk_adapter.py tests/wf_mcp/test_stateful_runtime.py tests/wf_mcp/test_compat_imports.py -q
|
||||
```
|
||||
|
||||
Expected: pass. Report any environment-based skips exactly.
|
||||
|
||||
- [ ] **Step 2: Run source typecheck**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
uv run basedpyright --level error src
|
||||
```
|
||||
|
||||
Expected: `0 errors, 0 warnings, 0 notes`.
|
||||
|
||||
- [ ] **Step 3: Run focused lint**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
uv run ruff check src/wf_sources_mcp tests/wf_sources_mcp/test_source_client.py tests/wf_sources_mcp/test_sdk_adapter.py
|
||||
```
|
||||
|
||||
Expected: `All checks passed!`
|
||||
|
||||
- [ ] **Step 4: Check runtime non-expansion**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
rg -n "def (list_tools|list_resources|list_prompts|read_resource|get_prompt|invoke_method|send_notification)" src/wf_sources_mcp/runtime
|
||||
```
|
||||
|
||||
Expected: no matches.
|
||||
|
||||
- [ ] **Step 5: Check whitespace**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
git diff --check
|
||||
```
|
||||
|
||||
Expected: no whitespace errors. CRLF warnings are acceptable on Windows.
|
||||
|
||||
---
|
||||
|
||||
## Self-Review
|
||||
|
||||
- Spec coverage: The plan creates the shared source-client facade, delegates one-shot adapter operations to it, preserves old runtime behavior, and documents the boundary.
|
||||
- Placeholder scan: No placeholder steps remain. All code edits include concrete snippets.
|
||||
- Type consistency: `McpSourceClient` wraps `ClientSession` plus `McpSourceConnection`; adapter public methods keep `BackendAdapter` signatures.
|
||||
- Intentional non-goal: persistent runtime does not gain non-tool operations in this slice.
|
||||
|
||||
Reference in New Issue
Block a user