Merge pull request #14 from andylim-duo/upstream-03182026

Upstream 03182026

Author: andylim-duo

docs/api.md

@@ -0,0 +1,35 @@
+"""Generate the code reference pages and navigation."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+root = Path(__file__).parent.parent.parent
+src = root / "src"
+
+for path in sorted(src.rglob("*.py")):
+    module_path = path.relative_to(src).with_suffix("")
+    doc_path = path.relative_to(src).with_suffix(".md")
+    full_doc_path = Path("api", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1].startswith("_"):
+        continue
+
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(parts)
+        fd.write(f"::: {ident}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))
+
+with mkdocs_gen_files.open("api/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

docs/hooks/gen_ref_pages.py

@@ -64,4 +64,4 @@ npx -y @modelcontextprotocol/inspector
 
 ## API Reference
 
-Full API documentation is available in the [API Reference](api.md).
+Full API documentation is available in the [API Reference](api/mcp/index.md).

docs/index.md

@@ -169,6 +169,30 @@ 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 `initialize_result` property
+
+`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):**
+
+```python
+capabilities = session.get_server_capabilities()
+# server_info, instructions, protocol_version were not stored — had to capture initialize() return value
+```
+
+**After (v2):**
+
+```python
+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.initialize_result` returns the same `InitializeResult` but is non-nullable — initialization is guaranteed inside the context manager, so no `None` check is needed. This replaces v1's `Client.server_capabilities`; use `client.initialize_result.capabilities` instead.
+
 ### `McpError` renamed to `MCPError`
 
 The `McpError` exception class has been renamed to `MCPError` for consistent naming with the MCP acronym style used throughout the SDK.
@@ -859,6 +883,6 @@ The lowlevel `Server` also now exposes a `session_manager` property to access th
 
 If you encounter issues during migration:
 
-1. Check the [API Reference](api.md) for updated method signatures
+1. Check the [API Reference](api/mcp/index.md) for updated method signatures
 2. Review the [examples](https://github.com/modelcontextprotocol/python-sdk/tree/main/examples) for updated usage patterns
 3. Open an issue on [GitHub](https://github.com/modelcontextprotocol/python-sdk/issues) if you find a bug or need further assistance

docs/migration.md

@@ -25,7 +25,7 @@ nav:
           - Introduction: experimental/tasks.md
           - Server Implementation: experimental/tasks-server.md
           - Client Usage: experimental/tasks-client.md
-  - API Reference: api.md
+  - API Reference: api/
 
 theme:
   name: "material"
@@ -115,19 +115,22 @@ plugins:
   - social:
       enabled: !ENV [ENABLE_SOCIAL_CARDS, false]
   - glightbox
+  - gen-files:
+      scripts:
+        - docs/hooks/gen_ref_pages.py
+  - literate-nav:
+      nav_file: SUMMARY.md
   - mkdocstrings:
       handlers:
         python:
-          paths: [src/mcp]
+          paths: [src]
           options:
             relative_crossrefs: true
             members_order: source
             separate_signature: true
             show_signature_annotations: true
             signature_crossrefs: true
             group_by_category: false
-            # 3 because docs are in pages with an H2 just above them
-            heading_level: 3
           inventories:
             - url: https://docs.python.org/3/objects.inv
             - url: https://docs.pydantic.dev/latest/objects.inv

mkdocs.yml

@@ -74,7 +74,9 @@ dev = [
 ]
 docs = [
     "mkdocs>=1.6.1",
+    "mkdocs-gen-files>=0.5.0",
     "mkdocs-glightbox>=0.4.0",
+    "mkdocs-literate-nav>=0.6.1",
     "mkdocs-material[imaging]>=9.5.45",
     "mkdocstrings-python>=2.0.1",
 ]

pyproject.toml

@@ -19,6 +19,7 @@
     EmptyResult,
     GetPromptResult,
     Implementation,
+    InitializeResult,
     ListPromptsResult,
     ListResourcesResult,
     ListResourceTemplatesResult,
@@ -29,7 +30,6 @@
     ReadResourceResult,
     RequestParamsMeta,
     ResourceTemplateReference,
-    ServerCapabilities,
 )
 
 
@@ -155,9 +155,16 @@ def session(self) -> ClientSession:
         return self._session
 
     @property
-    def server_capabilities(self) -> ServerCapabilities | None:
-        """The server capabilities received during initialization, or None if not yet initialized."""
-        return self.session.get_server_capabilities()
+    def initialize_result(self) -> InitializeResult:
+        """The server's InitializeResult.
+
+        Contains server_info, capabilities, instructions, and the negotiated protocol_version.
+        Raises RuntimeError if accessed outside the context manager.
+        """
+        result = self.session.initialize_result
+        if result is None:  # pragma: no cover
+            raise RuntimeError("Client must be used within an async context manager")
+        return result
 
     async def send_ping(self, *, meta: RequestParamsMeta | None = None) -> EmptyResult:
         """Send a ping request to the server."""

src/mcp/client/client.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_capabilities: types.ServerCapabilities | None = None
+        self._initialize_result: types.InitializeResult | None = None
         self._experimental_features: ExperimentalClientFeatures | None = None
 
         # Experimental: Task handlers (use defaults if not provided)
@@ -185,18 +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_capabilities = result.capabilities
+        self._initialize_result = result
 
         await self.send_notification(types.InitializedNotification())
 
         return result
 
-    def get_server_capabilities(self) -> types.ServerCapabilities | None:
-        """Return the server capabilities received during initialization.
+    @property
+    def initialize_result(self) -> types.InitializeResult | None:
+        """The server's InitializeResult. None until initialize() has been called.
 
-        Returns None if the session has not been initialized yet.
+        Contains server_info, capabilities, instructions, and the negotiated protocol_version.
         """
-        return self._server_capabilities
+        return self._initialize_result
 
     @property
     def experimental(self) -> ExperimentalClientFeatures:

src/mcp/client/session.py

@@ -496,7 +496,7 @@ async def send_progress_notification(
             related_request_id,
         )
 
-    async def send_resource_list_changed(self) -> None:  # pragma: no cover
+    async def send_resource_list_changed(self) -> None:
         """Send a resource list changed notification."""
         await self.send_notification(types.ResourceListChangedNotification())
 

src/mcp/server/session.py

@@ -10,7 +10,7 @@
 from mcp.shared.message import SessionMessage
 
 
-@asynccontextmanager  # pragma: no cover
+@asynccontextmanager
 async def websocket_server(scope: Scope, receive: Receive, send: Send):
     """WebSocket server transport for MCP. This is an ASGI application, suitable for use
     with a framework like Starlette and a server like Hypercorn.
@@ -34,13 +34,13 @@ async def ws_reader():
                 async for msg in websocket.iter_text():
                     try:
                         client_message = types.jsonrpc_message_adapter.validate_json(msg, by_name=False)
-                    except ValidationError as exc:
+                    except ValidationError as exc:  # pragma: no cover
                         await read_stream_writer.send(exc)
                         continue
 
                     session_message = SessionMessage(client_message)
                     await read_stream_writer.send(session_message)
-        except anyio.ClosedResourceError:
+        except anyio.ClosedResourceError:  # pragma: no cover
             await websocket.close()
 
     async def ws_writer():
@@ -49,7 +49,7 @@ async def ws_writer():
                 async for session_message in write_stream_reader:
                     obj = session_message.message.model_dump_json(by_alias=True, exclude_unset=True)
                     await websocket.send_text(obj)
-        except anyio.ClosedResourceError:
+        except anyio.ClosedResourceError:  # pragma: no cover
             await websocket.close()
 
     async with anyio.create_task_group() as tg: