mcp-chat 0.0.1__py3-none-any.whl

mcp_chat/__init__.py

@@ -0,0 +1,3 @@
+"""MCP Client Using LangChain / Python."""
+
+__version__ = "0.2.7"

mcp_chat/cli_chat.py

@@ -0,0 +1,270 @@
+# Standard library imports
+import argparse
+import asyncio
+from enum import Enum
+import json
+import logging
+import sys
+from pathlib import Path
+from typing import (
+    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
+    from langchain_mcp_tools import (
+        convert_mcp_to_langchain_tools,
+        McpServerCleanupFn,
+    )
+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
+
+# 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]) -> str | None:
+    """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")
+
+    filtered_config = {
+        k: v for k, v in llm_config.items() if k not in ["system_prompt"]
+    }
+    llm = init_chat_model(**filtered_config)
+
+    mcp_servers = config["mcp_servers"]
+    logger.info(f"Initializing {len(mcp_servers)} MCP server(s)...\n")
+
+    tools, mcp_cleanup = await convert_mcp_to_langchain_tools(
+        mcp_servers,
+        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: McpServerCleanupFn | None = 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()

mcp_chat/config_loader.py

@@ -0,0 +1,77 @@
+import os
+import re
+from pathlib import Path
+from typing import TypedDict, Any
+import pyjson5 as json5
+
+
+class LLMConfig(TypedDict):
+    """Type definition for LLM configuration."""
+    model_provider: str
+    model: str | None
+    temperature: float | None
+    system_prompt: str | None
+
+
+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 with environment
+    variable substitution.
+    """
+    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:
+        content = f.read()
+    
+    # Replace ${VAR_NAME} with environment variable values, but skip comments
+    def replace_env_var(match):
+        var_name = match.group(1)
+        env_value = os.getenv(var_name)
+        if env_value is None:
+            raise ConfigValidationError(
+                f'Environment variable "{var_name}" not found '
+                f'in "{config_file}"'
+            )
+        return env_value
+    
+    # Process line by line to skip comments
+    lines = content.split("\n")
+    processed_lines = []
+    
+    for line in lines:
+        # Split line at first occurrence of "//"
+        if "//" in line:
+            code_part, comment_part = line.split("//", 1)
+            # Apply substitution only to the code part
+            processed_code = re.sub(r"\$\{([^}]+)\}", replace_env_var,
+                                    code_part)
+            # Reconstruct line with original comment
+            processed_line = processed_code + "//" + comment_part
+        else:
+            # No comment in line, apply substitution to entire line
+            processed_line = re.sub(r"\$\{([^}]+)\}", replace_env_var, line)
+        
+        processed_lines.append(processed_line)
+    
+    content = "\n".join(processed_lines)
+    
+    # Parse the substituted content
+    config: dict[str, Any] = json5.loads(content)
+    
+    return config

mcp_chat-0.0.1.dist-info/METADATA

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: mcp-chat
+Version: 0.0.1
+Summary: Simple CLI MCP Client to quickly test and explore MCP servers from the command line
+Project-URL: Bug Tracker, https://github.com/hideya/mcp-client-langchain-py/issues
+Project-URL: Source Code, https://github.com/hideya/mcp-client-langchain-py
+License-File: LICENSE
+Keywords: cli,client,explore,langchain,mcp,model-context-protocol,python,quick,simple,test,tools,try
+Requires-Python: >=3.11
+Requires-Dist: langchain-anthropic>=0.3.1
+Requires-Dist: langchain-google-genai>=2.1.5
+Requires-Dist: langchain-groq>=0.2.3
+Requires-Dist: langchain-mcp-tools>=0.2.7
+Requires-Dist: langchain-openai>=0.3.0
+Requires-Dist: langchain>=0.3.26
+Requires-Dist: langgraph>=0.5.0
+Requires-Dist: pyjson5>=1.6.8
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: websockets>=15.0.1
+Description-Content-Type: text/markdown
+
+# Simple CLI MCP Client Using LangChain / Python [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/hideya/langchain-mcp-tools-py/blob/main/LICENSE)
+
+This is a simple [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) client
+that is intended for trying out MCP servers via a command-line interface.
+
+When testing LLM and MCP servers, their settings can be conveniently configured via a configuration file, such as the following:
+
+```json5
+{
+    "llm": {
+        "model_provider": "openai",
+        "model": "gpt-4o-mini",
+        // "model_provider": "anthropic",
+        // "model": "claude-3-5-haiku-latest",
+        // "model_provider": "google_genai",
+        // "model": "gemini-2.0-flash",
+    },
+
+    "mcp_servers": {
+        "fetch": {
+            "command": "uvx",
+            "args": [ "mcp-server-fetch" ]
+        },
+
+        "weather": {
+            "command": "npx",
+            "args": [ "-y", "@h1deya/mcp-server-weather" ]
+        },
+
+        // Auto-detection: tries Streamable HTTP first, falls back to SSE
+        "remote-mcp-server": {
+            "url": "https://${SERVER_HOST}:${SERVER_PORT}/..."
+        },
+
+        // Example of authentication via Authorization header
+        "github": {
+            "type": "http",  // recommended to specify the protocol explicitly when authentication is used
+            "url": "https://api.githubcopilot.com/mcp/",
+            "headers": {
+                "Authorization": "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}"
+            }
+        },
+    }
+}
+```
+
+It leverages  [LangChain ReAct Agent](https://langchain-ai.github.io/langgraph/reference/agents/) and
+a utility function `convert_mcp_to_langchain_tools()` from
+[`langchain_mcp_tools`](https://pypi.org/project/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
+([list[BaseTool]](https://python.langchain.com/api_reference/core/tools/langchain_core.tools.base.BaseTool.html#langchain_core.tools.base.BaseTool)).
+
+This client supports both local (stdio) MCP servers as well as
+remote (Streamable HTTP / SSE / WebSocket) MCP servers
+which are accessible via a simple URL and optional headers for authentication and other purposes.
+
+This client only supports text results of MCP tool calls and disregards other result types.
+
+For the convenience of debugging MCP servers, this client prints local (stdio) MCP server logs to the console.
+
+LLMs from Anthropic, OpenAI and Google (GenAI) are currently supported.
+
+A TypeScript version of this MCP client is available
+[here](https://github.com/hideya/mcp-client-langchain-ts)
+
+## Prerequisites
+
+- Python 3.11+
+- [optional] [`uv` (`uvx`)](https://docs.astral.sh/uv/getting-started/installation/)
+  installed to run Python package-based MCP servers
+- [optional] [npm 7+ (`npx`)](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
+  to run Node.js package-based MCP servers
+- 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
+```
+It takes a while on the first run.
+
+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`

mcp_chat-0.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+mcp_chat/__init__.py,sha256=cxW2vB9rLAKUrNgEJ9hxa3sAK95x9-3_7RZaTxCVTTo,66
+mcp_chat/cli_chat.py,sha256=raNzfFxm6B0RfMZ2HjCYLbQnzr_SHgvoOpDeqIehly0,8080
+mcp_chat/config_loader.py,sha256=SXQYTf_i5ZG7F8_EUC_8_SC0W4R97Juqx0jCllYS0Wk,2325
+mcp_chat-0.0.1.dist-info/METADATA,sha256=PncSynhjA5xiNVVpkHHZXmNq6teReYTxVJUv4XyC_Ro,5564
+mcp_chat-0.0.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mcp_chat-0.0.1.dist-info/entry_points.txt,sha256=nVuS7z3aG9zJ6VcZ4OK9j9lKea-fnNmMluMikwG3z-o,52
+mcp_chat-0.0.1.dist-info/licenses/LICENSE,sha256=CRC91e8v116gCpnp7h49oIa6_zjhxqnHFTREeoZFJwA,1072
+mcp_chat-0.0.1.dist-info/RECORD,,

mcp_chat-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mcp_chat-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-chat = mcp_chat.cli_chat:main

mcp_chat-0.0.1.dist-info/licenses/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.