chrishayuk/mcp-cli

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 --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
- **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