🧠 Ultimate MCP Client

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 and sse (HTTP Server-Sent Events) 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.

• 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. Useful for servers not advertising via mDNS. 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:

Interactive CLI: Streaming response with tool call/result.	Live TUI Dashboard: Real-time server & tool monitoring (/dashboard).
Web UI: Main chat interface showing messages and tool interactions.	Web UI: Server management tab with connection status and controls.	Web UI: Conversation tab showing the branching graph structure.

Note: Some screenshots feature tools like llm_gateway:generate_completion. These are provided by the 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.

🚀 Quickstart

Install Dependencies

Requires Python 3.13+

First, install 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

🌐 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) 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 (Requires ServerAddRequest model)
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:

/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.
  • 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 (primarily SSE).
  • 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:

mcpclient config --show
# OR in interactive mode:
/config

Edit Config File Manually:

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)
• 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. Refer to standard MIT terms.