MCP CLI - Model Context Protocol Command Line Interface

A powerful, feature-rich command-line interface for interacting with Model Context Protocol servers. This client enables seamless communication with LLMs through integration with the CHUK Tool Processor and CHUK-LLM, providing tool usage, conversation management, and multiple operational modes.

Default Configuration: MCP CLI defaults to using Ollama with the gpt-oss reasoning model for local, privacy-focused operation without requiring API keys.

🆕 Recent Updates (v0.16)

AI Virtual Memory (Experimental)

• --vm flag: Enable OS-style virtual memory for conversation context management, powered by chuk-ai-session-manager
• --vm-budget: Control token budget for conversation events (system prompt is uncapped on top), forcing earlier eviction and page creation
• --vm-mode: Choose VM mode — passive (runtime-managed, default), relaxed (VM-aware conversation), or strict (model-driven paging with tools)
• /memory command: Visualize VM state during conversations — page table, working set utilization, eviction metrics, TLB stats (aliases: /vm, /mem)
• Multimodal page_fault: Image pages return multi-block content (text + image_url) so multimodal models can re-analyze recalled images
• /memory page <id> --download: Export page content to local files with modality-aware extensions (.txt, .json, .png)

Execution Plans (Tier 6)

• /plan command: Create, inspect, and execute reproducible tool call graphs — create, list, show, run, delete, resume
• Model-driven planning (--plan-tools): The LLM autonomously creates and executes plans during conversation — no /plan command needed. It calls plan_create_and_execute when multi-step orchestration is required, and uses regular tools for simple tasks. Each step renders with real-time progress in the terminal
• Parallel batch execution: Independent plan steps run concurrently via topological batching (Kahn's BFS), with configurable max_concurrency
• Variable resolution: ${var}, ${var.field} nested access, and template strings like "https://${api.host}/users" — type-preserving for single refs
• Dry-run mode: Trace planned tool calls without executing — safe for production inspection
• Checkpointing & resume: Execution state persisted after each batch; resume interrupted plans with /plan resume <id>
• Guard integration: Plans respect existing budget, per-tool limits, and runaway detection guards
• DAG visualization: ASCII rendering with status indicators (○/◉/●/✗) and parallel markers (∥)
• Re-planning: Optional LLM-based re-planning on step failure (enable_replan=True)
• Powered by: chuk-ai-planner graph-based plan DSL

MCP Apps (SEP-1865)

• Interactive HTML UIs: MCP servers can serve interactive HTML applications (charts, tables, maps, markdown viewers) that render in your browser
• Sandboxed iframes: Apps run in secure sandboxed iframes with CSP protection
• WebSocket bridge: Real-time bidirectional communication between browser apps and MCP servers
• Automatic launch: Tools with _meta.ui annotations automatically open in the browser when called
• Session reliability: Message queuing, reconnection with exponential backoff, deferred tool result delivery

Production Hardening

• Secret Redaction: All log output (console and file) is automatically redacted for Bearer tokens, API keys, OAuth tokens, and Authorization headers
• Structured File Logging: Optional --log-file flag enables rotating JSON log files (10MB, 3 backups) at DEBUG level
• Per-Server Timeouts: Server configs support tool_timeout and init_timeout overrides, resolved per-server → global → default
• Thread-Safe OAuth: Concurrent OAuth flows serialized with asyncio.Lock and copy-on-write header mutation
• Server Health Monitoring: /health command, health-check-on-failure diagnostics, optional --health-interval background polling

Performance & Polish

• O(1) Tool Lookups: Indexed tool lookup replacing O(n) linear scans
• Cached LLM Tool Metadata: Per-provider caching with automatic invalidation
• Startup Progress: Real-time progress messages during initialization
• Token Usage Tracking: Per-turn and cumulative tracking with /usage command (aliases: /tokens, /cost)
• Session Persistence: Save/load/list conversation sessions with auto-save every 10 turns (/sessions)
• Conversation Export: Export conversations as Markdown or JSON with metadata (/export)

Dashboard (Real-Time Browser UI)

• --dashboard flag: Launch a real-time browser dashboard alongside chat mode
• Agent Terminal: Live conversation view with message bubbles, streaming tokens, and attachment rendering
• Activity Stream: Tool call/result pairs, reasoning steps, and user attachment events
• Plan Viewer: Visual execution plan progress with DAG rendering
• Tool Registry: Browse discovered tools, trigger execution from the browser
• Config Panel: View and switch providers, models, and system prompt
• File Attachments: "+" button for browser file upload, drag-and-drop, and clipboard paste

Multi-Modal Attachments

• /attach command: Stage files for the next message — images, text/code, and audio (aliases: /file, /image)
• --attach CLI flag: Attach files to the first message (repeatable: --attach img.png --attach code.py)
• Inline @file: references: Mention @file:path/to/file anywhere in a message to attach it
• Image URL detection: HTTP/HTTPS image URLs in messages are automatically sent as vision content
• Supported formats: PNG, JPEG, GIF, WebP, HEIC (images), MP3, WAV (audio), plus 25+ text/code extensions
• Dashboard rendering: Image thumbnails, expandable text previews, audio players, file badges
• Browser upload: "+" button in dashboard chat input with drag-and-drop and clipboard paste support

Code Quality

• Core/UI Separation: Core modules use logging only — no UI imports
• 4,300+ tests: Comprehensive test suite with branch coverage, integration tests, and 60% minimum threshold
• 15 Architecture Principles: Documented and enforced (see architecture.md)
• Full Roadmap: Tiers 1-6 complete, Tiers 7-12 planned (traces, memory scopes, skills, scheduling, multi-agent)

🔄 Architecture Overview

The MCP CLI is built on a modular architecture with clean separation of concerns:

• CHUK Tool Processor: Production-grade async tool execution with middleware (retry, circuit breaker, rate limiting), multiple execution strategies, and observability
• CHUK-LLM: Unified LLM provider with dynamic model discovery, capability-based selection, and llama.cpp integration (1.53x faster than Ollama with automatic model reuse)
• CHUK-Term: Enhanced terminal UI with themes, cross-platform terminal management, and rich formatting
• MCP CLI: Command orchestration and integration layer (this project)

🌟 Features

Multiple Operational Modes

• Chat Mode: Conversational interface with streaming responses and automated tool usage (default: Ollama/gpt-oss)
• Interactive Mode: Command-driven shell interface for direct server operations
• Command Mode: Unix-friendly mode for scriptable automation and pipelines
• Direct Commands: Run individual commands without entering interactive mode

Advanced Chat Interface

• Streaming Responses: Real-time response generation with live UI updates
• Reasoning Visibility: See AI's thinking process with reasoning models (gpt-oss, GPT-5, Claude 4.5)
• Concurrent Tool Execution: Execute multiple tools simultaneously while preserving conversation order
• Smart Interruption: Interrupt streaming responses or tool execution with Ctrl+C
• Performance Metrics: Response timing, words/second, and execution statistics
• Rich Formatting: Markdown rendering, syntax highlighting, and progress indicators
• Token Usage Tracking: Per-turn and cumulative API token usage with /usage command
• Multi-Modal Attachments: Attach images, text files, and audio to messages via /attach, --attach, @file: refs, or browser upload
• Session Persistence: Auto-save and manual save/load of conversation sessions
• Conversation Export: Export to Markdown or JSON with metadata and token usage

Comprehensive Provider Support

MCP CLI supports all providers and models from CHUK-LLM, including cutting-edge reasoning models:

Robust Tool System (Powered by CHUK Tool Processor v0.22+)

• Automatic Discovery: Server-provided tools are automatically detected and catalogued
• Provider Adaptation: Tool names are automatically sanitized for provider compatibility
• Production-Grade Execution: Middleware layers with timeouts, retries, exponential backoff, caching, and circuit breakers
• Multiple Execution Strategies: In-process (fast), isolated subprocess (safe), or remote via MCP
• Concurrent Execution: Multiple tools can run simultaneously with proper coordination
• Rich Progress Display: Real-time progress indicators and execution timing
• Tool History: Complete audit trail of all tool executions
• Middleware: Retry with exponential backoff, circuit breakers, and rate limiting via CTP
• Streaming Tool Calls: Support for tools that return streaming data

MCP Apps (Interactive UIs)

• Browser-based UIs: MCP servers can serve interactive HTML applications that render in your browser
• Automatic Detection: Tools with _meta.ui annotations automatically launch browser apps on tool call
• Sandboxed Execution: Apps run in secure sandboxed iframes with Content Security Policy protection
• WebSocket Bridge: Real-time JSON-RPC bridge between browser apps and MCP tool servers
• Session Persistence: Message queuing during disconnects, automatic reconnection, deferred tool result delivery
• structuredContent Support: Full MCP spec compliance including structured content extraction and forwarding

Execution Plans (Powered by chuk-ai-planner)

• Plan Creation: Generate execution plans from natural language descriptions using LLM-based plan agents
• Model-Driven Planning: With --plan-tools, the LLM autonomously decides when to plan — calls plan_create_and_execute for complex multi-step tasks, uses regular tools for simple ones
• DAG Execution: Plans are directed acyclic graphs — independent steps run in parallel batches, dependent steps wait
• Variable Resolution: Step outputs bind to variables (result_variable), referenced by later steps as ${var} or ${var.field}
• Dry-Run Mode: Trace what a plan would do without executing any tools — safe for production
• Checkpointing: Execution state saved after each batch; resume interrupted plans without re-running completed steps
• Guard Integration: Plans share budget and per-tool limits with the conversation — no bypass
• Re-planning: On step failure, optionally invoke the LLM to generate a revised plan for remaining work
• DAG Visualization: ASCII rendering shows dependency structure, batch grouping, and parallel markers
• Persistence: Plans stored as JSON at ~/.mcp-cli/plans/

Advanced Configuration Management

• Environment Integration: API keys and settings via environment variables
• File-based Config: YAML and JSON configuration files
• User Preferences: Persistent settings for active providers and models
• Validation & Diagnostics: Built-in provider health checks and configuration validation

Enhanced User Experience

• Cross-Platform Support: Windows, macOS, and Linux with platform-specific optimizations via chuk-term
• Rich Console Output: Powered by chuk-term with 8 built-in themes (default, dark, light, minimal, terminal, monokai, dracula, solarized)
• Advanced Terminal Management: Cross-platform terminal operations including clearing, resizing, color detection, and cursor control
• Interactive UI Components: User input handling through chuk-term's prompt system (ask, confirm, select_from_list, select_multiple)
• Command Completion: Context-aware tab completion for all interfaces

• Comprehensive Help: Detailed help system with examples and usage patterns