Add stub Client and InMemoryTransport classes with tests

This commit adds:
- Client class stub with from_server() class method
- InMemoryTransport class stub
- Comprehensive test suite for Client (TDD approach)

All methods currently raise NotImplementedError.

Github-Issue:#1728

Author: felixweinberger

src/mcp/client/client.py

@@ -0,0 +1,344 @@
+"""Unified MCP Client that wraps ClientSession with transport management."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from typing import Any
+
+from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
+from pydantic import AnyUrl
+
+import mcp.types as types
+from mcp.client.session import (
+    ClientSession,
+    ElicitationFnT,
+    ListRootsFnT,
+    LoggingFnT,
+    MessageHandlerFnT,
+    SamplingFnT,
+)
+from mcp.server import Server
+from mcp.server.fastmcp import FastMCP
+from mcp.shared.message import SessionMessage
+from mcp.shared.session import ProgressFnT
+
+logger = logging.getLogger(__name__)
+
+
+class Client:
+    """
+    A high-level MCP client that manages transport and session lifecycle.
+
+    The Client class provides a unified interface for connecting to MCP servers
+    using different transports (in-memory, stdio, HTTP, etc.) and exposes
+    all ClientSession functionality with simpler lifecycle management.
+
+    Example with in-memory transport:
+        server = FastMCP("test")
+
+        async with Client.from_server(server) as client:
+            tools = await client.list_tools()
+            result = await client.call_tool("my_tool", {"arg": "value"})
+
+    Example with custom transport:
+        async with Client(read_stream, write_stream) as client:
+            await client.initialize()
+            # Use client...
+    """
+
+    def __init__(
+        self,
+        read_stream: MemoryObjectReceiveStream[SessionMessage | Exception],
+        write_stream: MemoryObjectSendStream[SessionMessage],
+        read_timeout_seconds: float | None = None,
+        sampling_callback: SamplingFnT | None = None,
+        list_roots_callback: ListRootsFnT | None = None,
+        logging_callback: LoggingFnT | None = None,
+        message_handler: MessageHandlerFnT | None = None,
+        client_info: types.Implementation | None = None,
+        elicitation_callback: ElicitationFnT | None = None,
+    ) -> None:
+        """
+        Initialize the client with transport streams.
+
+        Args:
+            read_stream: Stream for receiving messages from the server
+            write_stream: Stream for sending messages to the server
+            read_timeout_seconds: Timeout for read operations
+            sampling_callback: Callback for handling sampling requests
+            list_roots_callback: Callback for handling list roots requests
+            logging_callback: Callback for handling logging notifications
+            message_handler: Callback for handling raw messages
+            client_info: Client implementation info to send to server
+            elicitation_callback: Callback for handling elicitation requests
+        """
+        raise NotImplementedError("Client.__init__ is not yet implemented")
+
+    @classmethod
+    @asynccontextmanager
+    async def from_server(
+        cls,
+        server: Server[Any] | FastMCP,
+        read_timeout_seconds: float | None = None,
+        sampling_callback: SamplingFnT | None = None,
+        list_roots_callback: ListRootsFnT | None = None,
+        logging_callback: LoggingFnT | None = None,
+        message_handler: MessageHandlerFnT | None = None,
+        client_info: types.Implementation | None = None,
+        raise_exceptions: bool = False,
+        elicitation_callback: ElicitationFnT | None = None,
+    ) -> AsyncGenerator[Client, None]:
+        """
+        Create a client connected to an in-memory server.
+
+        This is a convenience method that creates an in-memory transport,
+        starts the server, and returns an initialized client.
+
+        Args:
+            server: The MCP server to connect to (Server or FastMCP instance)
+            read_timeout_seconds: Timeout for read operations
+            sampling_callback: Callback for handling sampling requests
+            list_roots_callback: Callback for handling list roots requests
+            logging_callback: Callback for handling logging notifications
+            message_handler: Callback for handling raw messages
+            client_info: Client implementation info to send to server
+            raise_exceptions: Whether to raise exceptions from the server
+            elicitation_callback: Callback for handling elicitation requests
+
+        Yields:
+            An initialized Client connected to the server
+
+        Example:
+            server = FastMCP("test")
+
+            @server.tool()
+            def my_tool(arg: str) -> str:
+                return f"Result: {arg}"
+
+            async with Client.from_server(server) as client:
+                result = await client.call_tool("my_tool", {"arg": "value"})
+        """
+        # Silence unused parameter warnings in stub
+        _ = (server, read_timeout_seconds, sampling_callback, list_roots_callback,
+             logging_callback, message_handler, client_info, raise_exceptions, elicitation_callback)
+        # Stub: yield fake value, actual implementation will provide real client
+        yield None  # type: ignore[misc]
+        raise NotImplementedError("Client.from_server is not yet implemented")
+
+    async def __aenter__(self) -> Client:
+        """Enter the async context manager."""
+        raise NotImplementedError("Client.__aenter__ is not yet implemented")
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> None:
+        """Exit the async context manager."""
+        raise NotImplementedError("Client.__aexit__ is not yet implemented")
+
+    async def initialize(self) -> types.InitializeResult:
+        """
+        Initialize the MCP session with the server.
+
+        This must be called before using other client methods.
+
+        Returns:
+            The initialization result from the server
+        """
+        raise NotImplementedError("Client.initialize is not yet implemented")
+
+    def get_server_capabilities(self) -> types.ServerCapabilities | None:
+        """
+        Return the server capabilities received during initialization.
+
+        Returns:
+            The server capabilities, or None if not yet initialized
+        """
+        raise NotImplementedError("Client.get_server_capabilities is not yet implemented")
+
+    async def send_ping(self) -> types.EmptyResult:
+        """Send a ping request to the server."""
+        raise NotImplementedError("Client.send_ping is not yet implemented")
+
+    async def send_progress_notification(
+        self,
+        progress_token: str | int,
+        progress: float,
+        total: float | None = None,
+        message: str | None = None,
+    ) -> None:
+        """Send a progress notification to the server."""
+        raise NotImplementedError("Client.send_progress_notification is not yet implemented")
+
+    async def set_logging_level(self, level: types.LoggingLevel) -> types.EmptyResult:
+        """Set the logging level on the server."""
+        raise NotImplementedError("Client.set_logging_level is not yet implemented")
+
+    async def list_resources(
+        self,
+        cursor: str | None = None,
+        *,
+        params: types.PaginatedRequestParams | None = None,
+    ) -> types.ListResourcesResult:
+        """
+        List available resources from the server.
+
+        Args:
+            cursor: Pagination cursor (deprecated, use params instead)
+            params: Full pagination parameters
+
+        Returns:
+            List of available resources
+        """
+        raise NotImplementedError("Client.list_resources is not yet implemented")
+
+    async def list_resource_templates(
+        self,
+        cursor: str | None = None,
+        *,
+        params: types.PaginatedRequestParams | None = None,
+    ) -> types.ListResourceTemplatesResult:
+        """
+        List available resource templates from the server.
+
+        Args:
+            cursor: Pagination cursor (deprecated, use params instead)
+            params: Full pagination parameters
+
+        Returns:
+            List of available resource templates
+        """
+        raise NotImplementedError("Client.list_resource_templates is not yet implemented")
+
+    async def read_resource(self, uri: AnyUrl) -> types.ReadResourceResult:
+        """
+        Read a resource from the server.
+
+        Args:
+            uri: The URI of the resource to read
+
+        Returns:
+            The resource content
+        """
+        raise NotImplementedError("Client.read_resource is not yet implemented")
+
+    async def subscribe_resource(self, uri: AnyUrl) -> types.EmptyResult:
+        """Subscribe to resource updates."""
+        raise NotImplementedError("Client.subscribe_resource is not yet implemented")
+
+    async def unsubscribe_resource(self, uri: AnyUrl) -> types.EmptyResult:
+        """Unsubscribe from resource updates."""
+        raise NotImplementedError("Client.unsubscribe_resource is not yet implemented")
+
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        read_timeout_seconds: float | None = None,
+        progress_callback: ProgressFnT | None = None,
+        *,
+        meta: dict[str, Any] | None = None,
+    ) -> types.CallToolResult:
+        """
+        Call a tool on the server.
+
+        Args:
+            name: The name of the tool to call
+            arguments: Arguments to pass to the tool
+            read_timeout_seconds: Timeout for the tool call
+            progress_callback: Callback for progress updates
+            meta: Additional metadata for the request
+
+        Returns:
+            The tool result
+        """
+        raise NotImplementedError("Client.call_tool is not yet implemented")
+
+    async def list_prompts(
+        self,
+        cursor: str | None = None,
+        *,
+        params: types.PaginatedRequestParams | None = None,
+    ) -> types.ListPromptsResult:
+        """
+        List available prompts from the server.
+
+        Args:
+            cursor: Pagination cursor (deprecated, use params instead)
+            params: Full pagination parameters
+
+        Returns:
+            List of available prompts
+        """
+        raise NotImplementedError("Client.list_prompts is not yet implemented")
+
+    async def get_prompt(
+        self,
+        name: str,
+        arguments: dict[str, str] | None = None,
+    ) -> types.GetPromptResult:
+        """
+        Get a prompt from the server.
+
+        Args:
+            name: The name of the prompt
+            arguments: Arguments to pass to the prompt
+
+        Returns:
+            The prompt content
+        """
+        raise NotImplementedError("Client.get_prompt is not yet implemented")
+
+    async def complete(
+        self,
+        ref: types.ResourceTemplateReference | types.PromptReference,
+        argument: dict[str, str],
+        context_arguments: dict[str, str] | None = None,
+    ) -> types.CompleteResult:
+        """
+        Get completions for a prompt or resource template argument.
+
+        Args:
+            ref: Reference to the prompt or resource template
+            argument: The argument to complete
+            context_arguments: Additional context arguments
+
+        Returns:
+            Completion suggestions
+        """
+        raise NotImplementedError("Client.complete is not yet implemented")
+
+    async def list_tools(
+        self,
+        cursor: str | None = None,
+        *,
+        params: types.PaginatedRequestParams | None = None,
+    ) -> types.ListToolsResult:
+        """
+        List available tools from the server.
+
+        Args:
+            cursor: Pagination cursor (deprecated, use params instead)
+            params: Full pagination parameters
+
+        Returns:
+            List of available tools
+        """
+        raise NotImplementedError("Client.list_tools is not yet implemented")
+
+    async def send_roots_list_changed(self) -> None:
+        """Send a notification that the roots list has changed."""
+        raise NotImplementedError("Client.send_roots_list_changed is not yet implemented")
+
+    @property
+    def session(self) -> ClientSession:
+        """
+        Get the underlying ClientSession.
+
+        This provides access to the full ClientSession API for advanced use cases.
+        """
+        raise NotImplementedError("Client.session is not yet implemented")

src/mcp/client/transports/__init__.py

@@ -0,0 +1,5 @@
+"""In-memory transport implementations for MCP clients."""
+
+from mcp.client.transports.memory import InMemoryTransport
+
+__all__ = ["InMemoryTransport"]