$ show IBM/mcp-cli
This repository is a production-grade CLI application (`mcp-cli`) for interacting with the Model Context Protocol (MCP). It serves as an orchestration layer over MCP servers and Large Language Models (LLMs), providing a unified interface across chat, interactive shell, and scriptable command modes. The architecture is a monolithic Python application built on the `chuk-*` ecosystem, featuring a sophisticated unified command system, a streaming display manager, a WebSocket-based dashboard, multi-agent orchestration, and a planning subsystem for autonomous tool execution. It manages the full lifecycle of MCP server connections, tool discovery/execution, LLM provider abstraction, and session persistence. The codebase demonstrates high craftsmanship through its extensive use of Pydantic models for type safety, a well-isolated command pattern, and security-conscious utilities for SSRF protection and secret redaction. Key reusable components include the unified command framework (`UnifiedCommand`, `CommandRegistry`), the streaming display manager with content-type detection, and the `McpToolBackend` adapter that bridges planning systems to tool execution with guard integration. The project is actively maintained with a large test suite, though its heavy coupling to the `chuk-*` library ecosystem and cutting-edge Python version (3.14) represent notable technical dependencies.
The LLM identified 5 files worth highlighting for reuse:
Provides an abstract `UnifiedCommand` base class, `CommandGroup`, `CommandResult`, and `CommandMode` enums, managed by a singleton `UnifiedCommandRegistry`. This framework allows a single command implementation to be seamlessly exposed across chat (slash commands), interactive shell, and CLI (Typer) modes. It is a self-contained, reusable pattern for building multi-interface CLI applications.
Implements robust SSRF (Server-Side Request Forgery) protection by validating outbound URLs against private, loopback, and link-local IP ranges. It provides a clean, testable function to check if a URL is safe to fetch, preventing the application from being used as a proxy to internal networks. This is a highly reusable security primitive for any application that fetches user-provided URLs.
Manages the real-time display of streaming LLM responses and tool execution status in a terminal UI. It uses a Pydantic state machine (`StreamingState`, `StreamingChunk`) to handle content type detection (code, markdown, JSON), buffer caps, stall detection, and reasoning previews. This component encapsulates complex async display logic and can be adapted for any streaming text application.
Provides a `ToolSchemaValidator` that validates and automatically fixes tool call arguments against their JSON schemas. It handles common LLM errors like incorrect types, missing required fields, and extra properties. This is a critical and reusable component for any system that relies on LLMs to generate structured tool calls.
Acts as a bridge between an external planning system (`chuk_ai_planner`) and the core `ToolManager`. It translates planner requests into tool executions, handles namespace-prefixed tool names, integrates optional confirmation prompts and pre-execution guard checks (budget, runaway detection), and normalizes heterogeneous tool results into a unified format. This adapter pattern cleanly separates planning logic from tool execution infrastructure.