langchain-mcp-tools 0.1.11__py3-none-any.whl → 0.2.1__py3-none-any.whl

langchain_mcp_tools/__init__.py

@@ -2,4 +2,5 @@
 from .langchain_mcp_tools import (
   convert_mcp_to_langchain_tools,
   McpServerCleanupFn,
+  McpServersConfig,
 )

langchain_mcp_tools/langchain_mcp_tools.py

@@ -1,8 +1,4 @@
 # Standard library imports
-from anyio.streams.memory import (
-    MemoryObjectReceiveStream,
-    MemoryObjectSendStream,
-)
 import logging
 import os
 import sys
@@ -11,21 +7,27 @@ from typing import (
     Any,
     Awaitable,
     Callable,
-    Dict,
-    List,
+    cast,
     NoReturn,
-    Optional,
-    Tuple,
-    Type,
+    NotRequired,
+    TextIO,
     TypeAlias,
+    TypedDict,
 )
+from urllib.parse import urlparse
 
 # Third-party imports
 try:
+    from anyio.streams.memory import (
+        MemoryObjectReceiveStream,
+        MemoryObjectSendStream,
+    )
     from jsonschema_pydantic import jsonschema_to_pydantic  # type: ignore
     from langchain_core.tools import BaseTool, ToolException
     from mcp import ClientSession
+    from mcp.client.sse import sse_client
     from mcp.client.stdio import stdio_client, StdioServerParameters
+    from mcp.client.websocket import websocket_client
     import mcp.types as mcp_types
     from pydantic import BaseModel
     # from pydantic_core import to_json
@@ -35,6 +37,27 @@ except ImportError as e:
     sys.exit(1)
 
 
+class McpServerCommandBasedConfig(TypedDict):
+    command: str
+    args: NotRequired[list[str] | None]
+    env:  NotRequired[dict[str, str] | None]
+    cwd: NotRequired[str | None]
+    errlog: NotRequired[TextIO | None]
+
+
+class McpServerUrlBasedConfig(TypedDict):
+    url: str
+    args: NotRequired[list[str] | None]
+    env:  NotRequired[dict[str, str] | None]
+    cwd: NotRequired[str | None]
+    errlog: NotRequired[TextIO | None]
+
+
+McpServerConfig = McpServerCommandBasedConfig | McpServerUrlBasedConfig
+
+McpServersConfig = dict[str, McpServerConfig]
+
+
 def fix_schema(schema: dict) -> dict:
     """Converts JSON Schema 'type': ['string', 'null'] to 'anyOf' format"""
     if isinstance(schema, dict):
@@ -48,7 +71,7 @@ def fix_schema(schema: dict) -> dict:
 
 # Type alias for the bidirectional communication channels with the MCP server
 # FIXME: not defined in mcp.types, really?
-StdioTransport: TypeAlias = tuple[
+Transport: TypeAlias = tuple[
     MemoryObjectReceiveStream[mcp_types.JSONRPCMessage | Exception],
     MemoryObjectSendStream[mcp_types.JSONRPCMessage]
 ]
@@ -56,10 +79,10 @@ StdioTransport: TypeAlias = tuple[
 
 async def spawn_mcp_server_and_get_transport(
     server_name: str,
-    server_config: Dict[str, Any],
+    server_config: McpServerConfig,
     exit_stack: AsyncExitStack,
     logger: logging.Logger = logging.getLogger(__name__)
-) -> StdioTransport:
+) -> Transport:
     """
     Spawns an MCP server process and establishes communication channels.
 
@@ -79,54 +102,75 @@ async def spawn_mcp_server_and_get_transport(
         logger.info(f'MCP server "{server_name}": '
                     f'initializing with: {server_config}')
 
-        # NOTE: `uv` and `npx` seem to require PATH to be set.
-        # To avoid confusion, it was decided to automatically append it
-        # to the env if not explicitly set by the config.
-        env = dict(server_config.get('env', {}))
-        if 'PATH' not in env:
-            env['PATH'] = os.environ.get('PATH', '')
-
-        # Create server parameters with command, arguments and environment
-        server_params = StdioServerParameters(
-            command=server_config['command'],
-            args=server_config.get('args', []),
-            env=env,
-            cwd=server_config.get('cwd', None)
-        )
+        url_str = str(server_config.get('url'))  # None becomes 'None'
+        # no exception thrown even for a malformed URL
+        url_scheme = urlparse(url_str).scheme
 
-        # Initialize stdio client and register it with exit stack for cleanup
-        # NOTE: Why the key name `stderr` for `server_config` was chosen:
-        # Unlike the TypeScript SDK's `StdioServerParameters`, the Python SDK's
-        # `StdioServerParameters` doesn't include `stderr`.
-        # Instead, it calls `stdio_client()` with a separate argument
-        # `errlog`.  I once thought of using `errlog` for the key for the
-        # Pyhton version, but decided to follow the TypeScript version since
-        # its public API already exposes the key name and I choose consistency.
-        stdio_transport = await exit_stack.enter_async_context(
-            stdio_client(
-                server_params,
-                errlog=server_config.get('stderr', None)
+        if url_scheme in ('http', 'https'):
+            transport = await exit_stack.enter_async_context(
+                sse_client(url_str)
+            )
+
+        elif url_scheme in ('ws', 'wss'):
+            transport = await exit_stack.enter_async_context(
+                websocket_client(url_str)
+            )
+
+        else:
+            # NOTE: `uv` and `npx` seem to require PATH to be set.
+            # To avoid confusion, it was decided to automatically append it
+            # to the env if not explicitly set by the config.
+            config = cast(McpServerCommandBasedConfig, server_config)
+            # env = config.get('env', {}) does't work since it can yield None
+            env_val = config.get('env')
+            env = {} if env_val is None else dict(env_val)
+            if 'PATH' not in env:
+                env['PATH'] = os.environ.get('PATH', '')
+
+            # Use stdio client for commands
+            # args = config.get('args', []) does't work since it can yield None
+            args_val = config.get('args')
+            args = [] if args_val is None else list(args_val)
+            server_parameters = StdioServerParameters(
+                command=config.get('command', ''),
+                args=args,
+                env=env,
+                cwd=config.get('cwd', None)
+            )
+
+            # Initialize stdio client and register it with exit stack for
+            # cleanup
+            # NOTE: Why the key name `errlog` for `server_config` was chosen:
+            # Unlike TypeScript SDK's `StdioServerParameters`, the Python
+            # SDK's `StdioServerParameters` doesn't include `stderr: int`.
+            # Instead, it calls `stdio_client()` with a separate argument
+            # `errlog: TextIO`.  I once included `stderr: int` for
+            # compatibility with the TypeScript version, but decided to
+            # follow the Python SDK more closely.
+            errlog_val = server_config.get('errlog')
+            kwargs = {'errlog': errlog_val} if errlog_val is not None else {}
+            transport = await exit_stack.enter_async_context(
+                stdio_client(server_parameters, **kwargs)
             )
-        )
     except Exception as e:
         logger.error(f'Error spawning MCP server: {str(e)}')
         raise
 
-    return stdio_transport
+    return transport
 
 
 async def get_mcp_server_tools(
     server_name: str,
-    stdio_transport: StdioTransport,
+    transport: Transport,
     exit_stack: AsyncExitStack,
     logger: logging.Logger = logging.getLogger(__name__)
-) -> List[BaseTool]:
+) -> list[BaseTool]:
     """
     Retrieves and converts MCP server tools to LangChain format.
 
     Args:
         server_name: Server instance name to use for better logging
-        stdio_transport: Communication channels tuple
+        transport: Communication channels tuple
         exit_stack: Context manager for cleanup handling
         logger: Logger instance for debugging and monitoring
 
@@ -137,7 +181,7 @@ async def get_mcp_server_tools(
         Exception: If tool conversion fails
     """
     try:
-        read, write = stdio_transport
+        read, write = transport
 
         # Use an intermediate `asynccontextmanager` to log the cleanup message
         @asynccontextmanager
@@ -164,7 +208,7 @@ async def get_mcp_server_tools(
         tools_response = await session.list_tools()
 
         # Wrap MCP tools into LangChain tools
-        langchain_tools: List[BaseTool] = []
+        langchain_tools: list[BaseTool] = []
         for tool in tools_response.tools:
 
             # Define adapter class to convert MCP tool to LangChain format
@@ -172,10 +216,10 @@ async def get_mcp_server_tools(
                 name: str = tool.name or 'NO NAME'
                 description: str = tool.description or ''
                 # Convert JSON schema to Pydantic model for argument validation
-                args_schema: Type[BaseModel] = jsonschema_to_pydantic(
+                args_schema: type[BaseModel] = jsonschema_to_pydantic(
                     fix_schema(tool.inputSchema)  # Apply schema conversion
                 )
-                session: Optional[ClientSession] = None
+                session: ClientSession | None = None
 
                 def _run(self, **kwargs: Any) -> NoReturn:
                     raise NotImplementedError(
@@ -272,9 +316,9 @@ McpServerCleanupFn = Callable[[], Awaitable[None]]
 
 
 async def convert_mcp_to_langchain_tools(
-    server_configs: Dict[str, Dict[str, Any]],
-    logger: Optional[logging.Logger] = None
-) -> Tuple[List[BaseTool], McpServerCleanupFn]:
+    server_configs: dict[str, McpServerConfig],
+    logger: logging.Logger | None = None
+) -> tuple[list[BaseTool], McpServerCleanupFn]:
     """Initialize multiple MCP servers and convert their tools to
     LangChain format.
 
@@ -318,7 +362,7 @@ async def convert_mcp_to_langchain_tools(
             logger = init_logger()
 
     # Initialize AsyncExitStack for managing multiple server lifecycles
-    stdio_transports: List[StdioTransport] = []
+    transports: list[Transport] = []
     async_exit_stack = AsyncExitStack()
 
     # Spawn all MCP servers concurrently
@@ -327,24 +371,24 @@ async def convert_mcp_to_langchain_tools(
         # is spawned, i.e. after returning from the `await`, the spawned
         # subprocess starts its initialization independently of (so in
         # parallel with) the Python execution of the following lines.
-        stdio_transport = await spawn_mcp_server_and_get_transport(
+        transport = await spawn_mcp_server_and_get_transport(
             server_name,
             server_config,
             async_exit_stack,
             logger
         )
-        stdio_transports.append(stdio_transport)
+        transports.append(transport)
 
     # Convert tools from each server to LangChain format
-    langchain_tools: List[BaseTool] = []
-    for (server_name, server_config), stdio_transport in zip(
+    langchain_tools: list[BaseTool] = []
+    for (server_name, server_config), transport in zip(
         server_configs.items(),
-        stdio_transports,
+        transports,
         strict=True
     ):
         tools = await get_mcp_server_tools(
             server_name,
-            stdio_transport,
+            transport,
             async_exit_stack,
             logger
         )

{langchain_mcp_tools-0.1.11.dist-info → langchain_mcp_tools-0.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langchain-mcp-tools
-Version: 0.1.11
+Version: 0.2.1
 Summary: Model Context Protocol (MCP) To LangChain Tools Conversion Utility
 Project-URL: Bug Tracker, https://github.com/hideya/langchain-mcp-tools-py/issues
 Project-URL: Source Code, https://github.com/hideya/langchain-mcp-tools-py
@@ -12,6 +12,7 @@ Requires-Dist: jsonschema-pydantic>=0.6
 Requires-Dist: langchain>=0.3.14
 Requires-Dist: mcp>=1.6.0
 Requires-Dist: pyjson5>=1.6.8
+Requires-Dist: websockets>=15.0.1
 Provides-Extra: dev
 Requires-Dist: dotenv>=0.9.9; extra == "dev"
 Requires-Dist: langchain-anthropic>=0.3.1; extra == "dev"
@@ -65,6 +66,9 @@ pip install langchain-mcp-tools
 
 ## Quick Start
 
+A minimal but complete working usage example can be found
+[in this example in the langchain-mcp-tools-py-usage repo](https://github.com/hideya/langchain-mcp-tools-py-usage/blob/main/src/example.py)
+
 `convert_mcp_to_langchain_tools()` utility function accepts MCP server configurations
 that follow the same structure as
 [Claude for Desktop](https://modelcontextprotocol.io/quickstart/user),
@@ -73,13 +77,13 @@ and is expressed as a `dict`, e.g.:
 
 ```python
 mcp_servers = {
-    'filesystem': {
-        'command': 'npx',
-        'args': ['-y', '@modelcontextprotocol/server-filesystem', '.']
+    "filesystem": {
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
     },
-    'fetch': {
-        'command': 'uvx',
-        'args': ['mcp-server-fetch']
+    "fetch": {
+        "command": "uvx",
+        "args": ["mcp-server-fetch"]
     }
 }
 
@@ -90,7 +94,7 @@ tools, cleanup = await convert_mcp_to_langchain_tools(
 
 This utility function initializes all specified MCP servers in parallel,
 and returns LangChain Tools
-([`tools: List[BaseTool]`](https://python.langchain.com/api_reference/core/tools/langchain_core.tools.base.BaseTool.html#langchain_core.tools.base.BaseTool))
+([`tools: list[BaseTool]`](https://python.langchain.com/api_reference/core/tools/langchain_core.tools.base.BaseTool.html#langchain_core.tools.base.BaseTool))
 by gathering available MCP tools from the servers,
 and by wrapping them into LangChain tools.
 It also returns an async callback function (`cleanup: McpServerCleanupFn`)
@@ -101,8 +105,8 @@ The returned tools can be used with LangChain, e.g.:
 ```python
 # from langchain.chat_models import init_chat_model
 llm = init_chat_model(
-    model='claude-3-7-sonnet-latest',
-    model_provider='anthropic'
+    model="claude-3-7-sonnet-latest",
+    model_provider="anthropic"
 )
 
 # from langgraph.prebuilt import create_react_agent
@@ -112,22 +116,76 @@ agent = create_react_agent(
 )
 ```
 
-Find complete, minimal working usage examples
-[here](https://github.com/hideya/langchain-mcp-tools-py-usage/blob/main/src/example.py)
-
 For hands-on experimentation with MCP server integration,
 try [this LangChain application built with the utility](https://github.com/hideya/mcp-client-langchain-py)
 
 For detailed information on how to use this library, please refer to the following document:  
 ["Supercharging LangChain: Integrating 2000+ MCP with ReAct"](https://medium.com/@h1deya/supercharging-langchain-integrating-450-mcp-with-react-d4e467cbf41a)
 
-## Limitations
+## Experimental Features
+
+### Remote MCP Server Support
+
+`mcp_servers` configuration for SSE and Websocket servers are as follows:
+
+```python
+    "sse-server-name": {
+        "url": f"http://{sse_server_host}:{sse_server_port}/..."
+    },
+
+    "ws-server-name": {
+        "url": f"ws://{ws_server_host}:{ws_server_port}/..."
+    },
+```
+
+Note that the key `"url"` may be changed in the future to match
+the MCP server configurations used by Claude for Desktop once
+it introduces remote server support.
+
+A usage example can be found [here](
+https://github.com/hideya/langchain-mcp-tools-py-usage/blob/e759edf886bdaef7c162e7f228e32fbb43993e37/src/example.py#L43-L54)
+
+### Working Directory Configuration for Local MCP Servers
 
-Currently, only text results of tool calls are supported.
+The working directory that is used when spawning a local (stdio) MCP server
+can be specified with the `"cwd"` key as follows:
 
-Remote MCP server access is not supported.
+```python
+    "local-server-name": {
+        "command": "...",
+        "args": [...],
+        "cwd": "/working/directory"  # the working dir to be use by the server
+    },
+```
+
+The key name `cwd` is derived from Python SDK's `StdioServerParameters`.
+
+### Configuration for Local MCP Server `stderr` Redirection
+
+A new key `"errlog"` has been introduced in to specify a file-like object
+to which local (stdio) MCP server's stderr is redirected.
+
+```python
+    log_path = f"mcp-server-{server_name}.log"
+    log_file = open(log_path, "w")
+    mcp_servers[server_name]["errlog"] = log_file
+```
+
+A usage example can be found [here](
+https://github.com/hideya/langchain-mcp-tools-py-usage/blob/e759edf886bdaef7c162e7f228e32fbb43993e37/src/example.py#L88-L108)
+
+**NOTE: Why the key name `errlog` was chosen:**  
+Unlike TypeScript SDK's `StdioServerParameters`, the Python
+SDK's `StdioServerParameters` doesn't include `stderr: int`.
+Instead, it calls `stdio_client()` with a separate argument
+`errlog: TextIO`.  I once included `stderr: int` for
+compatibility with the TypeScript version, but decided to
+follow the Python SDK more closely.
+
+## Limitations
 
-Optiional MCP client Features, Roots and Sampling, are not supported.
+- Currently, only text results of tool calls are supported.
+- MCP features other than [Tools](https://modelcontextprotocol.io/docs/concepts/tools) are not supported.
 
 ## Change Log
 

langchain_mcp_tools-0.2.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+langchain_mcp_tools/__init__.py,sha256=iatHG2fCpz143wgQUZpyFVilgri4yOh2P0vxr22gguE,114
+langchain_mcp_tools/langchain_mcp_tools.py,sha256=n4u9fN3_sVMG1CmSKk8FrlXrBt79Ly1tz0TLhmDUaic,15118
+langchain_mcp_tools/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langchain_mcp_tools-0.2.1.dist-info/licenses/LICENSE,sha256=CRC91e8v116gCpnp7h49oIa6_zjhxqnHFTREeoZFJwA,1072
+langchain_mcp_tools-0.2.1.dist-info/METADATA,sha256=6_d5jxaN8KqL6ZyJHwVDI0YQLe30xy0-7sgyRs85Zlc,7287
+langchain_mcp_tools-0.2.1.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+langchain_mcp_tools-0.2.1.dist-info/top_level.txt,sha256=aR_9V2A1Yt-Bca60KmndmGLUWb2wiM5IOG-Gkaf1dxY,20
+langchain_mcp_tools-0.2.1.dist-info/RECORD,,

langchain_mcp_tools-0.1.11.dist-info/RECORD

@@ -1,8 +0,0 @@
-langchain_mcp_tools/__init__.py,sha256=Xtv2VphhrWB_KlxTIofHZqtCIGtNEl0MxugnrNXTERA,94
-langchain_mcp_tools/langchain_mcp_tools.py,sha256=O6TxRRuS-uTOY08-WVKK86Dxx7-dCeFZZRLpBYaPIng,13577
-langchain_mcp_tools/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-langchain_mcp_tools-0.1.11.dist-info/licenses/LICENSE,sha256=CRC91e8v116gCpnp7h49oIa6_zjhxqnHFTREeoZFJwA,1072
-langchain_mcp_tools-0.1.11.dist-info/METADATA,sha256=lW4Mm8snEac1hYSuS0szfHmJZFBs79GAEo0bwyEW_sw,5212
-langchain_mcp_tools-0.1.11.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
-langchain_mcp_tools-0.1.11.dist-info/top_level.txt,sha256=aR_9V2A1Yt-Bca60KmndmGLUWb2wiM5IOG-Gkaf1dxY,20
-langchain_mcp_tools-0.1.11.dist-info/RECORD,,