langchain-mcp-tools 0.0.1__py3-none-any.whl

cli_chat.py

@@ -0,0 +1,274 @@
+# Standard library imports
+import argparse
+import asyncio
+from enum import Enum
+import json
+import logging
+import sys
+from pathlib import Path
+from typing import (
+    List,
+    Optional,
+    Dict,
+    Any,
+    cast,
+)
+
+# Third-party imports
+try:
+    from dotenv import load_dotenv
+    from langchain.chat_models import init_chat_model
+    from langchain.schema import (
+        AIMessage,
+        BaseMessage,
+        HumanMessage,
+        SystemMessage,
+    )
+    from langchain_core.runnables.base import Runnable
+    from langchain_core.messages.tool import ToolMessage
+    from langgraph.prebuilt import create_react_agent
+except ImportError as e:
+    print(f'\nError: Required package not found: {e}')
+    print('Please ensure all required packages are installed\n')
+    sys.exit(1)
+
+# Local application imports
+from config_loader import load_config
+from langchain_mcp_tools import (
+    convert_mcp_to_langchain_tools,
+    McpServerCleanupFn,
+)
+
+# Type definitions
+ConfigType = Dict[str, Any]
+
+
+# ANSI color escape codes
+class Colors(str, Enum):
+    YELLOW = '\033[33m'  # color to yellow
+    CYAN = '\033[36m'    # color to cyan
+    RESET = '\033[0m'    # reset color
+
+    def __str__(self):
+        return self.value
+
+
+def parse_arguments() -> argparse.Namespace:
+    """Parse and return command line args for config path and verbosity."""
+    parser = argparse.ArgumentParser(
+        description='CLI Chat Application',
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter
+    )
+    parser.add_argument(
+        '-c', '--config',
+        default='llm_mcp_config.json5',
+        help='path to config file',
+        type=Path,
+        metavar='PATH'
+    )
+    parser.add_argument(
+        '-v', '--verbose',
+        action='store_true',
+        help='run with verbose logging'
+    )
+    return parser.parse_args()
+
+
+def init_logger(verbose: bool) -> logging.Logger:
+    """Initialize and return a logger with appropriate verbosity level."""
+    logging.basicConfig(
+        level=logging.DEBUG if verbose else logging.INFO,
+        format='\x1b[90m[%(levelname)s]\x1b[0m %(message)s'
+    )
+    return logging.getLogger()
+
+
+def print_colored(text: str, color: Colors, end: str = "\n") -> None:
+    """Print text in specified color and reset afterwards."""
+    print(f"{color}{text}{Colors.RESET}", end=end)
+
+
+def set_color(color: Colors) -> None:
+    """Set terminal color."""
+    print(color, end='')
+
+
+def clear_line() -> None:
+    """Move up one line and clear it."""
+    print('\x1b[1A\x1b[2K', end='')
+
+
+async def get_user_query(remaining_queries: List[str]) -> Optional[str]:
+    """Get user input or next example query, handling empty inputs
+    and quit commands."""
+    set_color(Colors.YELLOW)
+    query = input('Query: ').strip()
+
+    if len(query) == 0:
+        if len(remaining_queries) > 0:
+            query = remaining_queries.pop(0)
+            clear_line()
+            print_colored(f'Example Query: {query}', Colors.YELLOW)
+        else:
+            set_color(Colors.RESET)
+            print('\nPlease type a query, or "quit" or "q" to exit\n')
+            return await get_user_query(remaining_queries)
+
+    print(Colors.RESET)  # Reset after input
+
+    if query.lower() in ['quit', 'q']:
+        print_colored('Goodbye!\n', Colors.CYAN)
+        return None
+
+    return query
+
+
+async def handle_conversation(
+    agent: Runnable,
+    messages: List[BaseMessage],
+    example_queries: List[str],
+    verbose: bool
+) -> None:
+    """Manage an interactive conversation loop between the user and AI agent.
+
+    Args:
+        agent (Runnable): The initialized ReAct agent that processes queries
+        messages (List[BaseMessage]): List to maintain conversation history
+        example_queries (List[str]): list of example queries that can be used
+            when user presses Enter
+        verbose (bool): Flag to control detailed output of tool responses
+
+    Exception handling:
+    - TypeError: Ensures response is in correct string format
+    - General exceptions: Allows conversation to continue after errors
+
+    The conversation continues until user types 'quit' or 'q'.
+    """
+    print('\nConversation started. '
+          'Type "quit" or "q" to end the conversation.\n')
+    if len(example_queries) > 0:
+        print('Example Queries (just type Enter to supply them one by one):')
+        for ex_q in example_queries:
+            print(f"- {ex_q}")
+        print()
+
+    while True:
+        try:
+            query = await get_user_query(example_queries)
+            if not query:
+                break
+
+            messages.append(HumanMessage(content=query))
+
+            result = await agent.ainvoke({
+                'messages': messages
+            })
+
+            result_messages = cast(List[BaseMessage], result['messages'])
+            # the last message should be an AIMessage
+            response = result_messages[-1].content
+            if not isinstance(response, str):
+                raise TypeError(
+                    f"Expected string response, got {type(response)}"
+                )
+
+            # check if msg one before is a ToolMessage
+            message_one_before = result_messages[-2]
+            if isinstance(message_one_before, ToolMessage):
+                if verbose:
+                    # show tools call response
+                    print(message_one_before.content)
+                # new line after tool call output
+                print()
+            print_colored(f"{response}\n", Colors.CYAN)
+            messages.append(AIMessage(content=response))
+
+        except Exception as e:
+            print(f'Error getting response: {str(e)}')
+            print('You can continue chatting or type "quit" to exit.')
+
+
+async def init_react_agent(
+    config: ConfigType,
+    logger: logging.Logger
+) -> tuple[Runnable, List[BaseMessage], McpServerCleanupFn]:
+    """Initialize and configure a ReAct agent for conversation handling.
+
+    Args:
+        config (ConfigType): Configuration dictionary containing LLM and
+            MCP server settings
+        logger (logging.Logger): Logger instance for initialization
+            status updates
+
+    Returns:
+        tuple[Runnable, List[BaseMessage], McpServerCleanupFn]:
+            Returns a tuple containing:
+            - Configured ReAct agent ready for conversation
+            - Initial message list (empty or with system prompt)
+            - Cleanup function for MCP server connections
+    """
+    llm_config = config['llm']
+    logger.info(f'Initializing model... {json.dumps(llm_config, indent=2)}\n')
+
+    llm = init_chat_model(
+        model=llm_config['model'],
+        model_provider=llm_config['model_provider'],
+        temperature=llm_config['temperature'],
+        max_tokens=llm_config['max_tokens'],
+    )
+
+    mcp_configs = config['mcp_servers']
+    logger.info(f'Initializing {len(mcp_configs)} MCP server(s)...\n')
+    tools, mcp_cleanup = await convert_mcp_to_langchain_tools(
+        mcp_configs,
+        logger
+    )
+
+    agent = create_react_agent(
+        llm,
+        tools
+    )
+
+    messages: List[BaseMessage] = []
+    system_prompt = llm_config.get('system_prompt')
+    if system_prompt and isinstance(system_prompt, str):
+        messages.append(SystemMessage(content=system_prompt))
+
+    return agent, messages, mcp_cleanup
+
+
+async def run() -> None:
+    """Main async function to set up and run the simple chat app."""
+    mcp_cleanup: Optional[McpServerCleanupFn] = None
+    try:
+        load_dotenv()
+        args = parse_arguments()
+        logger = init_logger(args.verbose)
+        config = load_config(args.config)
+        example_queries = (
+            config.get('example_queries')[:]
+            if config.get('example_queries') is not None
+            else []
+        )
+
+        agent, messages, mcp_cleanup = await init_react_agent(config, logger)
+
+        await handle_conversation(
+            agent,
+            messages,
+            example_queries,
+            args.verbose
+        )
+
+    finally:
+        if mcp_cleanup is not None:
+            await mcp_cleanup()
+
+
+def main() -> None:
+    """Entry point of the script."""
+    asyncio.run(run())
+
+
+if __name__ == '__main__':
+    main()

config_loader.py

@@ -0,0 +1,39 @@
+import pyjson5 as json5
+from pathlib import Path
+from typing import TypedDict, Optional, Any
+
+
+class LLMConfig(TypedDict):
+    """Type definition for LLM configuration."""
+    model_provider: str
+    model: Optional[str]
+    temperature: Optional[float]
+    system_prompt: Optional[str]
+
+
+class ConfigError(Exception):
+    """Base exception for configuration related errors."""
+    pass
+
+
+class ConfigFileNotFoundError(ConfigError):
+    """Raised when the configuration file cannot be found."""
+    pass
+
+
+class ConfigValidationError(ConfigError):
+    """Raised when the configuration fails validation."""
+    pass
+
+
+def load_config(config_path: str):
+    """Load and validate configuration from JSON5 file.
+    """
+    config_file = Path(config_path)
+    if not config_file.exists():
+        raise ConfigFileNotFoundError(f"Config file {config_path} not found")
+
+    with open(config_file, 'r', encoding='utf-8') as f:
+        config: dict[str, Any] = json5.load(f)
+
+    return config

langchain_mcp_tools-0.0.1.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 hideya kawahara
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

langchain_mcp_tools-0.0.1.dist-info/METADATA

@@ -0,0 +1,93 @@
+Metadata-Version: 2.2
+Name: langchain-mcp-tools
+Version: 0.0.1
+Summary: MCP Client Using LangChain / Python
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jsonschema-pydantic>=0.6
+Requires-Dist: langchain>=0.3.14
+Requires-Dist: langchain-anthropic>=0.3.1
+Requires-Dist: langchain-groq>=0.2.3
+Requires-Dist: langchain-openai>=0.3.0
+Requires-Dist: langgraph>=0.2.62
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: pyjson5>=1.6.8
+Requires-Dist: pympler>=1.1
+Requires-Dist: python-dotenv>=1.0.1
+
+# MCP Client Using LangChain / Python [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/hideya/mcp-langchain-client-ts/blob/main/LICENSE)
+
+This simple [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
+client demonstrates MCP server invocations by LangChain ReAct Agent.
+
+It leverages a utility function `convert_mcp_to_langchain_tools()` from
+`langchain_mcp_tools`.  
+This function handles parallel initialization of specified multiple MCP servers
+and converts their available tools into a list of
+[LangChain-compatible tools](https://js.langchain.com/docs/how_to/tool_calling/).
+
+LLMs from Anthropic, OpenAI and Groq are currently supported.
+
+A typescript version of this MCP client is available
+[here](https://github.com/hideya/mcp-client-langchain-ts)
+
+## Requirements
+
+- Python 3.11+
+- [`uv`](https://docs.astral.sh/uv/) installation
+- API keys from [Anthropic](https://console.anthropic.com/settings/keys),
+  [OpenAI](https://platform.openai.com/api-keys), and/or
+  [Groq](https://console.groq.com/keys)
+  as needed
+
+## Setup
+1. Install dependencies:
+    ```bash
+    make install
+    ```
+
+2. Setup API keys:
+    ```bash
+    cp .env.template .env
+    ```
+    - Update `.env` as needed.
+    - `.gitignore` is configured to ignore `.env`
+      to prevent accidental commits of the credentials.
+
+3. Configure LLM and MCP Servers settings `llm_mcp_config.json5` as needed.
+
+    - [The configuration file format](https://github.com/hideya/mcp-client-langchain-ts/blob/main/llm_mcp_config.json5)
+      for MCP servers follows the same structure as
+      [Claude for Desktop](https://modelcontextprotocol.io/quickstart/user),
+      with one difference: the key name `mcpServers` has been changed
+      to `mcp_servers` to follow the snake_case convention
+      commonly used in JSON configuration files.
+    - The file format is [JSON5](https://json5.org/),
+      where comments and trailing commas are allowed.
+    - The format is further extended to replace `${...}` notations
+      with the values of corresponding environment variables.
+    - Keep all the credentials and private info in the `.env` file
+      and refer to them with `${...}` notation as needed.
+
+
+## Usage
+
+Run the app:
+```bash
+make start
+```
+
+Run in verbose mode:
+```bash
+make start-v
+```
+
+See commandline options:
+```bash
+make start-h
+```
+
+At the prompt, you can simply press Enter to use example queries that perform MCP server tool invocations.
+
+Example queries can be configured in  `llm_mcp_config.json5`

langchain_mcp_tools-0.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+cli_chat.py,sha256=HMsG9ltHqlPCTCBc_364tKzo88M7M-AU4YlXP92-PKY,8167
+config_loader.py,sha256=QA3qjCUWyIMt6X86fdqAv5xuD6YY40Vy3QMXnwBwLhA,986
+langchain_mcp_tools.py,sha256=P6jxJfITBwlZs2CvLQSvvRs3fWghUDrD8Yq4B7Q6-1Y,9975
+langchain_mcp_tools-0.0.1.dist-info/LICENSE,sha256=CRC91e8v116gCpnp7h49oIa6_zjhxqnHFTREeoZFJwA,1072
+langchain_mcp_tools-0.0.1.dist-info/METADATA,sha256=9HtbRjXrbay2Wdm40fiA3WpBO2s7UBGErF30AXj2Qic,3071
+langchain_mcp_tools-0.0.1.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+langchain_mcp_tools-0.0.1.dist-info/top_level.txt,sha256=CIi8dh_4Ci8PLdeCnzBaZ9A2SfhB8XN5tkE16WChlgk,43
+langchain_mcp_tools-0.0.1.dist-info/RECORD,,

langchain_mcp_tools-0.0.1.dist-info/WHEEL

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

langchain_mcp_tools-0.0.1.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+cli_chat
+config_loader
+langchain_mcp_tools

langchain_mcp_tools.py

@@ -0,0 +1,278 @@
+# Standard library imports
+import asyncio
+import logging
+import os
+import sys
+from contextlib import AsyncExitStack, asynccontextmanager
+from typing import (
+    Any,
+    Awaitable,
+    Callable,
+    Dict,
+    List,
+    NoReturn,
+    Tuple,
+    Type,
+)
+
+# Third-party imports
+try:
+    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 pydantic import BaseModel
+    from pympler import asizeof
+except ImportError as e:
+    print(f'\nError: Required package not found: {e}')
+    print('Please ensure all required packages are installed\n')
+    sys.exit(1)
+
+
+"""
+Resource Management Pattern for Parallel Server Initialization
+--------------------------------------------------------------
+This code implements a specific pattern for managing async resources that
+require context managers while enabling parallel initialization.
+The key aspects are:
+
+1. Core Challenge:
+   - Managing async resources (stdio_client and ClientSession) that seems to
+     rely exclusively on asynccontextmanager for cleanup with no manual cleanup
+     options (based on the mcp python-sdk impl as of Jan 14, 2025 #62a0af6)
+   - Initializing multiple servers in parallel
+   - Keeping sessions alive for later use
+   - Ensuring proper cleanup in the same task that created them
+
+2. Solution Strategy:
+   A key requirement for parallel initialization is that each server must be
+   initialized in its own dedicated task - there's no way around this if we
+   want true parallel initialization. However, this creates a challenge since
+   we also need to maintain long-lived sessions and handle cleanup properly.
+
+   The key insight is to keep the initialization tasks alive throughout the
+   session lifetime, rather than letting them complete after initialization.
+   By using events for coordination, we can:
+   - Allow parallel initialization while maintaining proper context management
+   - Keep each initialization task running until explicit cleanup is requested
+   - Ensure cleanup occurs in the same task that created the resources
+   - Provide a clean interface for the caller to manage the lifecycle
+
+   Alternative Considered:
+   A generator/coroutine approach using 'finally' block for cleanup was
+   considered but rejected because:
+   - The 'finally' block in a generator/coroutine can be executed by a
+     different task than the one that ran the main body of the code
+   - This breaks the requirement that AsyncExitStack.aclose() must be
+     called from the same task that created the context
+
+3. Task Lifecycle:
+   To allow the initialization task to stay alive waiting for cleanup:
+   [Task starts]
+     ↓
+   Initialize server & convert tools
+     ↓
+   Set ready_event (signals tools are ready)
+     ↓
+   await cleanup_event.wait() (keeps task alive)
+     ↓
+   When cleanup_event is set:
+   exit_stack.aclose() (cleanup in original task)
+
+This pattern enables parallel initialization while maintaining proper async
+resource lifecycle management through context managers.
+"""
+
+
+async def spawn_mcp_server_tools_task(
+    server_name: str,
+    server_config: Dict[str, Any],
+    langchain_tools: List[BaseTool],
+    ready_event: asyncio.Event,
+    cleanup_event: asyncio.Event,
+    logger: logging.Logger = logging.getLogger(__name__)
+) -> None:
+    """Convert MCP server tools to LangChain compatible tools
+    and manage lifecycle.
+
+    This task initializes an MCP server connection, converts its tools
+    to LangChain format, and manages the connection lifecycle.
+    It adds the tools to the provided langchain_tools list and uses events
+    for synchronization.
+
+    Args:
+        server_name: Name of the MCP server
+        server_config: Server configuration dictionary containing command,
+            args, and env
+        langchain_tools: List to which the converted LangChain tools will
+            be appended
+        ready_event: Event to signal when tools are ready for use
+        cleanup_event: Event to trigger cleanup and connection closure
+        logger: Logger instance to use for logging events and errors.
+               Defaults to module logger.
+
+    Returns:
+        None
+
+    Raises:
+        Exception: If there's an error in server connection or tool conversion
+    """
+    try:
+        logger.info(f'MCP server "{server_name}": 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', '')
+
+        server_params = StdioServerParameters(
+            command=server_config['command'],
+            args=server_config.get('args', []),
+            env=env
+        )
+
+        @asynccontextmanager
+        async def log_before_aexit(context_manager, message):
+            yield await context_manager.__aenter__()
+            logger.info(message)
+            await context_manager.__aexit__(None, None, None)
+
+        exit_stack = AsyncExitStack()
+
+        stdio_transport = await exit_stack.enter_async_context(
+            stdio_client(server_params)
+        )
+        read, write = stdio_transport
+
+        session = await exit_stack.enter_async_context(
+            log_before_aexit(
+                ClientSession(read, write),
+                f'MCP server "{server_name}": session closed'
+            )
+        )
+
+        await session.initialize()
+        logger.info(f'MCP server "{server_name}": connected')
+
+        tools_response = await session.list_tools()
+
+        for tool in tools_response.tools:
+            class McpToLangChainAdapter(BaseTool):
+                name: str = tool.name or 'NO NAME'
+                description: str = tool.description or ''
+                args_schema: Type[BaseModel] = jsonschema_to_pydantic(
+                    tool.inputSchema
+                )
+
+                def _run(self, **kwargs: Any) -> NoReturn:
+                    raise NotImplementedError(
+                        'Only async operation is supported'
+                    )
+
+                async def _arun(self, **kwargs: Any) -> Any:
+                    logger.info(f'MCP tool "{server_name}"/"{tool.name}"'
+                                f' received input:', kwargs)
+                    result = await session.call_tool(self.name, kwargs)
+                    if result.isError:
+                        raise ToolException(result.content)
+
+                    size = asizeof.asizeof(result.content)
+                    logger.info(f'MCP tool "{server_name}"/"{tool.name}" '
+                                f'received result (size: {size})')
+                    return result.content
+
+            langchain_tools.append(McpToLangChainAdapter())
+
+        logger.info(f'MCP server "{server_name}": {len(langchain_tools)} '
+                    f'tool(s) available:')
+        for tool in langchain_tools:
+            logger.info(f'- {tool.name}')
+    except Exception as e:
+        logger.error(f'Error getting response: {str(e)}')
+        raise
+
+    ready_event.set()
+
+    await cleanup_event.wait()
+
+    await exit_stack.aclose()
+
+
+McpServerCleanupFn = Callable[[], Awaitable[None]]
+
+
+async def convert_mcp_to_langchain_tools(
+    server_configs: Dict[str, Dict[str, Any]],
+    logger: logging.Logger = logging.getLogger(__name__)
+) -> Tuple[List[BaseTool], McpServerCleanupFn]:
+    """Initialize multiple MCP servers and convert their tools to
+    LangChain format.
+
+    This async function manages parallel initialization of multiple MCP
+    servers, converts their tools to LangChain format, and provides a cleanup
+    mechanism. It orchestrates the full lifecycle of multiple servers.
+
+    Args:
+        server_configs: Dictionary mapping server names to their
+            configurations, where each configuration contains command, args,
+            and env settings
+        logger: Logger instance to use for logging events and errors.
+               Defaults to module logger.
+
+    Returns:
+        A tuple containing:
+            - List of converted LangChain tools from all servers
+            - Async cleanup function to properly shutdown all server
+                connections
+
+    Example:
+        server_configs = {
+            "server1": {"command": "npm", "args": ["start"]},
+            "server2": {"command": "./server", "args": ["-p", "8000"]}
+        }
+        tools, cleanup = await convert_mcp_to_langchain_tools(server_configs)
+        # Use tools...
+        await cleanup()
+    """
+    per_server_tools = []
+    ready_event_list = []
+    cleanup_event_list = []
+
+    tasks = []
+    for server_name, server_config in server_configs.items():
+        server_tools_accumulator: List[BaseTool] = []
+        per_server_tools.append(server_tools_accumulator)
+        ready_event = asyncio.Event()
+        ready_event_list.append(ready_event)
+        cleanup_event = asyncio.Event()
+        cleanup_event_list.append(cleanup_event)
+        task = asyncio.create_task(spawn_mcp_server_tools_task(
+            server_name,
+            server_config,
+            server_tools_accumulator,
+            ready_event,
+            cleanup_event,
+            logger
+        ))
+        tasks.append(task)
+
+    for ready_event in ready_event_list:
+        await ready_event.wait()
+
+    langchain_tools = [
+        item for sublist in per_server_tools for item in sublist
+    ]
+
+    async def mcp_cleanup() -> None:
+        for cleanup_event in cleanup_event_list:
+            cleanup_event.set()
+
+    logger.info(f'MCP servers initialized: {len(langchain_tools)} tool(s) '
+                f'available in total')
+    for tool in langchain_tools:
+        logger.debug(f'- {tool.name}')
+
+    return langchain_tools, mcp_cleanup