ultimate_mcp_client
Async Python client for the Model Context Protocol with interactive CLI and reactive Web UI, connecting AI models to MCP servers via stdio and SSE
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/dicklesworthstone--ultimate-mcp-client)HTML
<a href="/listings/dicklesworthstone--ultimate-mcp-client"><img src="/api/listings/dicklesworthstone--ultimate-mcp-client/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
Install Dependencies
> **Requires Python 3.13+**
First, install [uv](https://github.com/astral-sh/uv) (the recommended fast Python package installer):
# macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Then clone the repository, set up a virtual environment using Python 3.13+, and install packages:
git clone https://github.com/Dicklesworthstone/ultimate_mcp_client cd ultimate_mcp_client # Create venv using uv (recommended) uv venv --python 3.13 # Or using standard venv # python3.13 -m venv .venv # Activate environment source .venv/bin/activate # Linux/macOS # .venv\Scripts\activate # Windows Powershell # .\venv\Scripts\activate.bat # Windows CMD # Install dependencies using uv (fastest) uv sync --all-extras # Or using pip (slower) # pip install -e . # Installs only core dependencies
Configure API Key
Set your Anthropic API key as an environment variable:
export ANTHROPIC_API_KEY="sk-ant-..." # Or add ANTHROPIC_API_KEY="sk-ant-..." to a .env file in the project root
Alternatively, set it later using the `/config api-key ...` command in the interactive CLI or via the Web UI settings panel.
Launch the Web UI (Recommended)
mcpclient run --webui
Then open your browser to `http://127.0.0.1:8017` (or the configured host/port).
You can customize the host and port:
mcpclient run --webui --host 0.0.0.0 --port 8080
Run Interactive CLI Mode
mcpclient run --interactive
Run a One-Off Query
mcpclient run --query "What's the weather in New York?"
Show the CLI Dashboard
mcpclient run --dashboard
Configure Port Scanning
# Enable port scanning (if disabled) mcpclient config port-scan enable true # Set the range (example) mcpclient config port-scan range 8000 8999
Import and Export Conversations
# Export current conversation branch to a default filename mcpclient export # Export current branch to a specific file mcpclient export --output my_conversation.json # Export specific conversation branch by ID (first 8 chars often suffice) mcpclient export --id 12345678 --output specific_branch.json # Import a conversation file (creates a new branch under the current node) mcpclient import-conv my_conversation.json
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 468 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 🧠 Ultimate MCP Client
- <div align="center">
- [](https://www.python.org/downloads/release/python-3130/)
- [](./LICENSE)
- [](https://github.com/mpctechdebt/mcp)
- [](https://github.com/astral-sh/ruff)
- A comprehensive, asynchronous client for the **Model Context Protocol (MCP)**. It bridges the gap between powerful AI models like Anthropic's Claude and a universe of external tools, local/remote servers, and contextual data sources, enabling complex, stateful interactions.
- 
- </div>
- > Built by Jeffrey Emanuel
- ---
- ## 🎯 Purpose & Motivation
- The Model Context Protocol (MCP) standardizes how AI models interact with external capabilities (tools, resources, prompts). This client aims to be the **ultimate interface** for leveraging MCP, providing:
- 1. **Robust Connectivity:** Reliably connect to diverse MCP servers (`stdio`, `sse`) with built-in resilience, advanced error handling, and intelligent discovery.
- 2. **Rich User Experience:** Offer both a powerful interactive CLI and a modern, reactive Web UI, ensuring usability for diverse workflows.
- 3. **Advanced State Management:** Go beyond simple chat history with forkable conversation graphs, persistent state across sessions, and smart context optimization techniques.
- 4. **Developer Introspection:** Provide deep observability via OpenTelemetry metrics and traces, alongside live dashboards for monitoring client and server health and performance.
- 5. **Seamless Integration:** Easily discover and integrate local filesystem scripts, local network (mDNS) servers, local port scan results, remote registry entries, and even configurations from existing tools like the Claude Desktop app.
- **This project tackles significant engineering challenges**, especially around reliable `stdio` communication, asynchronous state management, and providing a consistent experience across both CLI and Web interfaces, to deliver a truly comprehensive MCP client solution.
- ---
- ## 🔌 Key Features
- - **Dual Interfaces: Web UI & CLI**
- - **Web UI:** Beautiful, reactive interface built with **Alpine.js**, **DaisyUI**, and **Tailwind CSS**. Features real-time chat streaming via WebSockets, server/tool management modals, **visual conversation branching view**, settings configuration, **multiple theme switching** (respecting light/dark modes for code highlighting), and direct tool execution capabilities.
- - **CLI:** Feature-rich interactive shell (`/commands`, autocompletion, **Rich** Markdown rendering) and batch-mode operation via **Typer**. Includes a live **Textual User Interface (TUI) dashboard** for monitoring.
- - **Robust Server Connectivity & Management**
- - Supports `stdio`, `sse` (HTTP Server-Sent Events), and `streaming-http` MCP servers.
- - **Advanced STDIO Handling (Key Engineering Effort):** Features a custom `RobustStdioSession` designed to gracefully handle potentially noisy or non-compliant `stdio` servers. It includes:
- - *Noise Filtering:* Ignores non-JSON-RPC output that could corrupt the protocol.
- - *Direct Future Resolution:* Avoids complex queueing for faster response handling.
- - *Process Lifecycle Management:* Reliably starts, monitors, terminates, and kills `stdio` server processes.
- - **Critical STDIO Safety:** A multi-layered system (`StdioProtectionWrapper`, `safe_stdout` context manager, `get_safe_console()` function) prevents accidental writes to `sys.stdout` from corrupting the `stdio` channel, ensuring safe coexistence of multiple `stdio` servers and user output (redirected to `stderr` when necessary). This was crucial for stability.
- - **Resilience:** Automatic connection retries with exponential backoff and circuit breakers for failing servers (`@retry_with_circuit_breaker`). Background health monitoring (`ServerMonitor`) checks server responsiveness.
- - **Modern Transport Support**
- - **Streaming-HTTP:** Native support for the modern `streaming-http` transport protocol via the FastMCP library. This transport provides efficient bidirectional communication over HTTP with built-in streaming capabilities, making it ideal for modern MCP server deployments.
- - **Intelligent Transport Detection:** Automatically detects and suggests the appropriate transport type based on server URLs and discovery information:
- - Local file paths → `stdio`
- - URLs with `/sse` or `/events` paths → `sse`
- - General HTTP/HTTPS URLs → `streaming-http` (default for modern servers)
- - **Intelligent Server Discovery**
- - Auto-discovers local `stdio` servers (Python/JS scripts) in configured filesystem paths.
- - **mDNS Discovery (Zeroconf):** Real-time discovery and notification of MCP servers (`_mcp._tcp.local.`) on the local network. Interactive commands (`/discover list`, `/discover connect`, etc.) for managing LAN servers.
- - **Local Port Scanning:** Actively scans a configurable range of local ports (e.g., 8000-9000) for MCP servers by attempting an `initialize` handshake. Supports detection of all transport types (`stdio`, `sse`, `streaming-http`). Configurable via `/config port-scan ...` commands.
- - **Registry Integration:** Connects to remote MCP registries (specified in config) to find and add shared servers.
- - **Claude Desktop Import:** Automatically detects `claude_desktop_config.json` in the project root. **Intelligently adapts configurations:**
- - Remaps `wsl.exe ... bash -c "cmd"` calls to direct Linux shell execution (`/bin/bash -c "cmd"`).
- - Converts Windows-style paths (`C:\...`) in arguments to their Linux/WSL equivalents (`/mnt/c/...`) using `adapt_path_for_platform` for seamless integration.
- - **Powerful AI Integration & Streaming**
- - Deep integration with Claude models via the official `anthropic` SDK, supporting multi-turn tool use scenarios.
- - **Real-time Streaming:** Streams AI responses and tool status updates via WebSockets (Web UI) and live `Rich` rendering (CLI). Handles complex streaming events, including **partial JSON input accumulation (`input_json_delta`)** for tools requiring structured input.
- - **Intelligent Tool Routing:** Directs tool calls to the correct originating server based on loaded capabilities, using sanitized names for API compatibility while tracking original names internally.
- - **Direct Tool Execution:** Run specific tools with custom JSON parameters via the `/tool` command (CLI) or a dedicated modal (Web UI).
- - **Advanced Conversation Management**
- - **Branching:** Forkable conversation graphs (`ConversationGraph`) allow exploring different interaction paths without losing history. Visually represented and navigable in the Web UI.
- - **Persistence:** Conversation graphs (including all branches and messages) are automatically saved to JSON files in the config directory, preserving state across sessions.
- - **Context Optimization:** Automatic or manual summarization (`/optimize`) of long conversation histories using a specified AI model (configurable) to stay within context limits.
- - **Dynamic Prompts:** Inject pre-defined prompt templates obtained from servers into the current conversation context using the `/prompt` command.
- - **Import/Export:** Easily save (`/export`) and load (`/import`) entire conversation branches in a portable JSON format for sharing or backup.
- - **Observability & Monitoring**
- - **OpenTelemetry:** Integrated metrics (counters, histograms using `opentelemetry-sdk`) and tracing (spans) for monitoring client operations, server requests, and tool execution performance. Console exporters can be enabled for debugging.
- - **Live Dashboards:**
- - **CLI:** Real-time TUI dashboard (`/dashboard`) built with `Rich`, showing server health, tool usage stats, and client info.
- - **Web UI:** Dynamically updates server status, health indicators, and capability counts.
- - **Smart Caching**
- - Optional disk (`diskcache`) and in-memory caching for tool results to improve speed and reduce costs.
- - Configurable Time-To-Live (TTL) per tool category (e.g., `weather`, `filesystem`).
- - **Dependency Tracking:** Define relationships between tools. Invalidating one tool's cache (e.g., `stock:lookup`) can automatically invalidate dependent caches (e.g., `stock:analyze`). View the graph via `/cache dependencies`.
- ---
- ## 📸 Screenshots
- A glimpse into the Ultimate MCP Client's interfaces:
- <br/>
- <table>
- <tbody>
- <tr>
- <td align="center" valign="top" width="50%">
- <img src="https://github.com/Dicklesworthstone/ultimate_mcp_client/blob/main/screenshots/terminal_example_01.webp?raw=true" alt="CLI Interactive Mode showing tool execution and streaming" width="95%">
- <br/>
- <p align="center"><small><em>Interactive CLI: Streaming response with tool call/result.</em></small></p>
- </td>
- <td align="center" valign="top" width="50%">
- <img src="https://github.com/Dicklesworthstone/ultimate_mcp_client/blob/main/screenshots/terminal_example_02.webp?raw=true" alt="CLI TUI Dashboard showing server status" width="95%">
- <br/>
- <p align="center"><small><em>Live TUI Dashboard: Real-time server & tool monitoring (<code>/dashboard</code>).</em></small></p>
- </td>
- </tr>
- <tr>
- <td align="center" valign="top" width="33%">
- <img src="https://github.com/Dicklesworthstone/ultimate_mcp_client/blob/main/screenshots/webui_example_01.webp?raw=true" alt="Web UI Chat Interface" width="95%">
- <br/>
- <p align="center"><small><em>Web UI: Main chat interface showing messages and tool interactions.</em></small></p>
- </td>
- <td align="center" valign="top" width="33%">
- <img src="https://github.com/Dicklesworthstone/ultimate_mcp_client/blob/main/screenshots/webui_example_02.webp?raw=true" alt="Web UI Server Management Tab" width="95%">
- <br/>
- <p align="center"><small><em>Web UI: Server management tab with connection status and controls.</em></small></p>
- </td>
- <td align="center" valign="top" width="33%">
- <img src="https://github.com/Dicklesworthstone/ultimate_mcp_client/blob/main/screenshots/webui_example_03.webp?raw=true" alt="Web UI Conversation Branching View" width="95%">
- <br/>
- <p align="center"><small><em>Web UI: Conversation tab showing the branching graph structure.</em></small></p>
- </td>
- </tr>
- </tbody>
- </table>
- > **Note:** Some screenshots feature tools like `llm_gateway:generate_completion`. These are provided by the [LLM Gateway MCP Server](https://github.com/Dicklesworthstone/llm_gateway_mcp_server), another project by the same author. This server acts as an MCP-native gateway, enabling advanced agents (like Claude, used by *this* client) to intelligently delegate tasks to various other LLMs (e.g., Gemini, GPT-4o-mini), often optimizing for cost and performance.
- <br/>
- ---
- ## 🚀 Quickstart
- ### Install Dependencies
- > **Requires Python 3.13+**
- First, install [uv](https://github.com/astral-sh/uv) (the recommended fast Python package installer):
- ```bash
- # macOS / Linux
- curl -LsSf https://astral.sh/uv/install.sh | sh
- # Windows
- powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
- ```
- Then clone the repository, set up a virtual environment using Python 3.13+, and install packages:
- ```bash
- git clone https://github.com/Dicklesworthstone/ultimate_mcp_client
- cd ultimate_mcp_client
- # Create venv using uv (recommended)
- uv venv --python 3.13
- # Or using standard venv
- # python3.13 -m venv .venv
- # Activate environment
- source .venv/bin/activate # Linux/macOS
- # .venv\Scripts\activate # Windows Powershell
- # .\venv\Scripts\activate.bat # Windows CMD
- # Install dependencies using uv (fastest)
- uv sync --all-extras
- # Or using pip (slower)
- # pip install -e . # Installs only core dependencies
- ```
- ### Configure API Key
- Set your Anthropic API key as an environment variable:
- ```bash
- export ANTHROPIC_API_KEY="sk-ant-..."
- # Or add ANTHROPIC_API_KEY="sk-ant-..." to a .env file in the project root
- ```
- Alternatively, set it later using the `/config api-key ...` command in the interactive CLI or via the Web UI settings panel.
- ### Launch the Web UI (Recommended)
- ```bash
- mcpclient run --webui
- ```
- Then open your browser to `http://127.0.0.1:8017` (or the configured host/port).
- You can customize the host and port:
- ```bash
- mcpclient run --webui --host 0.0.0.0 --port 8080
- ```
- ### Run Interactive CLI Mode
- ```bash
- mcpclient run --interactive
- ```
- ### Run a One-Off Query
- ```bash
- mcpclient run --query "What's the weather in New York?"
- ```
- ### Show the CLI Dashboard
- ```bash
- mcpclient run --dashboard
- ```
- ### Configure Port Scanning
- ```bash
- # Enable port scanning (if disabled)
- mcpclient config port-scan enable true
- # Set the range (example)
- mcpclient config port-scan range 8000 8999
- ```
- ### Import and Export Conversations
- ```bash
- # Export current conversation branch to a default filename
- mcpclient export
- # Export current branch to a specific file
- mcpclient export --output my_conversation.json
- # Export specific conversation branch by ID (first 8 chars often suffice)
- mcpclient export --id 12345678 --output specific_branch.json
- # Import a conversation file (creates a new branch under the current node)
- mcpclient import-conv my_conversation.json
- ```
- ---
- ## 🌐 Web UI Features
- The web UI (`mcpclient run --webui`) provides a modern, user-friendly interface built with Alpine.js, Tailwind CSS, and DaisyUI:
- - **Real-time Chat:** Streamed responses from Claude via WebSockets, rich Markdown rendering (via `Marked.js`), code block syntax highlighting (via `highlight.js`) with copy buttons, and clear display of system messages and status updates.
- - **Tool Interaction:** Visual separation and display of tool calls (arguments) and their results (success or error) directly within the chat flow. A modal allows direct execution of any available tool with custom JSON parameters for testing and debugging.
- - **Server Management:** A dedicated sidebar tab lists configured servers. Users can:
- - Add new servers (STDIO/SSE/Streaming-HTTP) via a modal form.
- - Connect/disconnect from servers with status indicators (loading, connected, disconnected, error).
- - Enable/disable servers (automatically disconnects if disabled).
- - Remove server configurations.
- - View basic health/status and the number of tools provided by each server.
- - **Discovery:** Buttons in the Servers tab trigger discovery scans (local filesystem, remote registry, mDNS). Discovered servers are listed, allowing users to add them to the configuration with one click.
- - **Conversation Branching:** An interactive tree view in the Conversation tab visualizes the `ConversationGraph`. Users can click to checkout different branches (updating the chat view) or fork the current point to create new branches.
- - **Context Management:** Buttons in the Conversation tab allow users to clear the current branch's messages (resetting to parent/root state) or trigger context optimization/summarization via the API.
- - **Import/Export:** Buttons in the Conversation tab allow exporting the current branch to a JSON file or importing a previously exported JSON file via file selection (uploading to the backend).
- - **Settings:** A dedicated sidebar tab allows users to view and modify key configuration options (API Key, Default Model, Max Tokens, Temperature, feature toggles like Streaming, Caching, Auto-Discovery, mDNS) which are persisted to the server's config file.
- - **Theme Switching:** A dropdown menu allows selecting from a wide range of DaisyUI themes. The UI adapts instantly, and code highlighting automatically switches between light/dark styles based on the selected theme.
- - **Status Indicators:** Real-time WebSocket connection status icon, overall server connection count, and total available tool count are displayed in the header. Transient status messages (e.g., "Executing tool...") appear below the chat input.
- ---
- ## 🔌 API Server
- When running with `--webui`, a FastAPI server provides programmatic access:
- ```
- GET /api/status - Client overview (model, servers, tools, history count, current node)
- GET /api/config - Get current (non-sensitive) configuration
- PUT /api/config - Update configuration settings (e.g., { "temperature": 0.8 })
- GET /api/servers - List all configured servers with status, health, tools
- POST /api/servers - Add a new server configuration (Supports stdio/sse/streaming-http transports)
- DELETE /api/servers/{server_name} - Remove a server configuration
- POST /api/servers/{server_name}/connect - Connect to a specific server
- POST /api/servers/{server_name}/disconnect - Disconnect from a specific server
- PUT /api/servers/{server_name}/enable?enabled={true|false} - Enable/disable a server
- GET /api/tools - List all available tools from connected servers
- GET /api/resources - List all available resources
- GET /api/prompts - List all available prompts
- GET /api/conversation - Get current conversation state (messages, current node ID/name, full node graph)
- POST /api/conversation/fork - Create a fork (optionally named) from the current conversation node
- POST /api/conversation/checkout - Switch the current context to a different conversation node/branch (by ID)
- POST /api/conversation/clear - Clear messages on the current node and switch to root
- POST /api/conversation/optimize - Trigger context summarization for the current node (optional model/token args)
- POST /api/tool/execute - Execute a specific tool with given parameters (Requires ToolExecuteRequest model)
- WS /ws/chat - WebSocket endpoint for streaming chat (`query`, `command`), receiving updates (`text_chunk`, `status`, `query_complete`, `error`, `state_update`).
- ```
- *(Note: The actual request/response models like `ServerAddRequest`, `ToolExecuteRequest` are defined in the Python code and used by FastAPI for validation.)*
- ---
- ## ⚙️ Commands
- ### CLI Options
- Run `mcpclient --help` or `mcpclient [COMMAND] --help` for details.
- ### Interactive Shell Commands (`mcpclient run --interactive`)
- Type `/` followed by a command:
- ```text
- /help Show this help message
- /exit, /quit Exit the client
- /config Manage configuration (api-key, model, max-tokens, history-size, auto-discover, discovery-path, port-scan)
- /servers Manage MCP servers (list, add, remove, connect, disconnect, enable, disable, status)
- /discover Discover/manage LAN servers (list, connect <NAME>, refresh, auto <on|off>)
- /tools List available tools (optionally filter by server: /tools <server_name>)
- /tool Directly execute a tool: /tool <tool_name> '{"param": "value"}'
- /resources List available resources (optionally filter by server: /resources <server_name>)
- /prompts List available prompt templates (optionally filter by server: /prompts <server_name>)
- /prompt Apply a prompt template to the current conversation context: /prompt <prompt_name>
- /model View or change the current AI model: /model [<model_name>]
- /fork Create a new branch from the current conversation point: /fork [Optional Branch Name]
- /branch Manage branches (list, checkout <node_id_prefix>)
- /export Export current branch: /export [--id <node_id>] [--output <file.json>]
- /import Import conversation file: /import <file.json>
- /history View recent conversation history (optionally specify number: /history 10)
- /cache Manage tool cache (list, clear [--all|tool_name], clean, dependencies [tool_name])
- /dashboard Show the live Textual User Interface (TUI) dashboard (requires separate run)
- /optimize Summarize current conversation context: /optimize [--model <model>] [--tokens <num>]
- /reload Disconnect, reload capabilities, and reconnect to enabled servers
- /clear Clear messages in the current branch and optionally reset to root
- ```
- ---
- ## 🏗️ Architecture & Engineering Highlights
- This client employs several techniques to provide a robust and feature-rich experience:
- - **Asynchronous Core:** Built entirely on Python's `asyncio` for efficient handling of network I/O (HTTP, WebSockets, SSE), subprocess communication (`stdio`), filesystem operations (`aiofiles`), and concurrent background tasks (monitoring, discovery, port scanning).
- - **Component-Based Design:** While packaged primarily as a single script for ease of use, it internally separates concerns into distinct classes:
- - `MCPClient`: The main application class, orchestrating UI loops, command handling, and core logic.
- - `ServerManager`: Handles server configuration, lifecycle (connecting, disconnecting, restarting), discovery mechanisms, capability aggregation (tools, resources, prompts), and manages server processes/sessions. Uses `AsyncExitStack` for reliable resource cleanup. Supports all transport types including the modern `streaming-http` protocol via FastMCP integration.
- - **`RobustStdioSession` (Key Engineering Effort):** A custom implementation of the `mcp.ClientSession` tailored specifically for `stdio` servers. It includes logic to:
- - Filter non-JSON-RPC output from the server's `stdout` to prevent protocol errors.
- - Handle responses by directly resolving `asyncio.Future` objects associated with request IDs, offering a potentially more performant alternative to queue-based approaches.
- - Manage background tasks for reading `stdout` and writing captured `stderr` to log files asynchronously.
- - Gracefully handle process termination and cleanup.
- - **STDIO Safety Mechanisms (Crucial):** A multi-layered defense against accidental `stdout` pollution, which is fatal for `stdio`-based protocols:
- - `StdioProtectionWrapper`: Globally wraps `sys.stdout` to intercept writes, redirecting them to `stderr` if any `stdio` server is active.
- - `safe_stdout()`: A context manager used during critical operations (like server connection) to temporarily redirect `stdout` to `stderr`.
- - `get_safe_console()` / `safe_print()`: Utility functions ensuring that UI output (via `Rich`) uses the correct stream (`stdout` or `stderr`) based on active `stdio` servers.
- - These measures allow the client UI and logging to function correctly even when communicating with sensitive `stdio` servers.
- - `ConversationGraph`: Manages the non-linear, branching conversation structure using `ConversationNode` objects. Handles persistence to/from JSON.
- - `ToolCache`: Implements caching logic using `diskcache` for persistence and an in-memory layer for speed. Includes TTL management and dependency invalidation.
- - `ServerRegistry` / `ServerMonitor`: Handle mDNS/Zeroconf discovery/registration and background server health checks with recovery attempts.
- - **Dual Interface Implementation:**
- - **Web Backend:** Uses `FastAPI` for a clean REST API structure, `uvicorn` for the ASGI server, and `websockets` for bidirectional real-time chat. A FastAPI `lifespan` context manager ensures the `MCPClient` is properly initialized on startup and cleaned up on shutdown. Dependency injection provides endpoint access to the client instance.
- - **Web Frontend:** Leverages `Alpine.js` for lightweight reactivity and component logic directly in the HTML. `Tailwind CSS` and `DaisyUI` provide styling and pre-built components. `Marked.js`, `highlight.js`, and `DOMPurify` handle secure and attractive rendering of Markdown and code. `Tippy.js` provides tooltips.
- - **CLI/TUI:** Uses `Typer` for defining the command-line interface and parsing arguments. `Rich` is heavily used for formatted console output, tables, progress bars, Markdown rendering, syntax highlighting, and the live TUI dashboard. Careful management (`_run_with_progress`, `_run_with_simple_progress` helpers) prevents issues with nested `Rich Live` displays during complex operations.
- - **Resilience & Error Handling:** Employs decorators (`@retry_with_circuit_breaker`, `@with_tool_error_handling`) for common patterns like retries and standardized error reporting during tool execution. Structured `try...except...finally` blocks are used throughout for robustness.
- - **Observability:** Integrates `OpenTelemetry` for structured metrics (request counters, latency histograms, tool executions) and distributed tracing (spans track operations like query processing, server connections, tool calls). This aids in performance analysis and debugging.
- - **Configuration:** Flexible configuration system using a `config.yaml` file, environment variables (especially for sensitive keys like `ANTHROPIC_API_KEY`), and interactive commands or Web UI settings that persist changes back to the YAML file.
- ---
- ## 🔄 Smart Cache Dependency Tracking
- The Smart Cache Dependency system allows tools to declare dependencies on other tools:
- - When a tool's cache is invalidated, all dependent tools are automatically invalidated
- - Dependencies are registered when servers declare tool relationships
- - View the dependency graph with `/cache dependencies`
- - Improves data consistency by ensuring related tools use fresh data
- Example dependency flow:
- ```
- weather:current → weather:forecast → travel:recommendations
- ```
- If the current weather data is updated, both the forecast and travel recommendations caches are automatically invalidated.
- ---
- ## 🔍 Tool & Server Discovery
- This client offers multiple ways to find and integrate MCP servers:
- - **Configured Paths:** Searches directories specified in `config.yaml` (under `discovery_paths`) for local `stdio` server scripts (e.g., `.py`, `.js`). Defaults include:
- - `.mcpclient_config/servers` (in project root)
- - `~/mcp-servers`
- - `~/modelcontextprotocol/servers`
- - **Claude Desktop Config (`claude_desktop_config.json`):** If this file exists in the project root, the client automatically imports server definitions from it during setup.
- - **Intelligent Command Adaptation:**
- - Detects `wsl.exe ... <shell> -c "command ..."` patterns.
- - Extracts the Linux `<shell>` (e.g., `bash`, `sh`) and the `"command ..."`.
- - Remaps the configuration to execute the command directly using the identified Linux shell (e.g., `/bin/bash -c "command ..."`), bypassing `wsl.exe`.
- - For other command types (e.g., `npx ...`), it uses `adapt_path_for_platform` to scan arguments for Windows-style paths (`C:\Users\...`) and converts them to their `/mnt/c/Users/...` equivalents, ensuring compatibility when running the client in WSL/Linux.
- - **Remote Registries:** Connects to MCP registry server URLs defined in `config.yaml` (`registry_urls`) to discover publicly available or shared servers (typically SSE).
- - **Local Network (mDNS/Zeroconf):**
- - Uses the `zeroconf` library to listen for services advertised under `_mcp._tcp.local.` on the local network.
- - Provides real-time notifications in the interactive CLI when new servers appear or disappear.
- - The `/discover` command suite allows managing these discovered servers:
- - `/discover list`: View details of currently visible LAN servers.
- - `/discover connect <NAME>`: Add a discovered server to the configuration file and attempt to connect.
- - `/discover refresh`: Manually trigger a re-scan of the network.
- - `/discover auto [on|off]`: Toggle continuous background mDNS scanning (requires `enable_local_discovery: true` in config).
- - **Local Port Scanning:**
- - If enabled (`enable_port_scanning: true` in `config.yaml` or via `/config port-scan enable true`), actively scans a range of ports on specified local IP addresses during startup discovery.
- - Attempts a basic MCP `initialize` handshake on each port to detect responsive MCP servers. Supports automatic detection of `sse` and `streaming-http` transport types based on server responses and HTTP headers.
- - Useful for finding servers that don't use mDNS advertisement.
- - The range, target IPs, concurrency, and timeout are configurable via `config.yaml` or the `/config port-scan ...` commands.
- - Found servers are presented alongside other discovered servers for optional addition to the configuration.
- ---
- ## 📡 Telemetry + Debugging
- - **OpenTelemetry:** Generates traces and metrics for key operations. By default, data is collected but not exported. Set `use_console_exporter = True` near the top of `mcpclient.py` to enable noisy console output for debugging traces and metrics. For production, configure appropriate OTel exporters (e.g., Jaeger, Prometheus).
- - **Dashboards:**
- - **CLI:** Run `mcpclient run --dashboard` for a live TUI monitoring view powered by `Rich`. Shows server status, health, connection state, basic tool usage stats, and client info. Refreshes periodically.
- - **Web UI:** The "Servers" tab provides visual server status (connection, health via icons), and the header shows overall counts.
- - **Logging:** Uses Python's standard `logging` configured with `RichHandler` for pretty console output (to `stderr` to avoid `stdio` conflicts).
- - Use the `--verbose` or `-v` flag to increase log level to DEBUG for detailed internal information.
- - Verbose mode also enables detailed `stdio` session logging (`USE_VERBOSE_SESSION_LOGGING = True`) to see raw JSON-RPC messages (useful for debugging MCP servers).
- - **Error Tracebacks:** Set the environment variable `MCP_CLIENT_DEBUG=1` before running to make the CLI print full Python tracebacks for unexpected errors, aiding in debugging client-side issues.
- - **STDIO Server Logs:** The `stderr` output from `stdio` servers is captured asynchronously and written to log files in the configuration directory (e.g., `.mcpclient_config/<server_name>_stderr.log`), crucial for diagnosing server-side problems.
- ---
- ## 📦 Configuration
- - **Primary File:** Configuration is loaded from and saved to `.mcpclient_config/config.yaml` located in the project's root directory.
- - **Environment Variables:** `ANTHROPIC_API_KEY` is the primary way to provide the API key and overrides any key stored in the config file. `EDITOR` is used by `/config edit`. `MCP_CLIENT_DEBUG=1` enables tracebacks.
- - **Interactive CLI:** The `/config` command allows viewing and modifying settings like `api-key`, `model`, `max-tokens`, `discovery-path`, port scanning parameters, etc. Changes are saved back to `config.yaml`.
- - **Web UI Settings:** The "Settings" tab in the Web UI provides controls for common configuration options. Changes made here are sent via the API and saved to `config.yaml`.
- **View Current Config:**
- ```bash
- mcpclient config --show
- # OR in interactive mode:
- /config
- ```
- **Edit Config File Manually:**
- ```bash
- mcpclient config --edit
- # (This will open .mcpclient_config/config.yaml in the editor specified by your $EDITOR environment variable)
- ```
- ---
- ## 🧪 Development Notes
- - **Core:** Python 3.13+, `asyncio`
- - **CLI:** `Typer`, `Rich`
- - **Web:** `FastAPI`, `Uvicorn`, `WebSockets`, `Alpine.js`, `Tailwind CSS`, `DaisyUI`
- - **MCP:** `mcp` SDK (`mcp>=1.0.0`), `fastmcp` (for streaming-http transport)
- - **AI:** `anthropic` SDK (`anthropic>=0.15.0`)
- - **Observability:** `opentelemetry-sdk`, `opentelemetry-api`, `opentelemetry-instrumentation`
- - **Utilities:** `httpx`, `PyYAML`, `python-dotenv`, `psutil`, `aiofiles`, `diskcache`, `tiktoken`, `zeroconf`, `colorama`
- - **Linting/Formatting:** `ruff` is configured in `pyproject.toml`. Use `uv run lint` or `ruff check . && ruff format .`.
- - **Type Checking:** `mypy` is configured in `pyproject.toml`. Use `uv run typecheck` or `mypy mcpclient.py`.
- The project is primarily structured within `mcpclient.py` for easier distribution and introspection, although internal class-based modularity is maintained. The Web UI is served from the self-contained `mcp_client_ui.html` file, utilizing CDN-hosted libraries for simplicity. Key complex logic, such as the robust `stdio` handling and asynchronous management, resides within dedicated classes like `RobustStdioSession` and `ServerManager`.
- ---
- ## 📝 License
- MIT License (with OpenAI/Anthropic Rider). See [LICENSE](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.