Add doc-strings (#251)

Author: eyurtsev

examples/servers/streamable-http-stateless/mcp_simple_streamablehttp_stateless/server.py

@@ -1,3 +1,9 @@
+"""Simple MCP server example using streamable HTTP transport.
+
+This module demonstrates a basic MCP server implementation using streamable HTTP
+transport with basic math operations (add and multiply).
+"""
+
 import contextlib
 import logging
 from collections.abc import AsyncIterator
@@ -31,6 +37,16 @@ def main(
     log_level: str,
     json_response: bool,
 ) -> int:
+    """Run the MCP server with streamable HTTP transport.
+
+    Args:
+        port: Port to listen on for HTTP requests.
+        log_level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL).
+        json_response: Whether to enable JSON responses instead of SSE streams.
+
+    Returns:
+        Exit code (0 for success).
+    """
     # Configure logging
     logging.basicConfig(
         level=getattr(logging, log_level.upper()),
@@ -43,6 +59,18 @@ def main(
     async def call_tool(
         name: str, arguments: dict
     ) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
+        """Handle tool calls for math operations.
+
+        Args:
+            name: Name of the tool to call.
+            arguments: Dictionary of arguments for the tool.
+
+        Returns:
+            List of content objects with the tool result.
+
+        Raises:
+            ValueError: If the tool name is not recognized.
+        """
         if name == "add":
             return [
                 types.TextContent(
@@ -62,6 +90,11 @@ async def call_tool(
 
     @app.list_tools()
     async def list_tools() -> list[types.Tool]:
+        """List all available tools provided by this server.
+
+        Returns:
+            List of tool definitions for add and multiply operations.
+        """
         return [
             types.Tool(
                 name="add",
@@ -112,11 +145,25 @@ async def list_tools() -> list[types.Tool]:
     async def handle_streamable_http(
         scope: Scope, receive: Receive, send: Send
     ) -> None:
+        """Handle streamable HTTP requests through the session manager.
+
+        Args:
+            scope: ASGI scope object.
+            receive: ASGI receive callable.
+            send: ASGI send callable.
+        """
         await session_manager.handle_request(scope, receive, send)
 
     @contextlib.asynccontextmanager
     async def lifespan(app: Starlette) -> AsyncIterator[None]:
-        """Context manager for session manager."""
+        """Context manager for session manager lifecycle.
+
+        Args:
+            app: The Starlette application instance.
+
+        Yields:
+            None during the application lifetime.
+        """
         async with session_manager.run():
             logger.info("Application started with StreamableHTTP session manager!")
             try:

langchain_mcp_adapters/__init__.py

@@ -0,0 +1,6 @@
+"""LangChain MCP Adapters - Connect MCP servers with LangChain applications.
+
+This package provides adapters to connect MCP (Model Context Protocol) servers
+with LangChain applications, converting MCP tools, prompts, and resources into
+LangChain-compatible formats.
+"""

langchain_mcp_adapters/client.py

@@ -1,3 +1,9 @@
+"""Client for connecting to multiple MCP servers and loading LangChain-compatible resources.
+
+This module provides the MultiServerMCPClient class for managing connections to multiple
+MCP servers and loading tools, prompts, and resources from them.
+"""
+
 import asyncio
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
@@ -169,6 +175,11 @@ async def get_resources(
             return await load_mcp_resources(session, uris=uris)
 
     async def __aenter__(self) -> "MultiServerMCPClient":
+        """Async context manager entry point.
+
+        Raises:
+            NotImplementedError: Context manager support has been removed.
+        """
         raise NotImplementedError(ASYNC_CONTEXT_MANAGER_ERROR)
 
     def __aexit__(
@@ -177,6 +188,16 @@ def __aexit__(
         exc_val: BaseException | None,
         exc_tb: TracebackType | None,
     ) -> None:
+        """Async context manager exit point.
+
+        Args:
+            exc_type: Exception type if an exception occurred.
+            exc_val: Exception value if an exception occurred.
+            exc_tb: Exception traceback if an exception occurred.
+
+        Raises:
+            NotImplementedError: Context manager support has been removed.
+        """
         raise NotImplementedError(ASYNC_CONTEXT_MANAGER_ERROR)
 
 

langchain_mcp_adapters/prompts.py

@@ -1,3 +1,9 @@
+"""Prompts adapter for converting MCP prompts to LangChain messages.
+
+This module provides functionality to convert MCP prompt messages into LangChain
+message objects, handling both user and assistant message types.
+"""
+
 from typing import Any
 
 from langchain_core.messages import AIMessage, HumanMessage
@@ -35,7 +41,16 @@ async def load_mcp_prompt(
     *,
     arguments: dict[str, Any] | None = None,
 ) -> list[HumanMessage | AIMessage]:
-    """Load MCP prompt and convert to LangChain messages."""
+    """Load MCP prompt and convert to LangChain messages.
+
+    Args:
+        session: The MCP client session.
+        name: Name of the prompt to load.
+        arguments: Optional arguments to pass to the prompt.
+
+    Returns:
+        A list of LangChain messages converted from the MCP prompt.
+    """
     response = await session.get_prompt(name, arguments)
     return [
         convert_mcp_prompt_message_to_langchain_message(message) for message in response.messages

langchain_mcp_adapters/resources.py

@@ -1,3 +1,9 @@
+"""Resources adapter for converting MCP resources to LangChain Blobs.
+
+This module provides functionality to convert MCP resources into LangChain Blob
+objects, handling both text and binary resource content types.
+"""
+
 import base64
 
 from langchain_core.documents.base import Blob
@@ -31,12 +37,11 @@ async def get_mcp_resource(session: ClientSession, uri: str) -> list[Blob]:
     """Fetch a single MCP resource and convert it to LangChain Blobs.
 
     Args:
-        session: MCP client session
-        uri: URI of the resource to fetch
+        session: MCP client session.
+        uri: URI of the resource to fetch.
 
     Returns:
-        A list of LangChain Blobs
-
+        A list of LangChain Blobs.
     """
     contents_result = await session.read_resource(uri)
     if not contents_result.contents or len(contents_result.contents) == 0:
@@ -55,16 +60,17 @@ async def load_mcp_resources(
     """Load MCP resources and convert them to LangChain Blobs.
 
     Args:
-        session: MCP client session
-        uris: List of URIs to load.
-            If None, all resources will be loaded.
-            NOTE: if you specify None, dynamic resources will NOT be loaded,
-            as they need the parameters to be provided,
-            and are ignored by MCP SDK's session.list_resources() method.
+        session: MCP client session.
+        uris: List of URIs to load. If None, all resources will be loaded.
+            Note: Dynamic resources will NOT be loaded when None is specified,
+            as they require parameters and are ignored by the MCP SDK's
+            session.list_resources() method.
 
     Returns:
-        A list of LangChain Blobs
+        A list of LangChain Blobs.
 
+    Raises:
+        RuntimeError: If an error occurs while fetching a resource.
     """
     blobs = []
 

langchain_mcp_adapters/sessions.py

@@ -1,3 +1,9 @@
+"""Session management for different MCP transport types.
+
+This module provides connection configurations and session management for various
+MCP transport types including stdio, SSE, WebSocket, and streamable HTTP.
+"""
+
 from __future__ import annotations
 
 import os
@@ -30,15 +36,30 @@
 
 
 class McpHttpClientFactory(Protocol):
+    """Protocol for creating httpx.AsyncClient instances for MCP connections."""
+
     def __call__(
         self,
         headers: dict[str, str] | None = None,
         timeout: httpx.Timeout | None = None,
         auth: httpx.Auth | None = None,
-    ) -> httpx.AsyncClient: ...
+    ) -> httpx.AsyncClient:
+        """Create an httpx.AsyncClient instance.
+
+        Args:
+            headers: HTTP headers to include in requests.
+            timeout: Request timeout configuration.
+            auth: Authentication configuration.
+
+        Returns:
+            Configured httpx.AsyncClient instance.
+        """
+        ...
 
 
 class StdioConnection(TypedDict):
+    """Configuration for stdio transport connections to MCP servers."""
+
     transport: Literal["stdio"]
 
     command: str
@@ -74,6 +95,8 @@ class StdioConnection(TypedDict):
 
 
 class SSEConnection(TypedDict):
+    """Configuration for Server-Sent Events (SSE) transport connections to MCP servers."""
+
     transport: Literal["sse"]
 
     url: str
@@ -107,9 +130,10 @@ class SSEConnection(TypedDict):
 
 
 class StreamableHttpConnection(TypedDict):
-    transport: Literal["streamable_http"]
     """Connection configuration for Streamable HTTP transport."""
 
+    transport: Literal["streamable_http"]
+
     url: str
     """The URL of the endpoint to connect to."""
 
@@ -137,6 +161,8 @@ class StreamableHttpConnection(TypedDict):
 
 
 class WebsocketConnection(TypedDict):
+    """Configuration for WebSocket transport connections to MCP servers."""
+
     transport: Literal["websocket"]
 
     url: str
@@ -163,14 +189,16 @@ async def _create_stdio_session(  # noqa: PLR0913
     """Create a new session to an MCP server using stdio.
 
     Args:
-        command: Command to execute
-        args: Arguments for the command
-        env: Environment variables for the command
-        cwd: Working directory for the command
-        encoding: Character encoding
-        encoding_error_handler: How to handle encoding errors
-        session_kwargs: Additional keyword arguments to pass to the ClientSession
+        command: Command to execute.
+        args: Arguments for the command.
+        env: Environment variables for the command.
+        cwd: Working directory for the command.
+        encoding: Character encoding.
+        encoding_error_handler: How to handle encoding errors.
+        session_kwargs: Additional keyword arguments to pass to the ClientSession.
 
+    Yields:
+        An initialized ClientSession.
     """
     # NOTE: execution commands (e.g., `uvx` / `npx`) require PATH envvar to be set.
     # To address this, we automatically inject existing PATH envvar into the `env` value,
@@ -210,14 +238,16 @@ async def _create_sse_session(  # noqa: PLR0913
     """Create a new session to an MCP server using SSE.
 
     Args:
-        url: URL of the SSE server
-        headers: HTTP headers to send to the SSE endpoint
-        timeout: HTTP timeout
-        sse_read_timeout: SSE read timeout
-        session_kwargs: Additional keyword arguments to pass to the ClientSession
-        httpx_client_factory: Custom factory for httpx.AsyncClient (optional)
-        auth: httpx.Auth | None = None
+        url: URL of the SSE server.
+        headers: HTTP headers to send to the SSE endpoint.
+        timeout: HTTP timeout.
+        sse_read_timeout: SSE read timeout.
+        session_kwargs: Additional keyword arguments to pass to the ClientSession.
+        httpx_client_factory: Custom factory for httpx.AsyncClient (optional).
+        auth: Authentication for the HTTP client.
 
+    Yields:
+        An initialized ClientSession.
     """
     # Create and store the connection
     kwargs = {}
@@ -249,15 +279,17 @@ async def _create_streamable_http_session(  # noqa: PLR0913
     """Create a new session to an MCP server using Streamable HTTP.
 
     Args:
-        url: URL of the endpoint to connect to
-        headers: HTTP headers to send to the endpoint
-        timeout: HTTP timeout
-        sse_read_timeout: How long (in seconds) the client will wait for a new event before disconnecting
-        terminate_on_close: Whether to terminate the session on close
-        session_kwargs: Additional keyword arguments to pass to the ClientSession
-        httpx_client_factory: Custom factory for httpx.AsyncClient (optional)
-        auth: httpx.Auth | None = None
+        url: URL of the endpoint to connect to.
+        headers: HTTP headers to send to the endpoint.
+        timeout: HTTP timeout.
+        sse_read_timeout: How long the client will wait for a new event before disconnecting.
+        terminate_on_close: Whether to terminate the session on close.
+        session_kwargs: Additional keyword arguments to pass to the ClientSession.
+        httpx_client_factory: Custom factory for httpx.AsyncClient (optional).
+        auth: Authentication for the HTTP client.
 
+    Yields:
+        An initialized ClientSession.
     """
     # Create and store the connection
     kwargs = {}
@@ -288,12 +320,14 @@ async def _create_websocket_session(
     """Create a new session to an MCP server using Websockets.
 
     Args:
-        url: URL of the Websocket endpoint
-        session_kwargs: Additional keyword arguments to pass to the ClientSession
+        url: URL of the Websocket endpoint.
+        session_kwargs: Additional keyword arguments to pass to the ClientSession.
 
-    Raises:
-        ImportError: If websockets package is not installed
+    Yields:
+        An initialized ClientSession.
 
+    Raises:
+        ImportError: If websockets package is not installed.
     """
     try:
         from mcp.client.websocket import websocket_client