refactor(client): rename to initialize_result, decompose Client properties

- ClientSession.server_params -> initialize_result (avoids collision with
  StdioServerParameters idiom; matches Go SDK and FastMCP)
- Client: replace server_params proxy with non-nullable server_capabilities,
  server_info, server_instructions (init is guaranteed inside the context
  manager, so | None was unreachable)
- Client.server_capabilities is preserved from v1 with a better type

Github-Issue: #1018

Author: maxisbey

docs/migration.md

@@ -169,9 +169,9 @@ result = await session.list_resources(params=PaginatedRequestParams(cursor="next
 result = await session.list_tools(params=PaginatedRequestParams(cursor="next_page_token"))
 ```
 
-### `ClientSession.get_server_capabilities()` replaced by `server_params` property
+### `ClientSession.get_server_capabilities()` replaced by `initialize_result` property
 
-`ClientSession` now stores the full `InitializeResult` via a `server_params` property, mirroring `ServerSession.client_params`. This is the new way to access server metadata after initialization — `server_info`, `capabilities`, `instructions`, and the negotiated `protocol_version` are all available through this single property. The `get_server_capabilities()` method has been removed.
+`ClientSession` now stores the full `InitializeResult` via an `initialize_result` property. This provides access to `server_info`, `capabilities`, `instructions`, and the negotiated `protocol_version` through a single property. The `get_server_capabilities()` method has been removed.
 
 **Before (v1):**
 
@@ -183,15 +183,15 @@ capabilities = session.get_server_capabilities()
 **After (v2):**
 
 ```python
-params = session.server_params
-if params is not None:
-    capabilities = params.capabilities
-    server_info = params.server_info
-    instructions = params.instructions
-    version = params.protocol_version
+result = session.initialize_result
+if result is not None:
+    capabilities = result.capabilities
+    server_info = result.server_info
+    instructions = result.instructions
+    version = result.protocol_version
 ```
 
-The high-level `Client.server_capabilities` property has similarly been replaced by `Client.server_params`.
+The high-level `Client` exposes these directly as non-nullable properties (initialization is guaranteed inside the context manager): `client.server_capabilities`, `client.server_info`, and `client.server_instructions`.
 
 ### `McpError` renamed to `MCPError`
 

src/mcp/client/client.py

@@ -30,6 +30,7 @@
     ReadResourceResult,
     RequestParamsMeta,
     ResourceTemplateReference,
+    ServerCapabilities,
 )
 
 
@@ -96,6 +97,7 @@ async def main():
     """Callback for handling elicitation requests."""
 
     _session: ClientSession | None = field(init=False, default=None)
+    _initialize_result: InitializeResult | None = field(init=False, default=None)
     _exit_stack: AsyncExitStack | None = field(init=False, default=None)
     _transport: Transport = field(init=False)
 
@@ -129,7 +131,7 @@ async def __aenter__(self) -> Client:
                 )
             )
 
-            await self._session.initialize()
+            self._initialize_result = await self._session.initialize()
 
             # Transfer ownership to self for __aexit__ to handle
             self._exit_stack = exit_stack.pop_all()
@@ -140,6 +142,7 @@ async def __aexit__(self, exc_type: type[BaseException] | None, exc_val: BaseExc
         if self._exit_stack:  # pragma: no branch
             await self._exit_stack.__aexit__(exc_type, exc_val, exc_tb)
         self._session = None
+        self._initialize_result = None
 
     @property
     def session(self) -> ClientSession:
@@ -155,12 +158,25 @@ def session(self) -> ClientSession:
         return self._session
 
     @property
-    def server_params(self) -> InitializeResult | None:
-        """The server's initialization response. None if not yet initialized.
+    def server_capabilities(self) -> ServerCapabilities:
+        """Capabilities the server advertised during initialization."""
+        if self._initialize_result is None:
+            raise RuntimeError("Client must be used within an async context manager")
+        return self._initialize_result.capabilities
 
-        Contains server_info, capabilities, instructions, and the negotiated protocol_version.
-        """
-        return self.session.server_params
+    @property
+    def server_info(self) -> Implementation:
+        """The server's name, version, and other implementation details."""
+        if self._initialize_result is None:
+            raise RuntimeError("Client must be used within an async context manager")
+        return self._initialize_result.server_info
+
+    @property
+    def server_instructions(self) -> str | None:
+        """Instructions describing how to use the server and its features, if provided."""
+        if self._initialize_result is None:
+            raise RuntimeError("Client must be used within an async context manager")
+        return self._initialize_result.instructions
 
     async def send_ping(self, *, meta: RequestParamsMeta | None = None) -> EmptyResult:
         """Send a ping request to the server."""

src/mcp/client/session.py

@@ -131,7 +131,7 @@ def __init__(
         self._logging_callback = logging_callback or _default_logging_callback
         self._message_handler = message_handler or _default_message_handler
         self._tool_output_schemas: dict[str, dict[str, Any] | None] = {}
-        self._server_params: types.InitializeResult | None = None
+        self._initialize_result: types.InitializeResult | None = None
         self._experimental_features: ExperimentalClientFeatures | None = None
 
         # Experimental: Task handlers (use defaults if not provided)
@@ -185,20 +185,19 @@ async def initialize(self) -> types.InitializeResult:
         if result.protocol_version not in SUPPORTED_PROTOCOL_VERSIONS:
             raise RuntimeError(f"Unsupported protocol version from the server: {result.protocol_version}")
 
-        self._server_params = result
+        self._initialize_result = result
 
         await self.send_notification(types.InitializedNotification())
 
         return result
 
     @property
-    def server_params(self) -> types.InitializeResult | None:
-        """The server's initialization response. None if not yet initialized.
+    def initialize_result(self) -> types.InitializeResult | None:
+        """The server's InitializeResult. None until initialize() has been called.
 
-        Mirrors ServerSession.client_params. Contains server_info, capabilities,
-        instructions, and the negotiated protocol_version.
+        Contains server_info, capabilities, instructions, and the negotiated protocol_version.
         """
-        return self._server_params
+        return self._initialize_result
 
     @property
     def experimental(self) -> ExperimentalClientFeatures:

tests/client/test_client.py

@@ -99,15 +99,16 @@ def greeting_prompt(name: str) -> str:
 async def test_client_is_initialized(app: MCPServer):
     """Test that the client is initialized after entering context."""
     async with Client(app) as client:
-        assert client.server_params is not None
-        assert client.server_params.capabilities == snapshot(
+        assert client.server_capabilities == snapshot(
             ServerCapabilities(
                 experimental={},
                 prompts=PromptsCapability(list_changed=False),
                 resources=ResourcesCapability(subscribe=False, list_changed=False),
                 tools=ToolsCapability(list_changed=False),
             )
         )
+        assert client.server_info.name == "test"
+        assert client.server_instructions is None
 
 
 async def test_client_with_simple_server(simple_server: Server):
@@ -195,6 +196,17 @@ def test_client_session_property_before_enter(app: MCPServer):
         client.session
 
 
+def test_client_server_properties_before_enter(app: MCPServer):
+    """Test that server_* properties raise RuntimeError outside the context manager."""
+    client = Client(app)
+    with pytest.raises(RuntimeError, match="Client must be used within an async context manager"):
+        client.server_capabilities
+    with pytest.raises(RuntimeError, match="Client must be used within an async context manager"):
+        client.server_info
+    with pytest.raises(RuntimeError, match="Client must be used within an async context manager"):
+        client.server_instructions
+
+
 async def test_client_reentry_raises_runtime_error(app: MCPServer):
     """Test that reentering a client raises RuntimeError."""
     async with Client(app) as client:

tests/client/test_session.py

@@ -540,8 +540,8 @@ async def mock_server():
 
 
 @pytest.mark.anyio
-async def test_server_params():
-    """Test that server_params is None before init and contains the full result after."""
+async def test_initialize_result():
+    """Test that initialize_result is None before init and contains the full result after."""
     client_to_server_send, client_to_server_receive = anyio.create_memory_object_stream[SessionMessage](1)
     server_to_client_send, server_to_client_receive = anyio.create_memory_object_stream[SessionMessage](1)
 
@@ -593,17 +593,17 @@ async def mock_server():
         server_to_client_send,
         server_to_client_receive,
     ):
-        assert session.server_params is None
+        assert session.initialize_result is None
 
         tg.start_soon(mock_server)
         await session.initialize()
 
-        params = session.server_params
-        assert params is not None
-        assert params.server_info == expected_server_info
-        assert params.capabilities == expected_capabilities
-        assert params.instructions == expected_instructions
-        assert params.protocol_version == LATEST_PROTOCOL_VERSION
+        result = session.initialize_result
+        assert result is not None
+        assert result.server_info == expected_server_info
+        assert result.capabilities == expected_capabilities
+        assert result.instructions == expected_instructions
+        assert result.protocol_version == LATEST_PROTOCOL_VERSION
 
 
 @pytest.mark.anyio

tests/client/transports/test_memory.py

@@ -69,7 +69,7 @@ async def test_with_mcpserver(mcpserver_server: MCPServer):
 async def test_server_is_running(mcpserver_server: MCPServer):
     """Test that the server is running and responding to requests."""
     async with Client(mcpserver_server) as client:
-        assert client.server_params is not None
+        assert client.server_capabilities.tools is not None
 
 
 async def test_list_tools(mcpserver_server: MCPServer):