langchain-mcp-tools 0.1.10__py3-none-any.whl → 0.2.0__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, StdioServerParameters
-    from mcp.client.stdio import stdio_client
+    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,43 +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
-        )
+        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
-        stdio_transport = await exit_stack.enter_async_context(
-            stdio_client(server_params)
-        )
+        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
 
@@ -126,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
@@ -153,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
@@ -161,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(
@@ -247,7 +302,7 @@ async def get_mcp_server_tools(
     return langchain_tools
 
 
-# A very simple pre-implemented logger for fallback
+# A very simple pre-configured logger for fallback
 def init_logger() -> logging.Logger:
     logging.basicConfig(
         level=logging.INFO,  # logging.DEBUG,
@@ -261,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.
 
@@ -287,8 +342,12 @@ async def convert_mcp_to_langchain_tools(
 
     Example:
         server_configs = {
-            "server1": {"command": "npm", "args": ["start"]},
-            "server2": {"command": "./server", "args": ["-p", "8000"]}
+            'fetch': {
+                'command': 'uvx', 'args': ['mcp-server-fetch']
+            },
+            'weather': {
+                'command': 'npx', 'args': ['-y','@h1deya/mcp-server-weather']
+            }
         }
         tools, cleanup = await convert_mcp_to_langchain_tools(server_configs)
         # Use tools...
@@ -299,11 +358,11 @@ async def convert_mcp_to_langchain_tools(
         logger = logging.getLogger(__name__)
         # Check if the root logger has handlers configured
         if not logging.root.handlers and not logger.handlers:
-            # No logging configured, use our pre-implemented logger
+            # No logging configured, use a simple pre-configured logger
             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
@@ -312,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.10.dist-info → langchain_mcp_tools-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langchain-mcp-tools
-Version: 0.1.10
+Version: 0.2.0
 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
@@ -10,8 +10,9 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: jsonschema-pydantic>=0.6
 Requires-Dist: langchain>=0.3.14
-Requires-Dist: mcp>=1.2.0
+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"
@@ -35,21 +36,20 @@ dramatically expands LLM’s scope
 by enabling external tool and resource integration, including
 Google Drive, Slack, Notion, Spotify, Docker, PostgreSQL, and more…
 
-Over 1500 functional components available as MCP servers:
+Over 2000 functional components available as MCP servers:
 
+- [MCP Server Listing on the Official Site](https://github.com/modelcontextprotocol/servers?tab=readme-ov-file#model-context-protocol-servers)
 - [MCP.so - Find Awesome MCP Servers and Clients](https://mcp.so/)
 - [Smithery: MCP Server Registry](https://smithery.ai/)
-- [pulse - Browse and discover MCP use cases, servers, clients, and news](https://www.pulsemcp.com/)
-- [MCP Get Started/Example Servers](https://modelcontextprotocol.io/examples)
 
-The goal of this utility is to make these 1500+ MCP servers readily accessible from LangChain.
+The goal of this utility is to make these 2000+ MCP servers readily accessible from LangChain.
 
 It contains a utility function `convert_mcp_to_langchain_tools()`.  
 This async function handles parallel initialization of specified multiple MCP servers
 and converts their available tools into a list of LangChain-compatible tools.
 
 For detailed information on how to use this library, please refer to the following document:
-- ["Supercharging LangChain: Integrating 1500+ MCP with ReAct"](https://medium.com/@h1deya/supercharging-langchain-integrating-1500-mcp-with-react-d4e467cbf41a)
+- ["Supercharging LangChain: Integrating 2000+ MCP with ReAct"](https://medium.com/@h1deya/supercharging-langchain-integrating-450-mcp-with-react-d4e467cbf41a)
 
 A typescript equivalent of this utility is available
 [here](https://www.npmjs.com/package/@h1deya/langchain-mcp-tools)
@@ -73,25 +73,25 @@ but only the contents of the `mcpServers` property,
 and is expressed as a `dict`, e.g.:
 
 ```python
-mcp_configs = {
-    'filesystem': {
-        'command': 'npx',
-        'args': ['-y', '@modelcontextprotocol/server-filesystem', '.']
+mcp_servers = {
+    "filesystem": {
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
     },
-    'fetch': {
-        'command': 'uvx',
-        'args': ['mcp-server-fetch']
+    "fetch": {
+        "command": "uvx",
+        "args": ["mcp-server-fetch"]
     }
 }
 
 tools, cleanup = await convert_mcp_to_langchain_tools(
-    mcp_configs
+    mcp_servers
 )
 ```
 
 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`)
@@ -120,11 +120,64 @@ 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 1500+ MCP with ReAct"](https://medium.com/@h1deya/supercharging-langchain-integrating-1500-mcp-with-react-d4e467cbf41a)
+["Supercharging LangChain: Integrating 2000+ MCP with ReAct"](https://medium.com/@h1deya/supercharging-langchain-integrating-450-mcp-with-react-d4e467cbf41a)
+
+## 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 name `"url"` may be changed in the future to match
+the MCP server configurations used by Claude for Desktop once
+it introduces remote server support.
+
+### Working Directory Configuration for Local MCP Servers
+
+The working directory that is used when spawning a local MCP server
+can be specified with the `cwd` key as follows:
+
+```python
+    "local-server-name": {
+        "command": "...",
+        "args": [...],
+        "cwd": "/working/directory"  # the working dir to be use by the server
+    },
+```
+
+### Configuration for MCP Server stderr Redirection
+
+A new key `errlog` has been introduced in to specify a file-like object
+to which 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
+```
+
+**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.
 
 ## Limitations
 
-Currently, only text results of tool calls are supported.
+- Currently, only text results of tool calls are supported.
+- Fatures other than [Tools](https://modelcontextprotocol.io/docs/concepts/tools) are not supported.
 
 ## Change Log
 

langchain_mcp_tools-0.2.0.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.0.dist-info/licenses/LICENSE,sha256=CRC91e8v116gCpnp7h49oIa6_zjhxqnHFTREeoZFJwA,1072
+langchain_mcp_tools-0.2.0.dist-info/METADATA,sha256=oCzGJZvkhbhF_OA8Pm-Iy2JSjbeIJEEK1cr8pPxxh1g,6808
+langchain_mcp_tools-0.2.0.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+langchain_mcp_tools-0.2.0.dist-info/top_level.txt,sha256=aR_9V2A1Yt-Bca60KmndmGLUWb2wiM5IOG-Gkaf1dxY,20
+langchain_mcp_tools-0.2.0.dist-info/RECORD,,

{langchain_mcp_tools-0.1.10.dist-info → langchain_mcp_tools-0.2.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (78.0.2)
+Generator: setuptools (78.1.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

langchain_mcp_tools-0.1.10.dist-info/RECORD

@@ -1,8 +0,0 @@
-langchain_mcp_tools/__init__.py,sha256=Xtv2VphhrWB_KlxTIofHZqtCIGtNEl0MxugnrNXTERA,94
-langchain_mcp_tools/langchain_mcp_tools.py,sha256=vIiOB8u62Q-7Mi8U6XI247g-xfxpE2QvoBeo0pbtFX4,12838
-langchain_mcp_tools/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-langchain_mcp_tools-0.1.10.dist-info/licenses/LICENSE,sha256=CRC91e8v116gCpnp7h49oIa6_zjhxqnHFTREeoZFJwA,1072
-langchain_mcp_tools-0.1.10.dist-info/METADATA,sha256=kAMCbY0YTAA5aj-SaiGqtAanX30ggpEeZO39zChua0Y,5135
-langchain_mcp_tools-0.1.10.dist-info/WHEEL,sha256=DK49LOLCYiurdXXOXwGJm6U4DkHkg4lcxjhqwRa0CP4,91
-langchain_mcp_tools-0.1.10.dist-info/top_level.txt,sha256=aR_9V2A1Yt-Bca60KmndmGLUWb2wiM5IOG-Gkaf1dxY,20
-langchain_mcp_tools-0.1.10.dist-info/RECORD,,