[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-IBM--mcp-cli":3,"tool-IBM--mcp-cli":64},[4,17,27,35,43,56],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":16},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,3,"2026-04-05T11:01:52",[13,14,15],"开发框架","图像","Agent","ready",{"id":18,"name":19,"github_repo":20,"description_zh":21,"stars":22,"difficulty_score":23,"last_commit_at":24,"category_tags":25,"status":16},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",138956,2,"2026-04-05T11:33:21",[13,15,26],"语言模型",{"id":28,"name":29,"github_repo":30,"description_zh":31,"stars":32,"difficulty_score":23,"last_commit_at":33,"category_tags":34,"status":16},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107662,"2026-04-03T11:11:01",[13,14,15],{"id":36,"name":37,"github_repo":38,"description_zh":39,"stars":40,"difficulty_score":23,"last_commit_at":41,"category_tags":42,"status":16},3704,"NextChat","ChatGPTNextWeb\u002FNextChat","NextChat 是一款轻量且极速的 AI 助手，旨在为用户提供流畅、跨平台的大模型交互体验。它完美解决了用户在多设备间切换时难以保持对话连续性，以及面对众多 AI 模型不知如何统一管理的痛点。无论是日常办公、学习辅助还是创意激发，NextChat 都能让用户随时随地通过网页、iOS、Android、Windows、MacOS 或 Linux 端无缝接入智能服务。\n\n这款工具非常适合普通用户、学生、职场人士以及需要私有化部署的企业团队使用。对于开发者而言，它也提供了便捷的自托管方案，支持一键部署到 Vercel 或 Zeabur 等平台。\n\nNextChat 的核心亮点在于其广泛的模型兼容性，原生支持 Claude、DeepSeek、GPT-4 及 Gemini Pro 等主流大模型，让用户在一个界面即可自由切换不同 AI 能力。此外，它还率先支持 MCP（Model Context Protocol）协议，增强了上下文处理能力。针对企业用户，NextChat 提供专业版解决方案，具备品牌定制、细粒度权限控制、内部知识库整合及安全审计等功能，满足公司对数据隐私和个性化管理的高标准要求。",87618,"2026-04-05T07:20:52",[13,26],{"id":44,"name":45,"github_repo":46,"description_zh":47,"stars":48,"difficulty_score":23,"last_commit_at":49,"category_tags":50,"status":16},2268,"ML-For-Beginners","microsoft\u002FML-For-Beginners","ML-For-Beginners 是由微软推出的一套系统化机器学习入门课程，旨在帮助零基础用户轻松掌握经典机器学习知识。这套课程将学习路径规划为 12 周，包含 26 节精炼课程和 52 道配套测验，内容涵盖从基础概念到实际应用的完整流程，有效解决了初学者面对庞大知识体系时无从下手、缺乏结构化指导的痛点。\n\n无论是希望转型的开发者、需要补充算法背景的研究人员，还是对人工智能充满好奇的普通爱好者，都能从中受益。课程不仅提供了清晰的理论讲解，还强调动手实践，让用户在循序渐进中建立扎实的技能基础。其独特的亮点在于强大的多语言支持，通过自动化机制提供了包括简体中文在内的 50 多种语言版本，极大地降低了全球不同背景用户的学习门槛。此外，项目采用开源协作模式，社区活跃且内容持续更新，确保学习者能获取前沿且准确的技术资讯。如果你正寻找一条清晰、友好且专业的机器学习入门之路，ML-For-Beginners 将是理想的起点。",84991,"2026-04-05T10:45:23",[14,51,52,53,15,54,26,13,55],"数据工具","视频","插件","其他","音频",{"id":57,"name":58,"github_repo":59,"description_zh":60,"stars":61,"difficulty_score":10,"last_commit_at":62,"category_tags":63,"status":16},3128,"ragflow","infiniflow\u002Fragflow","RAGFlow 是一款领先的开源检索增强生成（RAG）引擎，旨在为大语言模型构建更精准、可靠的上下文层。它巧妙地将前沿的 RAG 技术与智能体（Agent）能力相结合，不仅支持从各类文档中高效提取知识，还能让模型基于这些知识进行逻辑推理和任务执行。\n\n在大模型应用中，幻觉问题和知识滞后是常见痛点。RAGFlow 通过深度解析复杂文档结构（如表格、图表及混合排版），显著提升了信息检索的准确度，从而有效减少模型“胡编乱造”的现象，确保回答既有据可依又具备时效性。其内置的智能体机制更进一步，使系统不仅能回答问题，还能自主规划步骤解决复杂问题。\n\n这款工具特别适合开发者、企业技术团队以及 AI 研究人员使用。无论是希望快速搭建私有知识库问答系统，还是致力于探索大模型在垂直领域落地的创新者，都能从中受益。RAGFlow 提供了可视化的工作流编排界面和灵活的 API 接口，既降低了非算法背景用户的上手门槛，也满足了专业开发者对系统深度定制的需求。作为基于 Apache 2.0 协议开源的项目，它正成为连接通用大模型与行业专有知识之间的重要桥梁。",77062,"2026-04-04T04:44:48",[15,14,13,26,54],{"id":65,"github_repo":66,"name":67,"description_en":68,"description_zh":69,"ai_summary_zh":69,"readme_en":70,"readme_zh":71,"quickstart_zh":72,"use_case_zh":73,"hero_image_url":74,"owner_login":75,"owner_name":76,"owner_avatar_url":77,"owner_bio":78,"owner_company":68,"owner_location":68,"owner_email":68,"owner_twitter":79,"owner_website":80,"owner_url":81,"languages":82,"stars":102,"forks":103,"last_commit_at":104,"license":105,"difficulty_score":23,"env_os":106,"env_gpu":107,"env_ram":108,"env_deps":109,"category_tags":119,"github_topics":68,"view_count":23,"oss_zip_url":68,"oss_zip_packed_at":68,"status":16,"created_at":120,"updated_at":121,"faqs":122,"releases":161},2046,"IBM\u002Fmcp-cli","mcp-cli",null,"mcp-cli 是一款功能强大的命令行工具，专为与模型上下文协议（MCP）服务器交互而设计。它旨在解决大语言模型（LLM）在本地部署时面临的上下文管理困难、复杂任务编排繁琐以及隐私安全等痛点，让用户无需 API 密钥即可通过 Ollama 等本地模型实现私密、流畅的对话与工具调用。\n\n这款工具特别适合开发者、AI 研究人员及热衷于本地化部署的技术爱好者使用。其核心亮点在于引入了实验性的\"AI 虚拟内存”机制，能像操作系统管理内存一样智能调度对话上下文，有效突破长对话的令牌限制；同时支持“执行计划”功能，可自动将复杂任务拆解为有向无环图（DAG），支持并行执行、断点续跑及可视化进度追踪。此外，mcp-cli 还能直接在浏览器中渲染 MCP 服务器提供的交互式 HTML 应用，并具备自动脱敏敏感信息的生产级安全特性，是构建高效、可控本地 AI 工作流的得力助手。","# MCP CLI - Model Context Protocol Command Line Interface\n\n[![CI](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fmcp-cli\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fmcp-cli\u002Factions\u002Fworkflows\u002Fci.yml)\n[![PyPI version](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fmcp-cli.svg)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fmcp-cli\u002F)\n\nA 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](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fchuk-tool-processor) and [CHUK-LLM](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fchuk-llm), providing tool usage, conversation management, and multiple operational modes.\n\n**Default Configuration**: MCP CLI defaults to using Ollama with the `gpt-oss` reasoning model for local, privacy-focused operation without requiring API keys.\n\n## 🆕 Recent Updates (v0.16)\n\n### AI Virtual Memory (Experimental)\n- **`--vm` flag**: Enable OS-style virtual memory for conversation context management, powered by `chuk-ai-session-manager`\n- **`--vm-budget`**: Control token budget for conversation events (system prompt is uncapped on top), forcing earlier eviction and page creation\n- **`--vm-mode`**: Choose VM mode — `passive` (runtime-managed, default), `relaxed` (VM-aware conversation), or `strict` (model-driven paging with tools)\n- **`\u002Fmemory` command**: Visualize VM state during conversations — page table, working set utilization, eviction metrics, TLB stats (aliases: `\u002Fvm`, `\u002Fmem`)\n- **Multimodal page_fault**: Image pages return multi-block content (text + image_url) so multimodal models can re-analyze recalled images\n- **`\u002Fmemory page \u003Cid> --download`**: Export page content to local files with modality-aware extensions (.txt, .json, .png)\n\n### Execution Plans (Tier 6)\n- **`\u002Fplan` command**: Create, inspect, and execute reproducible tool call graphs — `create`, `list`, `show`, `run`, `delete`, `resume`\n- **Model-driven planning (`--plan-tools`)**: The LLM autonomously creates and executes plans during conversation — no `\u002Fplan` 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\n- **Parallel batch execution**: Independent plan steps run concurrently via topological batching (Kahn's BFS), with configurable `max_concurrency`\n- **Variable resolution**: `${var}`, `${var.field}` nested access, and template strings like `\"https:\u002F\u002F${api.host}\u002Fusers\"` — type-preserving for single refs\n- **Dry-run mode**: Trace planned tool calls without executing — safe for production inspection\n- **Checkpointing & resume**: Execution state persisted after each batch; resume interrupted plans with `\u002Fplan resume \u003Cid>`\n- **Guard integration**: Plans respect existing budget, per-tool limits, and runaway detection guards\n- **DAG visualization**: ASCII rendering with status indicators (○\u002F◉\u002F●\u002F✗) and parallel markers (∥)\n- **Re-planning**: Optional LLM-based re-planning on step failure (`enable_replan=True`)\n- **Powered by**: [chuk-ai-planner](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fchuk-ai-planner) graph-based plan DSL\n\n### MCP Apps (SEP-1865)\n- **Interactive HTML UIs**: MCP servers can serve interactive HTML applications (charts, tables, maps, markdown viewers) that render in your browser\n- **Sandboxed iframes**: Apps run in secure sandboxed iframes with CSP protection\n- **WebSocket bridge**: Real-time bidirectional communication between browser apps and MCP servers\n- **Automatic launch**: Tools with `_meta.ui` annotations automatically open in the browser when called\n- **Session reliability**: Message queuing, reconnection with exponential backoff, deferred tool result delivery\n\n### Production Hardening\n- **Secret Redaction**: All log output (console and file) is automatically redacted for Bearer tokens, API keys, OAuth tokens, and Authorization headers\n- **Structured File Logging**: Optional `--log-file` flag enables rotating JSON log files (10MB, 3 backups) at DEBUG level\n- **Per-Server Timeouts**: Server configs support `tool_timeout` and `init_timeout` overrides, resolved per-server → global → default\n- **Thread-Safe OAuth**: Concurrent OAuth flows serialized with `asyncio.Lock` and copy-on-write header mutation\n- **Server Health Monitoring**: `\u002Fhealth` command, health-check-on-failure diagnostics, optional `--health-interval` background polling\n\n### Performance & Polish\n- **O(1) Tool Lookups**: Indexed tool lookup replacing O(n) linear scans\n- **Cached LLM Tool Metadata**: Per-provider caching with automatic invalidation\n- **Startup Progress**: Real-time progress messages during initialization\n- **Token Usage Tracking**: Per-turn and cumulative tracking with `\u002Fusage` command (aliases: `\u002Ftokens`, `\u002Fcost`)\n- **Session Persistence**: Save\u002Fload\u002Flist conversation sessions with auto-save every 10 turns (`\u002Fsessions`)\n- **Conversation Export**: Export conversations as Markdown or JSON with metadata (`\u002Fexport`)\n\n### Dashboard (Real-Time Browser UI)\n- **`--dashboard` flag**: Launch a real-time browser dashboard alongside chat mode\n- **Agent Terminal**: Live conversation view with message bubbles, streaming tokens, and attachment rendering\n- **Activity Stream**: Tool call\u002Fresult pairs, reasoning steps, and user attachment events\n- **Plan Viewer**: Visual execution plan progress with DAG rendering\n- **Tool Registry**: Browse discovered tools, trigger execution from the browser\n- **Config Panel**: View and switch providers, models, and system prompt\n- **File Attachments**: \"+\" button for browser file upload, drag-and-drop, and clipboard paste\n\n### Multi-Modal Attachments\n- **`\u002Fattach` command**: Stage files for the next message — images, text\u002Fcode, and audio (aliases: `\u002Ffile`, `\u002Fimage`)\n- **`--attach` CLI flag**: Attach files to the first message (repeatable: `--attach img.png --attach code.py`)\n- **Inline `@file:` references**: Mention `@file:path\u002Fto\u002Ffile` anywhere in a message to attach it\n- **Image URL detection**: HTTP\u002FHTTPS image URLs in messages are automatically sent as vision content\n- **Supported formats**: PNG, JPEG, GIF, WebP, HEIC (images), MP3, WAV (audio), plus 25+ text\u002Fcode extensions\n- **Dashboard rendering**: Image thumbnails, expandable text previews, audio players, file badges\n- **Browser upload**: \"+\" button in dashboard chat input with drag-and-drop and clipboard paste support\n\n### Code Quality\n- **Core\u002FUI Separation**: Core modules use `logging` only — no UI imports\n- **4,300+ tests**: Comprehensive test suite with branch coverage, integration tests, and 60% minimum threshold\n- **15 Architecture Principles**: Documented and enforced (see [architecture.md](architecture.md))\n- **Full [Roadmap](roadmap.md)**: Tiers 1-6 complete, Tiers 7-12 planned (traces, memory scopes, skills, scheduling, multi-agent)\n\n## 🔄 Architecture Overview\n\nThe MCP CLI is built on a modular architecture with clean separation of concerns:\n\n- **[CHUK Tool Processor](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fchuk-tool-processor)**: Production-grade async tool execution with middleware (retry, circuit breaker, rate limiting), multiple execution strategies, and observability\n- **[CHUK-LLM](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fchuk-llm)**: Unified LLM provider with dynamic model discovery, capability-based selection, and llama.cpp integration (1.53x faster than Ollama with automatic model reuse)\n- **[CHUK-Term](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fchuk-term)**: Enhanced terminal UI with themes, cross-platform terminal management, and rich formatting\n- **MCP CLI**: Command orchestration and integration layer (this project)\n\n## 🌟 Features\n\n### Multiple Operational Modes\n- **Chat Mode**: Conversational interface with streaming responses and automated tool usage (default: Ollama\u002Fgpt-oss)\n- **Interactive Mode**: Command-driven shell interface for direct server operations\n- **Command Mode**: Unix-friendly mode for scriptable automation and pipelines\n- **Direct Commands**: Run individual commands without entering interactive mode\n\n### Advanced Chat Interface\n- **Streaming Responses**: Real-time response generation with live UI updates\n- **Reasoning Visibility**: See AI's thinking process with reasoning models (gpt-oss, GPT-5, Claude 4.5)\n- **Concurrent Tool Execution**: Execute multiple tools simultaneously while preserving conversation order\n- **Smart Interruption**: Interrupt streaming responses or tool execution with Ctrl+C\n- **Performance Metrics**: Response timing, words\u002Fsecond, and execution statistics\n- **Rich Formatting**: Markdown rendering, syntax highlighting, and progress indicators\n- **Token Usage Tracking**: Per-turn and cumulative API token usage with `\u002Fusage` command\n- **Multi-Modal Attachments**: Attach images, text files, and audio to messages via `\u002Fattach`, `--attach`, `@file:` refs, or browser upload\n- **Session Persistence**: Auto-save and manual save\u002Fload of conversation sessions\n- **Conversation Export**: Export to Markdown or JSON with metadata and token usage\n\n### Comprehensive Provider Support\n\nMCP CLI supports all providers and models from CHUK-LLM, including cutting-edge reasoning models:\n\n| Provider | Key Models | Special Features |\n|----------|------------|------------------|\n| **Ollama** (Default) | 🧠 gpt-oss, llama3.3, llama3.2, qwen3, qwen2.5-coder, deepseek-coder, granite3.3, mistral, gemma3, phi3, codellama | Local reasoning models, privacy-focused, no API key required |\n| **OpenAI** | 🚀 GPT-5 family (gpt-5, gpt-5-mini, gpt-5-nano), GPT-4o family, O3 series (o3, o3-mini) | Advanced reasoning, function calling, vision |\n| **Anthropic** | 🧠 Claude 4.5 family (claude-4-5-opus, claude-4-5-sonnet), Claude 3.5 Sonnet | Enhanced reasoning, long context |\n| **Azure OpenAI** 🏢 | Enterprise GPT-5, GPT-4 models | Private endpoints, compliance, audit logs |\n| **Google Gemini** | Gemini 2.0 Flash, Gemini 1.5 Pro | Multimodal, fast inference |\n| **Groq** ⚡ | Llama 3.1 models, Mixtral | Ultra-fast inference (500+ tokens\u002Fsec) |\n| **Perplexity** 🌐 | Sonar models | Real-time web search with citations |\n| **IBM watsonx** 🏢 | Granite, Llama models | Enterprise compliance |\n| **Mistral AI** 🇪🇺 | Mistral Large, Medium | European, efficient models |\n\n### Robust Tool System (Powered by CHUK Tool Processor v0.22+)\n- **Automatic Discovery**: Server-provided tools are automatically detected and catalogued\n- **Provider Adaptation**: Tool names are automatically sanitized for provider compatibility\n- **Production-Grade Execution**: Middleware layers with timeouts, retries, exponential backoff, caching, and circuit breakers\n- **Multiple Execution Strategies**: In-process (fast), isolated subprocess (safe), or remote via MCP\n- **Concurrent Execution**: Multiple tools can run simultaneously with proper coordination\n- **Rich Progress Display**: Real-time progress indicators and execution timing\n- **Tool History**: Complete audit trail of all tool executions\n- **Middleware**: Retry with exponential backoff, circuit breakers, and rate limiting via CTP\n- **Streaming Tool Calls**: Support for tools that return streaming data\n\n### MCP Apps (Interactive UIs)\n- **Browser-based UIs**: MCP servers can serve interactive HTML applications that render in your browser\n- **Automatic Detection**: Tools with `_meta.ui` annotations automatically launch browser apps on tool call\n- **Sandboxed Execution**: Apps run in secure sandboxed iframes with Content Security Policy protection\n- **WebSocket Bridge**: Real-time JSON-RPC bridge between browser apps and MCP tool servers\n- **Session Persistence**: Message queuing during disconnects, automatic reconnection, deferred tool result delivery\n- **structuredContent Support**: Full MCP spec compliance including structured content extraction and forwarding\n\n### Execution Plans (Powered by chuk-ai-planner)\n- **Plan Creation**: Generate execution plans from natural language descriptions using LLM-based plan agents\n- **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\n- **DAG Execution**: Plans are directed acyclic graphs — independent steps run in parallel batches, dependent steps wait\n- **Variable Resolution**: Step outputs bind to variables (`result_variable`), referenced by later steps as `${var}` or `${var.field}`\n- **Dry-Run Mode**: Trace what a plan would do without executing any tools — safe for production\n- **Checkpointing**: Execution state saved after each batch; resume interrupted plans without re-running completed steps\n- **Guard Integration**: Plans share budget and per-tool limits with the conversation — no bypass\n- **Re-planning**: On step failure, optionally invoke the LLM to generate a revised plan for remaining work\n- **DAG Visualization**: ASCII rendering shows dependency structure, batch grouping, and parallel markers\n- **Persistence**: Plans stored as JSON at `~\u002F.mcp-cli\u002Fplans\u002F`\n\n### Advanced Configuration Management\n- **Environment Integration**: API keys and settings via environment variables\n- **File-based Config**: YAML and JSON configuration files\n- **User Preferences**: Persistent settings for active providers and models\n- **Validation & Diagnostics**: Built-in provider health checks and configuration validation\n\n### Enhanced User Experience\n- **Cross-Platform Support**: Windows, macOS, and Linux with platform-specific optimizations via chuk-term\n- **Rich Console Output**: Powered by chuk-term with 8 built-in themes (default, dark, light, minimal, terminal, monokai, dracula, solarized)\n- **Advanced Terminal Management**: Cross-platform terminal operations including clearing, resizing, color detection, and cursor control\n- **Interactive UI Components**: User input handling through chuk-term's prompt system (ask, confirm, select_from_list, select_multiple)\n- **Command Completion**: Context-aware tab completion for all interfaces\n- **Comprehensive Help**: Detailed help system with examples and usage patterns\n- **Graceful Error Handling**: User-friendly error messages with troubleshooting hints\n\n## 📚 Documentation\n\nComprehensive documentation is available in the `docs\u002F` directory:\n\n### Project\n- **[Architecture](architecture.md)** - 15 design principles, module layout, and coding conventions\n- **[Roadmap](roadmap.md)** - Vision, completed tiers (1-5), and planned tiers (6-12: plans, traces, skills, scheduling, multi-agent, remote sessions)\n\n### Core Documentation\n- **[Commands System](docs\u002FCOMMANDS.md)** - Complete guide to the unified command system, patterns, and usage across all modes\n- **[Token Management](docs\u002FTOKEN_MANAGEMENT.md)** - Comprehensive token management for providers and servers including OAuth, bearer tokens, and API keys\n\n### Specialized Documentation\n- **[Execution Plans](docs\u002FPLANNING.md)** - Plan creation, parallel execution, variable resolution, checkpointing, guards, and re-planning\n- **[Dashboard](docs\u002FDASHBOARD.md)** - Real-time browser UI with agent terminal, activity stream, and file uploads\n- **[Attachments](docs\u002FATTACHMENTS.md)** - Multi-modal file attachments: images, text, audio, and browser upload\n- **[MCP Apps](docs\u002FMCP_APPS.md)** - Interactive browser UIs served by MCP servers (SEP-1865)\n- **[OAuth Authentication](docs\u002FOAUTH.md)** - OAuth flows, storage backends, and MCP server integration\n- **[Streaming Integration](docs\u002FSTREAMING.md)** - Real-time response streaming architecture\n- **[Package Management](docs\u002FPACKAGE_MANAGEMENT.md)** - Dependency organization and feature groups\n\n### UI Documentation\n- **[Themes](docs\u002Fui\u002Fthemes.md)** - Theme system and customization\n- **[Output System](docs\u002Fui\u002Foutput.md)** - Rich console output and formatting\n- **[Terminal Management](docs\u002Fui\u002Fterminal.md)** - Cross-platform terminal operations\n\n### Testing Documentation\n- **[Unit Testing](docs\u002Ftesting\u002FUNIT_TESTING.md)** - Test structure and patterns\n- **[Test Coverage](docs\u002Ftesting\u002FTEST_COVERAGE.md)** - Coverage requirements and reporting\n\n## 📋 Prerequisites\n\n- **Python 3.11 or higher**\n- **For Local Operation (Default)**:\n  - Ollama: Install from [ollama.ai](https:\u002F\u002Follama.ai)\n  - Pull the default reasoning model: `ollama pull gpt-oss`\n- **For Cloud Providers** (Optional):\n  - OpenAI: `OPENAI_API_KEY` environment variable (for GPT-5, GPT-4, O3 models)\n  - Anthropic: `ANTHROPIC_API_KEY` environment variable (for Claude 4.5, Claude 3.5)\n  - Azure: `AZURE_OPENAI_API_KEY` and `AZURE_OPENAI_ENDPOINT` (for enterprise GPT-5)\n  - Google: `GEMINI_API_KEY` (for Gemini models)\n  - Groq: `GROQ_API_KEY` (for fast Llama models)\n  - Custom providers: Provider-specific configuration\n- **MCP Servers**: Server configuration file (default: `server_config.json`)\n\n## 🚀 Installation\n\n### Quick Start with Ollama (Default)\n\n1. **Install Ollama** (if not already installed):\n```bash\n# macOS\u002FLinux\ncurl -fsSL https:\u002F\u002Follama.ai\u002Finstall.sh | sh\n\n# Or visit https:\u002F\u002Follama.ai for other installation methods\n```\n\n2. **Pull the default reasoning model**:\n```bash\nollama pull gpt-oss  # Open-source reasoning model with thinking visibility\n```\n\n3. **Install and run MCP CLI**:\n```bash\n# Using uvx (recommended)\nuvx mcp-cli --help\n\n# Or install from source\ngit clone https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fmcp-cli\ncd mcp-cli\npip install -e \".\"\nmcp-cli --help\n\n# Optional: Enable MCP Apps (interactive browser UIs)\npip install -e \".[apps]\"\n```\n\n### Using Different Models\n\n```bash\n# === LOCAL MODELS (No API Key Required) ===\n\n# Use default reasoning model (gpt-oss)\nmcp-cli --server sqlite\n\n# Use other Ollama models\nmcp-cli --model llama3.3              # Latest Llama\nmcp-cli --model qwen2.5-coder         # Coding-focused\nmcp-cli --model deepseek-coder        # Another coding model\nmcp-cli --model granite3.3            # IBM Granite\n\n# === CLOUD PROVIDERS (API Keys Required) ===\n\n# GPT-5 Family (requires OpenAI API key)\nmcp-cli --provider openai --model gpt-5          # Full GPT-5 with reasoning\nmcp-cli --provider openai --model gpt-5-mini     # Efficient GPT-5 variant\nmcp-cli --provider openai --model gpt-5-nano     # Ultra-lightweight GPT-5\n\n# GPT-4 Family\nmcp-cli --provider openai --model gpt-4o         # GPT-4 Optimized\nmcp-cli --provider openai --model gpt-4o-mini    # Smaller GPT-4\n\n# O3 Reasoning Models\nmcp-cli --provider openai --model o3             # O3 reasoning\nmcp-cli --provider openai --model o3-mini        # Efficient O3\n\n# Claude 4.5 Family (requires Anthropic API key)\nmcp-cli --provider anthropic --model claude-4-5-opus    # Most advanced Claude\nmcp-cli --provider anthropic --model claude-4-5-sonnet  # Balanced Claude 4.5\nmcp-cli --provider anthropic --model claude-3-5-sonnet  # Claude 3.5\n\n# Enterprise Azure (requires Azure configuration)\nmcp-cli --provider azure_openai --model gpt-5    # Enterprise GPT-5\n\n# Other Providers\nmcp-cli --provider gemini --model gemini-2.0-flash      # Google Gemini\nmcp-cli --provider groq --model llama-3.1-70b          # Fast Llama via Groq\n```\n\n## 🧰 Global Configuration\n\n### Default Configuration\n\nMCP CLI defaults to:\n- **Provider**: `ollama` (local, no API key required)\n- **Model**: `gpt-oss` (open-source reasoning model with thinking visibility)\n\n### Command-line Arguments\n\nGlobal options available for all modes and commands:\n\n- `--server`: Specify server(s) to connect to (comma-separated)\n- `--config-file`: Path to server configuration file (default: `server_config.json`)\n- `--provider`: LLM provider (default: `ollama`)\n- `--model`: Specific model to use (default: `gpt-oss` for Ollama)\n- `--disable-filesystem`: Disable filesystem access (default: enabled)\n- `--api-base`: Override API endpoint URL\n- `--api-key`: Override API key (not needed for Ollama)\n- `--token-backend`: Override token storage backend (`auto`, `keychain`, `windows`, `secretservice`, `encrypted`, `vault`)\n- `--verbose`: Enable detailed logging\n- `--quiet`: Suppress non-essential output\n- `--log-file`: Write debug logs to a rotating file (secrets auto-redacted)\n- `--vm`: [Experimental] Enable AI virtual memory for context management\n- `--vm-budget`: Token budget for conversation events in VM mode (default: 128000, on top of system prompt)\n- `--vm-mode`: VM mode — `passive` (default), `relaxed`, or `strict`\n- `--dashboard`: Launch a real-time browser dashboard UI alongside chat mode\n- `--attach`: Attach files to the first message (repeatable: `--attach img.png --attach code.py`)\n- `--plan-tools`: Enable model-driven planning — the LLM autonomously creates and executes multi-step plans\n- `--no-tools`: Disable MCP tool calling entirely — chat directly with the LLM without connecting to any MCP servers\n\n### Environment Variables\n\n```bash\n# Override defaults\nexport LLM_PROVIDER=ollama              # Default provider (already the default)\nexport LLM_MODEL=gpt-oss                # Default model (already the default)\n\n# For cloud providers (optional)\nexport OPENAI_API_KEY=sk-...           # For GPT-5, GPT-4, O3 models\nexport ANTHROPIC_API_KEY=sk-ant-...    # For Claude 4.5, Claude 3.5\nexport AZURE_OPENAI_API_KEY=sk-...     # For enterprise GPT-5\nexport AZURE_OPENAI_ENDPOINT=https:\u002F\u002F...\nexport GEMINI_API_KEY=...              # For Gemini models\nexport GROQ_API_KEY=...                # For Groq fast inference\n\n# Tool configuration\nexport MCP_TOOL_TIMEOUT=120            # Tool execution timeout (seconds)\n```\n\n## 🌐 Available Modes\n\n### 1. Chat Mode (Default)\n\nProvides a natural language interface with streaming responses and automatic tool usage:\n\n```bash\n# Default mode with Ollama\u002Fgpt-oss reasoning model (no API key needed)\nmcp-cli --server sqlite\n\n# See the AI's thinking process with reasoning models\nmcp-cli --server sqlite --model gpt-oss     # Open-source reasoning\nmcp-cli --server sqlite --provider openai --model gpt-5  # GPT-5 reasoning\nmcp-cli --server sqlite --provider anthropic --model claude-4-5-opus  # Claude 4.5 reasoning\n\n# Use different local models\nmcp-cli --server sqlite --model llama3.3\nmcp-cli --server sqlite --model qwen2.5-coder\n\n# Switch to cloud providers (requires API keys)\nmcp-cli chat --server sqlite --provider openai --model gpt-5\nmcp-cli chat --server sqlite --provider anthropic --model claude-4-5-sonnet\n\n# Launch with real-time browser dashboard\nmcp-cli --server sqlite --dashboard\n\n# Attach files to the first message\nmcp-cli --server sqlite --attach image.png --attach data.csv\n```\n\n### 2. Interactive Mode\n\nCommand-driven shell interface for direct server operations:\n\n```bash\nmcp-cli interactive --server sqlite\n\n# With specific models\nmcp-cli interactive --server sqlite --model gpt-oss       # Local reasoning\nmcp-cli interactive --server sqlite --provider openai --model gpt-5  # Cloud GPT-5\n```\n\n### 3. Command Mode\n\nUnix-friendly interface for automation and scripting:\n\n```bash\n# Process text with reasoning models\nmcp-cli cmd --server sqlite --model gpt-oss --prompt \"Think through this step by step\" --input data.txt\n\n# Use GPT-5 for complex reasoning\nmcp-cli cmd --server sqlite --provider openai --model gpt-5 --prompt \"Analyze this data\" --input data.txt\n\n# Execute tools directly\nmcp-cli cmd --server sqlite --tool list_tables --output tables.json\n\n# Pipeline-friendly processing\necho \"SELECT * FROM users LIMIT 5\" | mcp-cli cmd --server sqlite --tool read_query --input -\n```\n\n### 4. Direct Commands\n\nExecute individual commands without entering interactive mode:\n\n```bash\n# List available tools\nmcp-cli tools --server sqlite\n\n# Show provider configuration\nmcp-cli provider list\n\n# Show available models for current provider\nmcp-cli models\n\n# Show models for specific provider\nmcp-cli models openai    # Shows GPT-5, GPT-4, O3 models\nmcp-cli models anthropic # Shows Claude 4.5, Claude 3.5 models\nmcp-cli models ollama    # Shows gpt-oss, llama3.3, etc.\n\n# Ping servers\nmcp-cli ping --server sqlite\n\n# List resources\nmcp-cli resources --server sqlite\n\n# UI Theme Management\nmcp-cli theme                     # Show current theme and list available\nmcp-cli theme dark                # Switch to dark theme\nmcp-cli theme --select            # Interactive theme selector\nmcp-cli theme --list              # List all available themes\n\n# Token Storage Management\nmcp-cli token backends            # Show available storage backends\nmcp-cli --token-backend encrypted token list  # Use specific backend\n```\n\n## 🌐 MCP Apps (Interactive Browser UIs)\n\nMCP Apps allow tool servers to provide interactive HTML UIs that render in your browser. When a tool has a `_meta.ui` annotation pointing to a UI resource, mcp-cli automatically launches a local web server and opens the app in your browser.\n\n### Prerequisites\n\n```bash\n# Install the apps extra (adds websockets dependency)\npip install \"mcp-cli[apps]\"\n```\n\n### How It Works\n\n1. Connect to an MCP server that provides app-enabled tools\n2. Call a tool that has `_meta.ui` metadata (e.g., `show_chart`, `show_table`)\n3. mcp-cli automatically fetches the UI resource, starts a local server, and opens your browser\n4. The app receives tool results in real-time via WebSocket\n\n### Example\n\n```bash\n# Connect to a server with app-enabled tools\nmcp-cli --server view_demo\n\n# In chat, ask for something visual:\n> Show me the sales data as a chart\n# Browser opens automatically with an interactive chart\n\n# The \u002Ftools command shows which tools have app UIs (APP column)\n> \u002Ftools\n```\n\n### Architecture\n\n- **Host page** serves a sandboxed iframe with the app HTML\n- **WebSocket bridge** proxies JSON-RPC between the browser and MCP servers\n- **Security**: Iframe sandbox, CSP protection, XSS prevention, URL scheme validation\n- **Reliability**: Message queuing during disconnects, exponential backoff reconnection, deferred tool result delivery\n\nSee [MCP Apps Documentation](docs\u002FMCP_APPS.md) for the full guide.\n\n## 🤖 Using Chat Mode\n\nChat mode provides the most advanced interface with streaming responses and intelligent tool usage.\n\n### Starting Chat Mode\n\n```bash\n# Simple startup with default reasoning model (gpt-oss)\nmcp-cli --server sqlite\n\n# Multiple servers\nmcp-cli --server sqlite,filesystem\n\n# With advanced reasoning models\nmcp-cli --server sqlite --provider openai --model gpt-5\nmcp-cli --server sqlite --provider anthropic --model claude-4-5-opus\n```\n\n### Chat Commands (Slash Commands)\n\n#### Provider & Model Management\n```bash\n\u002Fprovider                           # Show current configuration (default: ollama)\n\u002Fprovider list                      # List all providers\n\u002Fprovider config                    # Show detailed configuration\n\u002Fprovider diagnostic               # Test provider connectivity\n\u002Fprovider set ollama api_base http:\u002F\u002Flocalhost:11434  # Configure Ollama endpoint\n\u002Fprovider openai                   # Switch to OpenAI (requires API key)\n\u002Fprovider anthropic                # Switch to Anthropic (requires API key)\n\u002Fprovider openai gpt-5             # Switch to OpenAI GPT-5\n\n# Custom Provider Management\n\u002Fprovider custom                   # List custom providers\n\u002Fprovider add localai http:\u002F\u002Flocalhost:8080\u002Fv1 gpt-4  # Add custom provider\n\u002Fprovider remove localai           # Remove custom provider\n\n\u002Fmodel                             # Show current model (default: gpt-oss)\n\u002Fmodel llama3.3                    # Switch to different Ollama model\n\u002Fmodel gpt-5                       # Switch to GPT-5 (if using OpenAI)\n\u002Fmodel claude-4-5-opus             # Switch to Claude 4.5 (if using Anthropic)\n\u002Fmodels                            # List available models for current provider\n```\n\n#### Tool Management\n```bash\n\u002Ftools                             # List available tools\n\u002Ftools --all                       # Show detailed tool information\n\u002Ftools --raw                       # Show raw JSON definitions\n\u002Ftools call                        # Interactive tool execution\n\n\u002Ftoolhistory                       # Show tool execution history\n\u002Fth -n 5                          # Last 5 tool calls\n\u002Fth 3                             # Details for call #3\n\u002Fth --json                        # Full history as JSON\n```\n\n#### Server Management (Runtime Configuration)\n```bash\n\u002Fserver                            # List all configured servers\n\u002Fserver list                       # List servers (alias)\n\u002Fserver list all                   # Include disabled servers\n\n# Add servers at runtime (persists in ~\u002F.mcp-cli\u002Fpreferences.json)\n\u002Fserver add \u003Cname> stdio \u003Ccommand> [args...]\n\u002Fserver add sqlite stdio uvx mcp-server-sqlite --db-path test.db\n\u002Fserver add playwright stdio npx @playwright\u002Fmcp@latest\n\u002Fserver add time stdio uvx mcp-server-time\n\u002Fserver add fs stdio npx @modelcontextprotocol\u002Fserver-filesystem \u002Fpath\u002Fto\u002Fdir\n\n# HTTP\u002FSSE server examples with authentication\n\u002Fserver add github --transport http --header \"Authorization: Bearer ghp_token\" -- https:\u002F\u002Fapi.github.com\u002Fmcp\n\u002Fserver add myapi --transport http --env API_KEY=secret -- https:\u002F\u002Fapi.example.com\u002Fmcp\n\u002Fserver add events --transport sse -- https:\u002F\u002Fevents.example.com\u002Fsse\n\n# Manage server state\n\u002Fserver enable \u003Cname>              # Enable a disabled server\n\u002Fserver disable \u003Cname>             # Disable without removing\n\u002Fserver remove \u003Cname>              # Remove user-added server\n\u002Fserver ping \u003Cname>                # Test server connectivity\n\n# Server details\n\u002Fserver \u003Cname>                     # Show server configuration details\n```\n\n**Note**: Servers added via `\u002Fserver add` are stored in `~\u002F.mcp-cli\u002Fpreferences.json` and persist across sessions. Project servers remain in `server_config.json`.\n\n#### Multi-Modal Attachments\n```bash\n\u002Fattach image.png                  # Stage an image for the next message\n\u002Fattach code.py                    # Stage a text file\n\u002Fattach list                       # Show currently staged files\n\u002Fattach clear                      # Clear staged files\n\u002Ffile data.csv                     # Alias for \u002Fattach\n\u002Fimage screenshot.heic             # Alias for \u002Fattach\n\n# Inline file references (in any message)\n@file:screenshot.png describe what you see\n@file:data.csv summarize this data\n\n# Image URLs are auto-detected\nhttps:\u002F\u002Fexample.com\u002Fphoto.jpg what is in this image?\n```\n\n#### Conversation Management\n```bash\n\u002Fconversation                      # Show conversation history\n\u002Fch -n 10                         # Last 10 messages\n\u002Fch 5                             # Details for message #5\n\u002Fch --json                        # Full history as JSON\n\n\u002Fsave conversation.json            # Save conversation to file\n\u002Fcompact                          # Summarize conversation\n\u002Fclear                            # Clear conversation history\n\u002Fcls                              # Clear screen only\n```\n\n#### UI Customization\n```bash\n\u002Ftheme                            # Interactive theme selector with preview\n\u002Ftheme dark                       # Switch to dark theme\n\u002Ftheme monokai                    # Switch to monokai theme\n\n# Available themes: default, dark, light, minimal, terminal, monokai, dracula, solarized\n# Themes are persisted across sessions\n```\n\n#### Token Management\n```bash\n\u002Ftoken                            # List all stored tokens\n\u002Ftoken list                       # List all tokens explicitly\n\u002Ftoken set \u003Cname>                 # Store a bearer token\n\u002Ftoken get \u003Cname>                 # Get token details\n\u002Ftoken delete \u003Cname>              # Delete a token\n\u002Ftoken clear                      # Clear all tokens (with confirmation)\n\u002Ftoken backends                   # Show available storage backends\n\n# Examples\n\u002Ftoken set my-api                 # Prompts for token value (secure)\n\u002Ftoken get notion --oauth         # Get OAuth token for Notion server\n\u002Ftoken list --api-keys            # List only provider API keys\n```\n\n**Token Storage Backends:**\nMCP CLI supports multiple secure token storage backends:\n- **Keychain** (macOS) - Uses macOS Keychain (default on macOS)\n- **Windows Credential Manager** - Native Windows storage (default on Windows)\n- **Secret Service** - Linux desktop keyring (GNOME\u002FKDE)\n- **Encrypted File** - AES-256 encrypted local files (cross-platform fallback)\n- **HashiCorp Vault** - Enterprise secret management\n\nOverride the default backend with `--token-backend`:\n```bash\n# Use encrypted file storage instead of keychain\nmcp-cli --token-backend encrypted token list\n\n# Use vault for enterprise environments\nmcp-cli --token-backend vault token list\n```\n\nSee [Token Management Guide](docs\u002FTOKEN_MANAGEMENT.md) for comprehensive documentation.\n\n#### Session Control\n```bash\n\u002Fverbose                          # Toggle verbose\u002Fcompact display (Default: Enabled)\n\u002Fconfirm                          # Toggle tool call confirmation (Default: Enabled)\n\u002Finterrupt                        # Stop running operations\n\u002Fserver                           # Manage MCP servers (see Server Management above)\n\u002Fhelp                            # Show all commands\n\u002Fhelp tools                       # Help for specific command\n\u002Fexit                            # Exit chat mode\n```\n\n**For complete command documentation**, see [Commands System Guide](docs\u002FCOMMANDS.md).\n\n### Chat Features\n\n#### Streaming Responses with Reasoning Visibility\n- **🧠 Reasoning Models**: See the AI's thinking process with gpt-oss, GPT-5, Claude 4\n- **Real-time Generation**: Watch text appear token by token\n- **Performance Metrics**: Words\u002Fsecond, response time\n- **Graceful Interruption**: Ctrl+C to stop streaming\n- **Progressive Rendering**: Markdown formatted as it streams\n\n#### Tool Execution\n- Automatic tool discovery and usage\n- Concurrent execution with progress indicators\n- Verbose and compact display modes\n- Complete execution history and timing\n\n#### Multi-Modal Attachments\n- Attach images, text files, and audio to any message\n- `\u002Fattach` command with staging, list, and clear (aliases: `\u002Ffile`, `\u002Fimage`)\n- Inline `@file:path` references in any message\n- `--attach` CLI flag for first-message attachments\n- Browser \"+\" button with drag-and-drop and clipboard paste (with `--dashboard`)\n- Dashboard renders thumbnails, text previews, and audio players\n\n#### Provider Integration\n- Seamless switching between providers\n- Model-specific optimizations\n- API key and endpoint management\n- Health monitoring and diagnostics\n\n## 🖥️ Using Interactive Mode\n\nInteractive mode provides a command shell for direct server interaction.\n\n### Starting Interactive Mode\n\n```bash\nmcp-cli interactive --server sqlite\n```\n\n### Interactive Commands\n\n```bash\nhelp                              # Show available commands\nexit                              # Exit interactive mode\nclear                             # Clear terminal\n\n# Provider management\nprovider                          # Show current provider\nprovider list                     # List providers\nprovider anthropic                # Switch provider\nprovider openai gpt-5             # Switch to GPT-5\n\n# Model management\nmodel                             # Show current model\nmodel gpt-oss                     # Switch to reasoning model\nmodel claude-4-5-opus             # Switch to Claude 4.5\nmodels                            # List available models\n\n# Tool operations\ntools                             # List tools\ntools --all                       # Detailed tool info\ntools call                        # Interactive tool execution\n\n# Server operations\nservers                           # List servers\nping                              # Ping all servers\nresources                         # List resources\nprompts                           # List prompts\n```\n\n## 📄 Using Command Mode\n\nCommand mode provides Unix-friendly automation capabilities.\n\n### Command Mode Options\n\n```bash\n--input FILE                      # Input file (- for stdin)\n--output FILE                     # Output file (- for stdout)\n--prompt TEXT                     # Prompt template\n--tool TOOL                       # Execute specific tool\n--tool-args JSON                  # Tool arguments as JSON\n--system-prompt TEXT              # Custom system prompt\n--raw                             # Raw output without formatting\n--single-turn                     # Disable multi-turn conversation\n--max-turns N                     # Maximum conversation turns\n```\n\n### Examples\n\n```bash\n# Text processing with reasoning models\necho \"Analyze this data\" | mcp-cli cmd --server sqlite --model gpt-oss --input - --output analysis.txt\n\n# Use GPT-5 for complex analysis\nmcp-cli cmd --server sqlite --provider openai --model gpt-5 --prompt \"Provide strategic analysis\" --input report.txt\n\n# Tool execution\nmcp-cli cmd --server sqlite --tool list_tables --raw\n\n# Complex queries\nmcp-cli cmd --server sqlite --tool read_query --tool-args '{\"query\": \"SELECT COUNT(*) FROM users\"}'\n\n# Batch processing with GNU Parallel\nls *.txt | parallel mcp-cli cmd --server sqlite --input {} --output {}.summary --prompt \"Summarize: {{input}}\"\n```\n\n## 🔧 Provider Configuration\n\n### Ollama Configuration (Default)\n\nOllama runs locally by default on `http:\u002F\u002Flocalhost:11434`. MCP CLI v0.11.1+ with CHUK-LLM v0.16+ includes **llama.cpp integration** that automatically discovers and reuses Ollama's downloaded models for 1.53x faster inference (311 vs 204 tokens\u002Fsec) without re-downloading.\n\nTo use reasoning and other models:\n\n```bash\n# Pull reasoning and other models for Ollama\nollama pull gpt-oss          # Default reasoning model\nollama pull llama3.3         # Latest Llama\nollama pull llama3.2         # Llama 3.2\nollama pull qwen3            # Qwen 3\nollama pull qwen2.5-coder    # Coding-focused\nollama pull deepseek-coder   # DeepSeek coder\nollama pull granite3.3       # IBM Granite\nollama pull mistral          # Mistral\nollama pull gemma3           # Google Gemma\nollama pull phi3             # Microsoft Phi\nollama pull codellama        # Code Llama\n\n# List available Ollama models\nollama list\n\n# Configure remote Ollama server\nmcp-cli provider set ollama api_base http:\u002F\u002Fremote-server:11434\n```\n\n### Cloud Provider Configuration\n\nTo use cloud providers with advanced models, configure API keys:\n\n```bash\n# Configure OpenAI (for GPT-5, GPT-4, O3 models)\nmcp-cli provider set openai api_key sk-your-key-here\n\n# Configure Anthropic (for Claude 4.5, Claude 3.5)\nmcp-cli provider set anthropic api_key sk-ant-your-key-here\n\n# Configure Azure OpenAI (for enterprise GPT-5)\nmcp-cli provider set azure_openai api_key sk-your-key-here\nmcp-cli provider set azure_openai api_base https:\u002F\u002Fyour-resource.openai.azure.com\n\n# Configure other providers\nmcp-cli provider set gemini api_key your-gemini-key\nmcp-cli provider set groq api_key your-groq-key\n\n# Test configuration\nmcp-cli provider diagnostic openai\nmcp-cli provider diagnostic anthropic\n```\n\n### Custom OpenAI-Compatible Providers\n\nMCP CLI supports adding custom OpenAI-compatible providers (LocalAI, custom proxies, etc.):\n\n```bash\n# Add a custom provider (persisted across sessions)\nmcp-cli provider add localai http:\u002F\u002Flocalhost:8080\u002Fv1 gpt-4 gpt-3.5-turbo\nmcp-cli provider add myproxy https:\u002F\u002Fproxy.example.com\u002Fv1 custom-model-1 custom-model-2\n\n# Set API key via environment variable (never stored in config)\nexport LOCALAI_API_KEY=your-api-key\nexport MYPROXY_API_KEY=your-api-key\n\n# List custom providers\nmcp-cli provider custom\n\n# Use custom provider\nmcp-cli --provider localai --server sqlite\nmcp-cli --provider myproxy --model custom-model-1 --server sqlite\n\n# Remove custom provider\nmcp-cli provider remove localai\n\n# Runtime provider (session-only, not persisted)\nmcp-cli --provider temp-ai --api-base https:\u002F\u002Fapi.temp.com\u002Fv1 --api-key test-key --server sqlite\n```\n\n**Security Note**: API keys can be stored securely in OS-native keychains (macOS Keychain, Windows Credential Manager, Linux Secret Service) or HashiCorp Vault using the token management system. Alternatively, use environment variables following the pattern `{PROVIDER_NAME}_API_KEY` or pass via `--api-key` for session-only use. See [Token Management](docs\u002FTOKEN_MANAGEMENT.md) for details.\n\n### Manual Configuration\n\nThe `chuk_llm` library configuration in `~\u002F.chuk_llm\u002Fconfig.yaml`:\n\n```yaml\nollama:\n  api_base: http:\u002F\u002Flocalhost:11434\n  default_model: gpt-oss\n\nopenai:\n  api_base: https:\u002F\u002Fapi.openai.com\u002Fv1\n  default_model: gpt-5\n\nanthropic:\n  api_base: https:\u002F\u002Fapi.anthropic.com\n  default_model: claude-4-5-opus\n\nazure_openai:\n  api_base: https:\u002F\u002Fyour-resource.openai.azure.com\n  default_model: gpt-5\n\ngemini:\n  api_base: https:\u002F\u002Fgenerativelanguage.googleapis.com\n  default_model: gemini-2.0-flash\n\ngroq:\n  api_base: https:\u002F\u002Fapi.groq.com\n  default_model: llama-3.1-70b\n```\n\nAPI keys can be provided via:\n1. **Secure token storage** (recommended) - Stored in OS keychain\u002FVault, see [Token Management](docs\u002FTOKEN_MANAGEMENT.md)\n2. **Environment variables** - Export in your shell or add to `~\u002F.chuk_llm\u002F.env`:\n\n```bash\nOPENAI_API_KEY=sk-your-key-here\nANTHROPIC_API_KEY=sk-ant-your-key-here\nAZURE_OPENAI_API_KEY=sk-your-azure-key-here\nGEMINI_API_KEY=your-gemini-key\nGROQ_API_KEY=your-groq-key\n```\n\n3. **Command-line** - Pass `--api-key` for session-only use (not persisted)\n\n## 📂 Server Configuration\n\nMCP CLI supports two types of server configurations:\n\n1. **Project Servers** (`server_config.json`): Shared project-level configurations\n2. **User Servers** (`~\u002F.mcp-cli\u002Fpreferences.json`): Personal runtime-added servers that persist across sessions\n\n### Configuration File Discovery\n\nMCP CLI searches for `server_config.json` in the following priority order:\n\n1. **Explicit path** via `--config-file` option:\n   ```bash\n   mcp-cli --config-file \u002Fpath\u002Fto\u002Fcustom-config.json\n   ```\n\n2. **Current directory** - Automatically detected when running from a project directory:\n   ```bash\n   cd \u002Fpath\u002Fto\u002Fmy-project\n   mcp-cli --server sqlite    # Uses .\u002Fserver_config.json if it exists\n   ```\n\n3. **Bundled default** - When running via `uvx` or from any directory without a local config:\n   ```bash\n   uvx mcp-cli --server cloudflare_workers    # Uses packaged server_config.json\n   ```\n\nThis means you can:\n- **Override per-project**: Place a `server_config.json` in your project directory with project-specific server configurations\n- **Use defaults globally**: Run `uvx mcp-cli` from anywhere and get the bundled default servers\n- **Customize explicitly**: Use `--config-file` to specify any configuration file location\n\n### Bundled Default Servers\n\nMCP CLI v0.11.1+ comes with an expanded set of pre-configured servers in the bundled `server_config.json`:\n\n| Server | Type | Description | Configuration |\n|--------|------|-------------|---------------|\n| **sqlite** | STDIO | SQLite database operations | `uvx mcp-server-sqlite --db-path test.db` |\n| **echo** | STDIO | Echo server for testing | `uvx chuk-mcp-echo stdio` |\n| **math** | STDIO | Mathematical computations | `uvx chuk-mcp-math-server` |\n| **playwright** | STDIO | Browser automation | `npx @playwright\u002Fmcp@latest` |\n| **brave_search** | STDIO | Web search via Brave API | Requires `BRAVE_API_KEY` token |\n| **notion** | HTTP | Notion workspace integration | `https:\u002F\u002Fmcp.notion.com\u002Fmcp` (OAuth) |\n| **cloudflare_workers** | HTTP | Cloudflare Workers bindings | `https:\u002F\u002Fbindings.mcp.cloudflare.com\u002Fmcp` (OAuth) |\n| **monday** | HTTP | Monday.com integration | `https:\u002F\u002Fmcp.monday.com\u002Fmcp` (OAuth) |\n| **linkedin** | HTTP | LinkedIn integration | `https:\u002F\u002Flinkedin.chukai.io\u002Fmcp` |\n| **weather** | HTTP | Weather data service | `https:\u002F\u002Fweather.chukai.io\u002Fmcp` |\n\n**Note**: HTTP servers and API-based servers require authentication. Use the [Token Management](docs\u002FTOKEN_MANAGEMENT.md) system to configure access tokens.\n\nTo use these servers:\n```bash\n# Use bundled servers from anywhere\nuvx mcp-cli --server sqlite\nuvx mcp-cli --server echo\nuvx mcp-cli --server math\nuvx mcp-cli --server playwright\n\n# API-based servers require tokens\nmcp-cli token set brave_search --type bearer\nuvx mcp-cli --server brave_search\n\n# HTTP\u002FOAuth servers require OAuth authentication\nuvx mcp-cli token set notion --oauth\nuvx mcp-cli --server notion\n\n# Use multiple servers simultaneously\nuvx mcp-cli --server sqlite,math,playwright\n```\n\n### Project Configuration\n\nCreate a `server_config.json` file with your MCP server configurations:\n\n```json\n{\n  \"mcpServers\": {\n    \"sqlite\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"mcp_server.sqlite_server\"],\n      \"env\": {\n        \"DATABASE_PATH\": \"database.db\"\n      }\n    },\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol\u002Fserver-filesystem\", \"\u002Fpath\u002Fto\u002Fallowed\u002Ffiles\"],\n      \"env\": {}\n    },\n    \"brave-search\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@brave\u002Fbrave-search-mcp-server\"],\n      \"env\": {\n        \"BRAVE_API_KEY\": \"${TOKEN:bearer:brave_search}\"\n      }\n    },\n    \"notion\": {\n      \"url\": \"https:\u002F\u002Fmcp.notion.com\u002Fmcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer ${TOKEN:bearer:notion}\"\n      }\n    }\n  }\n}\n```\n\n### Secure Token Replacement\n\nMCP CLI supports automatic token replacement from secure storage using the `${TOKEN:namespace:name}` syntax:\n\n**Syntax**: `${TOKEN:\u003Cnamespace>:\u003Ctoken-name>}`\n\n**Examples**:\n```json\n{\n  \"mcpServers\": {\n    \"brave-search\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@brave\u002Fbrave-search-mcp-server\"],\n      \"env\": {\n        \"BRAVE_API_KEY\": \"${TOKEN:bearer:brave_search}\"\n      }\n    },\n    \"api-server\": {\n      \"url\": \"https:\u002F\u002Fapi.example.com\u002Fmcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer ${TOKEN:bearer:my_api}\",\n        \"X-API-Key\": \"${TOKEN:api-key:my_service}\"\n      }\n    }\n  }\n}\n```\n\n**Token Storage**:\n```bash\n# Store tokens securely (never in config files!)\nmcp-cli token set brave_search --type bearer\n# Enter token value when prompted (hidden input)\n\nmcp-cli token set my_api --type bearer --value \"your-token-here\"\n\n# Tokens are stored in OS-native secure storage:\n# - macOS: Keychain\n# - Windows: Credential Manager\n# - Linux: Secret Service (GNOME Keyring\u002FKWallet)\n```\n\n**Supported Locations**:\n- `env`: Environment variables for STDIO servers\n- `headers`: HTTP headers for HTTP\u002FSSE servers\n\n**Namespaces**:\n- `bearer`: Bearer tokens (default for `--type bearer`)\n- `api-key`: API keys (default for `--type api-key`)\n- `oauth`: OAuth tokens (automatic)\n- `generic`: Custom tokens\n\n**Benefits**:\n- ✅ Never store API keys in config files\n- ✅ Share `server_config.json` safely (no secrets)\n- ✅ Tokens encrypted in OS-native secure storage\n- ✅ Works across all transport types (STDIO, HTTP, SSE)\n\nSee [Token Management Guide](docs\u002FTOKEN_MANAGEMENT.md) for complete documentation.\n\n### Runtime Server Management\n\nAdd servers dynamically during runtime without editing configuration files:\n\n```bash\n# Add STDIO servers (most common)\nmcp-cli\n> \u002Fserver add sqlite stdio uvx mcp-server-sqlite --db-path mydata.db\n> \u002Fserver add playwright stdio npx @playwright\u002Fmcp@latest\n> \u002Fserver add time stdio uvx mcp-server-time\n\n# Add HTTP servers with authentication\n> \u002Fserver add github --transport http --header \"Authorization: Bearer ghp_token\" -- https:\u002F\u002Fapi.github.com\u002Fmcp\n> \u002Fserver add myapi --transport http --env API_KEY=secret -- https:\u002F\u002Fapi.example.com\u002Fmcp\n\n# Add SSE (Server-Sent Events) servers\n> \u002Fserver add events --transport sse -- https:\u002F\u002Fevents.example.com\u002Fsse\n\n# Manage servers\n> \u002Fserver list                     # Show all servers\n> \u002Fserver disable sqlite           # Temporarily disable\n> \u002Fserver enable sqlite            # Re-enable\n> \u002Fserver remove myapi             # Remove user-added server\n```\n\n**Key Points:**\n- User-added servers persist in `~\u002F.mcp-cli\u002Fpreferences.json`\n- Survive application restarts\n- Can be enabled\u002Fdisabled without removal\n- Support STDIO, HTTP, and SSE transports\n- Environment variables and headers for authentication\n\n## 📈 Advanced Usage Examples\n\n### Reasoning Model Comparison\n\n```bash\n# Compare reasoning across different models\n> \u002Fprovider ollama\n> \u002Fmodel gpt-oss\n> Think through this problem step by step: If a train leaves New York at 3 PM...\n[See the complete thinking process with gpt-oss]\n\n> \u002Fprovider openai\n> \u002Fmodel gpt-5\n> Think through this problem step by step: If a train leaves New York at 3 PM...\n[See GPT-5's reasoning approach]\n\n> \u002Fprovider anthropic\n> \u002Fmodel claude-4-5-opus\n> Think through this problem step by step: If a train leaves New York at 3 PM...\n[See Claude 4.5's analytical process]\n```\n\n### Local-First Workflow with Reasoning\n\n```bash\n# Start with default Ollama\u002Fgpt-oss (no API key needed)\nmcp-cli chat --server sqlite\n\n# Use reasoning model for complex problems\n> Think through this database optimization problem step by step\n[gpt-oss shows its complete thinking process before answering]\n\n# Try different local models for different tasks\n> \u002Fmodel llama3.3              # General purpose\n> \u002Fmodel qwen2.5-coder         # For coding tasks\n> \u002Fmodel deepseek-coder        # Alternative coding model\n> \u002Fmodel granite3.3            # IBM's model\n> \u002Fmodel gpt-oss               # Back to reasoning model\n\n# Switch to cloud when needed (requires API keys)\n> \u002Fprovider openai\n> \u002Fmodel gpt-5\n> Complex enterprise architecture design...\n\n> \u002Fprovider anthropic\n> \u002Fmodel claude-4-5-opus\n> Detailed strategic analysis...\n\n> \u002Fprovider ollama\n> \u002Fmodel gpt-oss\n> Continue with local processing...\n```\n\n### Multi-Provider Workflow\n\n```bash\n# Start with local reasoning (default, no API key)\nmcp-cli chat --server sqlite\n\n# Compare responses across providers\n> \u002Fprovider ollama\n> What's the best way to optimize this SQL query?\n\n> \u002Fprovider openai gpt-5        # Requires API key\n> What's the best way to optimize this SQL query?\n\n> \u002Fprovider anthropic claude-4-5-sonnet  # Requires API key\n> What's the best way to optimize this SQL query?\n\n# Use each provider's strengths\n> \u002Fprovider ollama gpt-oss      # Local reasoning, privacy\n> \u002Fprovider openai gpt-5        # Advanced reasoning\n> \u002Fprovider anthropic claude-4-5-opus  # Deep analysis\n> \u002Fprovider groq llama-3.1-70b  # Ultra-fast responses\n```\n\n### Complex Tool Workflows with Reasoning\n\n```bash\n# Use reasoning model for complex database tasks\n> \u002Fmodel gpt-oss\n> I need to analyze our database performance. Think through what we should check first.\n[gpt-oss shows thinking: \"First, I should check the table structure, then indexes, then query patterns...\"]\n[Tool: list_tables] → products, customers, orders\n\n> Now analyze the indexes and suggest optimizations\n[gpt-oss thinks through index analysis]\n[Tool: describe_table] → Shows current indexes\n[Tool: read_query] → Analyzes query patterns\n\n> Create an optimization plan based on your analysis\n[Complete reasoning process followed by specific recommendations]\n```\n\n### Automation and Scripting\n\n```bash\n# Batch processing with different models\nfor file in data\u002F*.csv; do\n  # Use reasoning model for analysis\n  mcp-cli cmd --server sqlite \\\n    --model gpt-oss \\\n    --prompt \"Analyze this data and think through patterns\" \\\n    --input \"$file\" \\\n    --output \"analysis\u002F$(basename \"$file\" .csv)_reasoning.txt\"\n  \n  # Use coding model for generating scripts\n  mcp-cli cmd --server sqlite \\\n    --model qwen2.5-coder \\\n    --prompt \"Generate Python code to process this data\" \\\n    --input \"$file\" \\\n    --output \"scripts\u002F$(basename \"$file\" .csv)_script.py\"\ndone\n\n# Pipeline with reasoning\ncat complex_problem.txt | \\\n  mcp-cli cmd --model gpt-oss --prompt \"Think through this step by step\" --input - | \\\n  mcp-cli cmd --model llama3.3 --prompt \"Summarize the key points\" --input - > solution.txt\n```\n\n### Performance Monitoring\n\n```bash\n# Check provider and model performance\n> \u002Fprovider diagnostic\nProvider Diagnostics\nProvider      | Status      | Response Time | Features      | Models\nollama        | ✅ Ready    | 56ms         | 📡🔧         | gpt-oss, llama3.3, qwen3, ...\nopenai        | ✅ Ready    | 234ms        | 📡🔧👁️      | gpt-5, gpt-4o, o3, ...\nanthropic     | ✅ Ready    | 187ms        | 📡🔧         | claude-4-5-opus, claude-4-5-sonnet, ...\nazure_openai  | ✅ Ready    | 198ms        | 📡🔧👁️      | gpt-5, gpt-4o, ...\ngemini        | ✅ Ready    | 156ms        | 📡🔧👁️      | gemini-2.0-flash, ...\ngroq          | ✅ Ready    | 45ms         | 📡🔧         | llama-3.1-70b, ...\n\n# Check available models\n> \u002Fmodels\nModels for ollama (Current Provider)\nModel                | Status\ngpt-oss             | Current & Default (Reasoning)\nllama3.3            | Available\nllama3.2            | Available\nqwen2.5-coder       | Available\ndeepseek-coder      | Available\ngranite3.3          | Available\n... and 6 more\n\n# Monitor tool execution with reasoning\n> \u002Fverbose\n> \u002Fmodel gpt-oss\n> Analyze the database and optimize the slowest queries\n[Shows complete thinking process]\n[Tool execution with timing]\n```\n\n## 🔍 Troubleshooting\n\n### Common Issues\n\n1. **Ollama not running** (default provider):\n   ```bash\n   # Start Ollama service\n   ollama serve\n   \n   # Or check if it's running\n   curl http:\u002F\u002Flocalhost:11434\u002Fapi\u002Ftags\n   ```\n\n2. **Model not found**:\n   ```bash\n   # For Ollama (default), pull the model first\n   ollama pull gpt-oss      # Reasoning model\n   ollama pull llama3.3     # Latest Llama\n   ollama pull qwen2.5-coder # Coding model\n   \n   # List available models\n   ollama list\n   \n   # For cloud providers, check supported models\n   mcp-cli models openai     # Shows GPT-5, GPT-4, O3 models\n   mcp-cli models anthropic  # Shows Claude 4.5, Claude 3.5 models\n   ```\n\n3. **Provider not found or API key missing**:\n   ```bash\n   # Check available providers\n   mcp-cli provider list\n   \n   # For cloud providers, set API keys\n   mcp-cli provider set openai api_key sk-your-key\n   mcp-cli provider set anthropic api_key sk-ant-your-key\n   \n   # Test connection\n   mcp-cli provider diagnostic openai\n   ```\n\n4. **Connection issues with Ollama**:\n   ```bash\n   # Check Ollama is running\n   ollama list\n   \n   # Test connection\n   mcp-cli provider diagnostic ollama\n   \n   # Configure custom endpoint if needed\n   mcp-cli provider set ollama api_base http:\u002F\u002Flocalhost:11434\n   ```\n\n### Debug Mode\n\nEnable verbose logging for troubleshooting:\n\n```bash\nmcp-cli --verbose chat --server sqlite\nmcp-cli --log-level DEBUG interactive --server sqlite\n\n# Write debug logs to a rotating file (secrets are automatically redacted)\nmcp-cli --log-file ~\u002F.mcp-cli\u002Flogs\u002Fdebug.log --server sqlite\n```\n\n## 🔒 Security Considerations\n\n### Privacy & Local-First\n- **Local by Default**: Ollama with gpt-oss runs locally, keeping your data private\n- **No Cloud Required**: Full functionality without external API dependencies\n\n### Token & Authentication Security\n- **Secure Token Storage**: Tokens stored in OS-native credential stores (macOS Keychain, Windows Credential Manager, Linux Secret Service) under the \"mcp-cli\" service identifier\n- **Multiple Storage Backends**: Choose between keychain, encrypted files, or HashiCorp Vault based on security requirements\n- **API Keys**: Only needed for cloud providers (OpenAI, Anthropic, etc.), stored securely using token management system\n- **OAuth 2.0 Support**: Secure authentication for MCP servers using PKCE and resource indicators (RFC 7636, RFC 8707)\n\n### Log Security\n- **Secret Redaction**: All log output (console and file) is automatically redacted for Bearer tokens, API keys (sk-*), OAuth access tokens, and Authorization headers\n- **Rotating File Logs**: Optional `--log-file` with JSON format, 10MB rotation, and 3 backup files\n\n### Execution Security\n- **Tool Validation**: All tool calls are validated before execution\n- **Timeout Protection**: Configurable timeouts prevent hanging operations (v0.13+)\n- **Circuit Breakers**: Automatic failure detection and recovery to prevent cascading failures (v0.13+)\n- **Server Isolation**: Each server runs in its own process\n- **File Access**: Filesystem access can be disabled with `--disable-filesystem`\n- **Transport Monitoring**: Automatic detection of connection failures with warnings (v0.11+)\n\n### MCP Apps Security\n- **Iframe Sandbox**: Apps run in sandboxed iframes with restricted permissions\n- **Content Security Policy**: Server-supplied CSP domains are validated and sanitized\n- **XSS Prevention**: Tool names and user-supplied content are HTML-escaped before template injection\n- **URL Scheme Validation**: `ui\u002Fopen-link` only allows `http:\u002F\u002F` and `https:\u002F\u002F` schemes\n- **Tool Name Validation**: Bridge rejects tool names not matching the MCP spec character set\n\n## 🚀 Performance Features\n\n### LLM Provider Performance (v0.16+)\n- **52x Faster Imports**: Reduced from 735ms to 14ms through lazy loading\n- **112x Faster Client Creation**: Automatic thread-safe caching\n- **llama.cpp Integration**: 1.53x faster inference (311 vs 204 tokens\u002Fsec) with automatic Ollama model reuse\n- **Dynamic Model Discovery**: Zero overhead capability-based model selection\n\n### Tool Execution Performance (v0.13+)\n- **Production Middleware**: Timeouts, retries with exponential backoff, circuit breakers, and result caching\n- **Concurrent Tool Execution**: Multiple tools can run simultaneously with proper coordination\n- **Connection Health Monitoring**: Automatic detection and recovery from transport failures\n- **Optimized Tool Manager**: Reduced from 2000+ to ~800 lines while maintaining all functionality\n\n### Runtime Performance\n- **Local Processing**: Default Ollama provider minimizes latency\n- **Reasoning Visibility**: See AI thinking process with gpt-oss, GPT-5, Claude 4\n- **Streaming Responses**: Real-time response generation\n- **Connection Pooling**: Efficient reuse of client connections\n- **Caching**: Tool metadata and provider configurations are cached\n- **Async Architecture**: Non-blocking operations throughout\n\n## 📦 Dependencies\n\nCore dependencies are organized into feature groups:\n\n- **cli**: Terminal UI and command framework (Rich, Typer, chuk-term)\n- **dev**: Development tools, testing utilities, linting\n- **chuk-tool-processor v0.22+**: Production-grade tool execution with middleware, multiple execution strategies, and observability\n- **chuk-llm v0.17+**: Unified LLM provider with dynamic model discovery, capability-based selection, and llama.cpp integration\n- **chuk-term**: Enhanced terminal UI with themes, prompts, and cross-platform support\n\nInstall with specific features:\n```bash\npip install \"mcp-cli[cli]\"        # Basic CLI features\npip install \"mcp-cli[cli,dev]\"    # CLI with development tools\npip install \"mcp-cli[apps]\"       # MCP Apps (interactive browser UIs)\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fmcp-cli\ncd mcp-cli\npip install -e \".[cli,dev]\"\npre-commit install\n```\n\n### Demo Scripts\n\nExplore the capabilities of MCP CLI:\n\n```bash\n# Command Mode Demos\n\n# General cmd mode features (bash)\nbash examples\u002Fcmd_mode_demo.sh\n\n# LLM integration with cmd mode (bash)\nbash examples\u002Fcmd_mode_llm_demo.sh\n\n# Python integration example\nuv run examples\u002Fcmd_mode_python_demo.py\n\n# Custom Provider Management Demos\n\n# Interactive walkthrough demo (educational)\nuv run examples\u002Fcustom_provider_demo.py\n\n# Working demo with actual inference (requires OPENAI_API_KEY)\nuv run examples\u002Fcustom_provider_working_demo.py\n\n# Simple shell script demo (requires OPENAI_API_KEY)\nbash examples\u002Fcustom_provider_simple_demo.sh\n\n# Terminal management features (chuk-term)\nuv run examples\u002Fui_terminal_demo.py\n\n# Output system with themes (chuk-term)\nuv run examples\u002Fui_output_demo.py\n\n# Streaming UI capabilities (chuk-term)\nuv run examples\u002Fui_streaming_demo.py\n```\n\n### Running Tests\n\n```bash\npytest\npytest --cov=mcp_cli --cov-report=html\n```\n\n## 📜 License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- **[CHUK Tool Processor](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fchuk-tool-processor)** - Production-grade async tool execution with middleware and observability\n- **[CHUK-LLM](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fchuk-llm)** - Unified LLM provider with dynamic model discovery, llama.cpp integration, and GPT-5\u002FClaude 4.5 support (v0.17+)\n- **[CHUK-Term](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fchuk-term)** - Enhanced terminal UI with themes and cross-platform support\n- **[Rich](https:\u002F\u002Fgithub.com\u002FTextualize\u002Frich)** - Beautiful terminal formatting\n- **[Typer](https:\u002F\u002Ftyper.tiangolo.com\u002F)** - CLI framework\n- **[Prompt Toolkit](https:\u002F\u002Fgithub.com\u002Fprompt-toolkit\u002Fpython-prompt-toolkit)** - Interactive input\n\n## 🔗 Related Projects\n\n- **[Model Context Protocol](https:\u002F\u002Fmodelcontextprotocol.io\u002F)** - Core protocol specification\n- **[MCP Servers](https:\u002F\u002Fgithub.com\u002Fmodelcontextprotocol\u002Fservers)** - Official MCP server implementations\n- **[CHUK Tool Processor](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fchuk-tool-processor)** - Production-grade tool execution with middleware and observability\n- **[CHUK-LLM](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fchuk-llm)** - LLM provider abstraction with dynamic model discovery, GPT-5, Claude 4.5, O3 series support, and llama.cpp integration\n- **[CHUK-Term](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fchuk-term)** - Terminal UI library with themes and cross-platform support","# MCP CLI - 模型上下文协议命令行界面\n\n[![CI](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fmcp-cli\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fmcp-cli\u002Factions\u002Fworkflows\u002Fci.yml)\n[![PyPI版本](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fmcp-cli.svg)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fmcp-cli\u002F)\n\n一个功能强大、特性丰富的命令行界面，用于与模型上下文协议服务器交互。该客户端通过与[CHUK工具处理器](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fchuk-tool-processor)和[CHUK-LLM](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fchuk-llm)集成，实现与大语言模型的无缝通信，提供工具使用、对话管理以及多种操作模式。\n\n**默认配置**：MCP CLI 默认使用 Ollama，并采用 `gpt-oss` 推理模型，以实现本地、注重隐私的操作，无需 API 密钥。\n\n## 🆕 最近更新（v0.16）\n\n### AI 虚拟内存（实验性）\n- **`--vm` 标志**：启用操作系统风格的虚拟内存，用于对话上下文管理，由 `chuk-ai-session-manager` 提供支持\n- **`--vm-budget`**：控制对话事件的标记预算（系统提示不受限制），强制较早驱逐并创建页面\n- **`--vm-mode`**：选择 VM 模式——`passive`（运行时管理，默认）、`relaxed`（感知 VM 的对话）或 `strict`（模型驱动的分页与工具结合）\n- **`\u002Fmemory` 命令**：可视化对话期间的 VM 状态——页表、工作集利用率、驱逐指标、TLB 统计信息（别名：`\u002Fvm`、`\u002Fmem`）\n- **多模态 page_fault**：图像页面返回多块内容（文本 + image_url），以便多模态模型可重新分析召回的图像\n- **`\u002Fmemory page \u003Cid> --download`**：将页面内容导出到本地文件，并带有模态感知的扩展名（.txt、.json、.png）\n\n### 执行计划（第 6 层）\n- **`\u002Fplan` 命令**：创建、检查和执行可复现的工具调用图——`create`、`list`、`show`、`run`、`delete`、`resume`\n- **模型驱动规划 (`--plan-tools`)**：大语言模型在对话过程中自主创建并执行计划——无需 `\u002Fplan` 命令。当需要多步骤编排时调用 `plan_create_and_execute`，简单任务则使用常规工具。每一步都在终端中实时显示进度\n- **并行批量执行**：独立的计划步骤通过拓扑排序批量执行（Kahn 的 BFS），可配置 `max_concurrency`\n- **变量解析**：`${var}`、`${var.field}` 嵌套访问，以及类似 `\"https:\u002F\u002F${api.host}\u002Fusers\"` 的模板字符串——对单个引用保持类型一致\n- **干运行模式**：跟踪计划的工具调用而不实际执行——适合生产环境检查\n- **检查点与恢复**：每次批量后持久化执行状态；中断的计划可通过 `\u002Fplan resume \u003Cid>` 恢复\n- **防护集成**：计划尊重现有预算、每工具限制及失控检测防护\n- **DAG 可视化**：ASCII 渲染，带状态指示符（○\u002F◉\u002F●\u002F✗）和并行标记符（∥）\n- **重新规划**：可选的基于大语言模型的重新规划，在步骤失败时启用 (`enable_replan=True`)\n- **驱动技术**：[chuk-ai-planner](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fchuk-ai-planner) 图形化计划 DSL\n\n### MCP 应用程序（SEP-1865）\n- **交互式 HTML UI**：MCP 服务器可提供交互式 HTML 应用程序（图表、表格、地图、Markdown 查看器），在浏览器中渲染\n- **沙箱 iframe**：应用运行于安全的沙箱 iframe 中，具备 CSP 防护\n- **WebSocket 桥接**：浏览器应用与 MCP 服务器之间的实时双向通信\n- **自动启动**：带有 `_meta.ui` 注解的工具在调用时会自动在浏览器中打开\n- **会话可靠性**：消息队列、指数退避重连、延迟工具结果交付\n\n### 生产环境加固\n- **密钥脱敏**：所有日志输出（控制台和文件）都会自动脱敏 Bearer 令牌、API 密钥、OAuth 令牌和授权头\n- **结构化文件日志**：可选的 `--log-file` 标志启用轮转 JSON 日志文件（10MB，3 个备份），级别为 DEBUG\n- **每服务器超时**：服务器配置支持 `tool_timeout` 和 `init_timeout` 覆盖，按服务器 → 全局 → 默认解析\n- **线程安全 OAuth**：并发 OAuth 流程通过 `asyncio.Lock` 序列化，且头部变更采用写时复制\n- **服务器健康监测**：`\u002Fhealth` 命令、故障时健康检查诊断，可选的 `--health-interval` 后台轮询\n\n### 性能与优化\n- **O(1) 工具查找**：索引化的工具查找取代了 O(n) 的线性扫描\n- **缓存 LLM 工具元数据**：按提供商缓存，自动失效\n- **启动进度**：初始化期间的实时进度消息\n- **标记使用追踪**：每轮及累计追踪，通过 `\u002Fusage` 命令（别名：`\u002Ftokens`、`\u002Fcost`）\n- **会话持久化**：保存\u002F加载\u002F列出对话会话，每 10 轮自动保存（`\u002Fsessions`）\n- **对话导出**：将对话导出为 Markdown 或 JSON 并附带元数据（`\u002Fexport`）\n\n### 仪表板（实时浏览器 UI）\n- **`--dashboard` 标志**：在聊天模式旁启动实时浏览器仪表板\n- **代理终端**：实时对话视图，带消息气泡、流式标记和附件渲染\n- **活动流**：工具调用\u002F结果对、推理步骤及用户附件事件\n- **计划查看器**：可视化执行计划进度，带 DAG 渲染\n- **工具注册表**：浏览发现的工具，从浏览器触发执行\n- **配置面板**：查看并切换提供商、模型及系统提示\n- **文件附件**：浏览器文件上传的“+”按钮，拖放及剪贴板粘贴支持\n\n### 多模态附件\n- **`\u002Fattach` 命令**：为下一条消息暂存文件——图片、文本\u002F代码及音频（别名：`\u002Ffile`、`\u002Fimage`）\n- **`--attach` CLI 标志**：为第一条消息附加文件（可重复：`--attach img.png --attach code.py`）\n- **内联 `@file:` 引用**：在消息任意位置提及 `@file:路径\u002F文件` 即可附加\n- **图片 URL 检测**：消息中的 HTTP\u002FHTTPS 图片 URL 会自动作为视觉内容发送\n- **支持格式**：PNG、JPEG、GIF、WebP、HEIC（图片）、MP3、WAV（音频），以及 25+ 文本\u002F代码扩展\n- **仪表板渲染**：图片缩略图、可展开的文本预览、音频播放器、文件标签\n- **浏览器上传**：仪表板聊天输入中的“+”按钮，支持拖放及剪贴板粘贴\n\n### 代码质量\n- **核心与 UI 分离**：核心模块仅使用 `logging`——不引入 UI\n- **4,300+ 测试**：全面测试套件，包含分支覆盖率、集成测试及 60% 的最低阈值\n- **15 项架构原则**：已文档化并强制执行（参见 [architecture.md](architecture.md)）\n- **完整[路线图](roadmap.md)**：第 1-6 层已完成，第 7-12 层规划中（追踪、内存范围、技能、调度、多智能体）\n\n## 🔄 架构概览\n\nMCP CLI 基于模块化架构构建，实现了清晰的职责分离：\n\n- **[CHUK 工具处理器](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fchuk-tool-processor)**：生产级异步工具执行，内置中间件（重试、熔断器、限流）、多种执行策略及可观测性功能。\n- **[CHUK-LLM](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fchuk-llm)**：统一的大型语言模型提供商，支持动态模型发现、基于能力的选择以及 llama.cpp 集成（比 Ollama 快 1.53 倍，并自动复用模型）。\n- **[CHUK-Term](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fchuk-term)**：增强型终端 UI，支持主题切换、跨平台终端管理及丰富的格式化功能。\n- **MCP CLI**：命令编排与集成层（本项目）。\n\n## 🌟 主要特性\n\n### 多种运行模式\n- **聊天模式**：对话式界面，支持流式响应和自动化工具使用（默认：Ollama\u002Fgpt-oss）。\n- **交互模式**：命令驱动的 Shell 界面，用于直接操作服务器。\n- **命令模式**：兼容 Unix 的模式，适合脚本化自动化与流水线。\n- **直接命令**：无需进入交互模式即可直接运行单个命令。\n\n### 先进的聊天界面\n- **流式响应**：实时生成响应并同步更新 UI。\n- **推理可见性**：通过推理模型（gpt-oss、GPT-5、Claude 4.5）查看 AI 的思考过程。\n- **并发工具执行**：同时执行多个工具，同时保持对话顺序。\n- **智能中断**：按 Ctrl+C 可中断流式响应或工具执行。\n- **性能指标**：包括响应时间、每秒词数及执行统计信息。\n- **丰富格式化**：支持 Markdown 渲染、语法高亮及进度指示器。\n- **Token 使用追踪**：通过 `\u002Fusage` 命令可查看每轮及累计的 API Token 使用情况。\n- **多模态附件**：可通过 `\u002Fattach`、`--attach`、`@file:` 引用或浏览器上传方式，向消息中添加图片、文本文件及音频。\n- **会话持久化**：自动保存及手动保存\u002F加载对话会话。\n- **对话导出**：支持以 Markdown 或 JSON 格式导出对话内容，包含元数据及 Token 使用信息。\n\n### 全面的提供商支持\n\nMCP CLI 支持 CHUK-LLM 的所有提供商与模型，包括前沿推理模型：\n\n| 提供商 | 关键模型 | 特殊功能 |\n|----------|------------|------------------|\n| **Ollama**（默认） | 🧠 gpt-oss、llama3.3、llama3.2、qwen3、qwen2.5-coder、deepseek-coder、granite3.3、mistral、gemma3、phi3、codellama | 本地推理模型，注重隐私，无需 API 密钥 |\n| **OpenAI** | 🚀 GPT-5 系列（gpt-5、gpt-5-mini、gpt-5-nano）、GPT-4o 系列、O3 系列（o3、o3-mini） | 高级推理、函数调用、视觉处理 |\n| **Anthropic** | 🧠 Claude 4.5 系列（claude-4-5-opus、claude-4-5-sonnet）、Claude 3.5 Sonnet | 增强推理能力，长上下文支持 |\n| **Azure OpenAI** 🏢 | 企业版 GPT-5、GPT-4 模型 | 私有端点、合规性、审计日志 |\n| **Google Gemini** | Gemini 2.0 Flash、Gemini 1.5 Pro | 多模态，快速推理 |\n| **Groq** ⚡ | Llama 3.1 模型、Mixtral | 超高速推理（500+ tokens\u002Fsec） |\n| **Perplexity** 🌐 | Sonar 模型 | 实时网络搜索并附带引用 |\n| **IBM watsonx** 🏢 | Granite、Llama 模型 | 企业级合规性 |\n| **Mistral AI** 🇪🇺 | Mistral Large、Medium | 欧洲高效模型 |\n\n### 强大的工具系统（由 CHUK 工具处理器 v0.22+ 提供支持）\n- **自动发现**：服务器提供的工具会自动检测并编入目录。\n- **提供商适配**：工具名称会自动清理以适应不同提供商。\n- **生产级执行**：内置中间件层，支持超时、重试、指数退避、缓存及熔断机制。\n- **多种执行策略**：进程内（快速）、独立子进程（安全），或通过 MCP 远程执行。\n- **并发执行**：多个工具可同时运行并协调一致。\n- **丰富的进度显示**：实时进度指示器及执行计时。\n- **工具历史**：完整记录所有工具执行的审计轨迹。\n- **中间件**：通过 CTP 支持指数退避重试、熔断器及限流。\n- **流式工具调用**：支持返回流式数据的工具。\n\n### MCP 应用程序（交互式 UI）\n- **基于浏览器的 UI**：MCP 服务器可提供交互式 HTML 应用程序，在浏览器中渲染。\n- **自动检测**：带有 `_meta.ui` 注解的工具会在调用时自动启动浏览器应用。\n- **沙箱执行**：应用运行在受保护的沙箱 iframe 中，具备内容安全策略防护。\n- **WebSocket 桥接**：浏览器应用与 MCP 工具服务器之间的实时 JSON-RPC 桥接。\n- **会话持久化**：断开连接时的消息队列、自动重连及延迟工具结果交付。\n- **structuredContent 支持**：完全符合 MCP 规范，包括结构化内容提取与转发。\n\n### 执行计划（由 chuk-ai-planner 提供支持）\n- **计划创建**：通过自然语言描述生成执行计划，使用基于 LLM 的计划代理。\n- **模型驱动规划**：使用 `--plan-tools` 参数，LLM 自主决定何时规划——对复杂多步骤任务调用 `plan_create_and_execute`，简单任务则直接使用常规工具。\n- **DAG 执行**：计划为有向无环图——独立步骤并行批次执行，依赖步骤等待。\n- **变量解析**：步骤输出绑定到变量（`result_variable`），后续步骤可引用为 `${var}` 或 `${var.field}`。\n- **干运行模式**：在不执行任何工具的情况下跟踪计划将如何执行——适用于生产环境的安全测试。\n- **检查点**：每次批次后保存执行状态；恢复中断的计划，无需重新执行已完成步骤。\n- **Guard 集成**：计划与对话共享预算及每工具限制——不可绕过。\n- **重新规划**：当步骤失败时，可选择调用 LLM 生成剩余工作的修订计划。\n- **DAG 可视化**：ASCII 渲染展示依赖关系结构、批次分组及并行标记。\n- **持久化**：计划以 JSON 格式存储在 `~\u002F.mcp-cli\u002Fplans\u002F`。\n\n### 高级配置管理\n- **环境集成**：通过环境变量管理 API 密钥与设置。\n- **文件配置**：支持 YAML 和 JSON 配置文件。\n- **用户偏好**：保存活跃提供商与模型的持久化设置。\n- **验证与诊断**：内置提供商健康检查与配置验证。\n\n### 优化的用户体验\n- **跨平台支持**：Windows、macOS 和 Linux，通过 chuk-term 实现针对各平台的优化\n- **丰富的控制台输出**：由 chuk-term 提供支持，内置 8 种主题（默认、深色、浅色、极简、终端、Monokai、Dracula、Solarized）\n- **高级终端管理**：跨平台终端操作功能，包括清除、调整大小、颜色检测和光标控制\n- **交互式 UI 组件**：通过 chuk-term 的提示系统处理用户输入（ask、confirm、select_from_list、select_multiple）\n- **命令补全**：所有界面均支持上下文感知的 Tab 键补全\n- **全面的帮助文档**：提供详尽的帮助系统，包含示例和使用模式\n- **友好的错误处理**：提供用户友好的错误信息，并附带故障排除提示\n\n## 📚 文档\n\n完整的文档位于 `docs\u002F` 目录中：\n\n### 项目\n- **[架构](architecture.md)** - 15 项设计原则、模块布局和编码规范\n- **[路线图](roadmap.md)** - 愿景、已完成的阶段（1-5）、以及计划中的阶段（6-12：规划、追踪、技能、调度、多智能体、远程会话）\n\n### 核心文档\n- **[命令系统](docs\u002FCOMMANDS.md)** - 统一命令系统的完整指南、模式及所有模式下的用法\n- **[令牌管理](docs\u002FTOKEN_MANAGEMENT.md)** - 针对提供商和服务器的全面令牌管理，包括 OAuth、Bearer 令牌和 API 密钥\n\n### 专项文档\n- **[执行计划](docs\u002FPLANNING.md)** - 计划创建、并行执行、变量解析、检查点、守卫和重新规划\n- **[仪表板](docs\u002FDASHBOARD.md)** - 实时浏览器 UI，包含智能体终端、活动流和文件上传\n- **[附件](docs\u002FATTACHMENTS.md)** - 多模态文件附件：图片、文本、音频和浏览器上传\n- **[MCP 应用](docs\u002FMCP_APPS.md)** - 由 MCP 服务器提供的交互式浏览器 UI（SEP-1865）\n- **[OAuth 认证](docs\u002FOAUTH.md)** - OAuth 流程、存储后端和 MCP 服务器集成\n- **[流式集成](docs\u002FSTREAMING.md)** - 实时响应流式架构\n- **[包管理](docs\u002FPACKAGE_MANAGEMENT.md)** - 依赖组织和功能分组\n\n### UI 文档\n- **[主题](docs\u002Fui\u002Fthemes.md)** - 主题系统和自定义\n- **[输出系统](docs\u002Fui\u002Foutput.md)** - 丰富的控制台输出和格式化\n- **[终端管理](docs\u002Fui\u002Fterminal.md)** - 跨平台终端操作\n\n### 测试文档\n- **[单元测试](docs\u002Ftesting\u002FUNIT_TESTING.md)** - 测试结构和模式\n- **[测试覆盖率](docs\u002Ftesting\u002FTEST_COVERAGE.md)** - 覆盖率要求和报告\n\n## 📋 先决条件\n\n- **Python 3.11 或更高版本**\n- **本地运行（默认）**：\n  - Ollama：从 [ollama.ai](https:\u002F\u002Follama.ai) 安装\n  - 拉取默认推理模型：`ollama pull gpt-oss`\n- **云端提供商（可选）**：\n  - OpenAI：`OPENAI_API_KEY` 环境变量（用于 GPT-5、GPT-4、O3 模型）\n  - Anthropic：`ANTHROPIC_API_KEY` 环境变量（用于 Claude 4.5、Claude 3.5）\n  - Azure：`AZURE_OPENAI_API_KEY` 和 `AZURE_OPENAI_ENDPOINT`（用于企业版 GPT-5）\n  - Google：`GEMINI_API_KEY`（用于 Gemini 模型）\n  - Groq：`GROQ_API_KEY`（用于快速 Llama 模型）\n  - 自定义提供商：特定提供商的配置\n- **MCP 服务器**：服务器配置文件（默认：`server_config.json`）\n\n## 🚀 安装\n\n### 使用 Ollama 快速入门（默认）\n\n1. **安装 Ollama**（如果尚未安装）：\n```bash\n# macOS\u002FLinux\ncurl -fsSL https:\u002F\u002Follama.ai\u002Finstall.sh | sh\n\n# 或访问 https:\u002F\u002Follama.ai 获取其他安装方法\n```\n\n2. **拉取默认推理模型**：\n```bash\nollama pull gpt-oss  # 开源推理模型，具备思考可视化功能\n```\n\n3. **安装并运行 MCP CLI**：\n```bash\n# 推荐使用 uvx\nuvx mcp-cli --help\n\n# 或从源码安装\ngit clone https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fmcp-cli\ncd mcp-cli\npip install -e \".\"\nmcp-cli --help\n\n# 可选：启用 MCP 应用（交互式浏览器 UI）\npip install -e \".[apps]\"\n```\n\n### 使用不同模型\n\n```bash\n# === 本地模型（无需 API 密钥）===\n\n# 使用默认推理模型（gpt-oss）\nmcp-cli --server sqlite\n\n# 使用其他 Ollama 模型\nmcp-cli --model llama3.3              # 最新 Llama\nmcp-cli --model qwen2.5-coder         # 专注编码\nmcp-cli --model deepseek-coder        # 另一种编码模型\nmcp-cli --model granite3.3            # IBM Granite\n\n# === 云端提供商（需要 API 密钥）===\n\n# GPT-5 系列（需 OpenAI API 密钥）\nmcp-cli --provider openai --model gpt-5          # 全功能 GPT-5，具备推理能力\nmcp-cli --provider openai --model gpt-5-mini     # 高效 GPT-5 变体\nmcp-cli --provider openai --model gpt-5-nano     # 超轻量级 GPT-5\n\n# GPT-4 系列\nmcp-cli --provider openai --model gpt-4o         # GPT-4 优化版\nmcp-cli --provider openai --model gpt-4o-mini    # 较小的 GPT-4\n\n# O3 推理模型\nmcp-cli --provider openai --model o3             # O3 推理\nmcp-cli --provider openai --model o3-mini        # 高效 O3\n\n# Claude 4.5 系列（需 Anthropic API 密钥）\nmcp-cli --provider anthropic --model claude-4-5-opus    # 最先进的 Claude\nmcp-cli --provider anthropic --model claude-4-5-sonnet  # 平衡的 Claude 4.5\nmcp-cli --provider anthropic --model claude-3-5-sonnet  # Claude 3.5\n\n# 企业版 Azure（需 Azure 配置）\nmcp-cli --provider azure_openai --model gpt-5    # 企业版 GPT-5\n\n# 其他提供商\nmcp-cli --provider gemini --model gemini-2.0-flash      # Google Gemini\nmcp-cli --provider groq --model llama-3.1-70b          # 通过 Groq 的快速 Llama\n```\n\n## 🧰 全局配置\n\n### 默认配置\n\nMCP CLI 默认设置为：\n- **提供商**：`ollama`（本地，无需 API 密钥）\n- **模型**：`gpt-oss`（开源推理模型，具备思考可视化功能）\n\n### 命令行参数\n\n适用于所有模式和命令的全局选项：\n\n- `--server`：指定要连接的服务器（以逗号分隔）\n- `--config-file`：服务器配置文件的路径（默认：`server_config.json`）\n- `--provider`：LLM 提供商（默认：`ollama`）\n- `--model`：要使用的特定模型（默认：对于 Ollama 为 `gpt-oss`）\n- `--disable-filesystem`：禁用文件系统访问（默认：启用）\n- `--api-base`：覆盖 API 端点 URL\n- `--api-key`：覆盖 API 密钥（对于 Ollama 不需要）\n- `--token-backend`：覆盖令牌存储后端（`auto`、`keychain`、`windows`、`secretservice`、`encrypted`、`vault`）\n- `--verbose`：启用详细日志记录\n- `--quiet`：抑制非必要输出\n- `--log-file`：将调试日志写入轮转文件（自动脱敏密钥）\n- `--vm`：[实验性] 启用 AI 虚拟内存进行上下文管理\n- `--vm-budget`：VM 模式下对话事件的令牌预算（默认：128000，位于系统提示之上）\n- `--vm-mode`：VM 模式——`passive`（默认）、`relaxed` 或 `strict`\n- `--dashboard`：在聊天模式旁启动实时浏览器仪表板 UI\n- `--attach`：将文件附加到第一条消息（可重复：`--attach img.png --attach code.py`）\n- `--plan-tools`：启用模型驱动规划——LLM 自主创建并执行多步骤计划\n- `--no-tools`：完全禁用 MCP 工具调用——直接与 LLM 对话，无需连接任何 MCP 服务器\n\n### 环境变量\n\n```bash\n# 覆盖默认值\nexport LLM_PROVIDER=ollama              # 默认提供商（已为默认值）\nexport LLM_MODEL=gpt-oss                # 默认模型（已为默认值）\n\n# 对于云提供商（可选）\nexport OPENAI_API_KEY=sk-...           # 对于 GPT-5、GPT-4、O3 模型\nexport ANTHROPIC_API_KEY=sk-ant-...    # 对于 Claude 4.5、Claude 3.5\nexport AZURE_OPENAI_API_KEY=sk-...     # 对于企业版 GPT-5\nexport AZURE_OPENAI_ENDPOINT=https:\u002F\u002F...\nexport GEMINI_API_KEY=...              # 对于 Gemini 模型\nexport GROQ_API_KEY=...                # 对于 Groq 快速推理\n\n# 工具配置\nexport MCP_TOOL_TIMEOUT=120            # 工具执行超时时间（秒）\n```\n\n## 🌐 可用模式\n\n### 1. 聊天模式（默认）\n\n提供自然语言界面，支持流式响应和自动工具使用：\n\n```bash\n# 默认模式，使用 Ollama\u002Fgpt-oss 推理模型（无需 API 密钥）\nmcp-cli --server sqlite\n\n# 查看 AI 的思考过程，使用推理模型\nmcp-cli --server sqlite --model gpt-oss     # 开源推理\nmcp-cli --server sqlite --provider openai --model gpt-5  # GPT-5 推理\nmcp-cli --server sqlite --provider anthropic --model claude-4-5-opus  # Claude 4.5 推理\n\n# 使用不同的本地模型\nmcp-cli --server sqlite --model llama3.3\nmcp-cli --server sqlite --model qwen2.5-coder\n\n# 切换到云提供商（需要 API 密钥）\nmcp-cli chat --server sqlite --provider openai --model gpt-5\nmcp-cli chat --server sqlite --provider anthropic --model claude-4-5-sonnet\n\n# 附带实时浏览器仪表板启动\nmcp-cli --server sqlite --dashboard\n\n# 将文件附加到第一条消息\nmcp-cli --server sqlite --attach image.png --attach data.csv\n```\n\n### 2. 交互模式\n\n命令驱动的 Shell 界面，用于直接操作服务器：\n\n```bash\nmcp-cli interactive --server sqlite\n\n# 使用特定模型\nmcp-cli interactive --server sqlite --model gpt-oss       # 本地推理\nmcp-cli interactive --server sqlite --provider openai --model gpt-5  # 云 GPT-5\n```\n\n### 3. 命令模式\n\n适合 Unix 的接口，用于自动化和脚本编写：\n\n```bash\n# 使用推理模型处理文本\nmcp-cli cmd --server sqlite --model gpt-oss --prompt \"逐步思考\" --input data.txt\n\n# 使用 GPT-5 进行复杂推理\nmcp-cli cmd --server sqlite --provider openai --model gpt-5 --prompt \"分析这些数据\" --input data.txt\n\n# 直接执行工具\nmcp-cli cmd --server sqlite --tool list_tables --output tables.json\n\n# 流水线友好处理\necho \"SELECT * FROM users LIMIT 5\" | mcp-cli cmd --server sqlite --tool read_query --input -\n```\n\n### 4. 直接命令\n\n无需进入交互模式，直接执行单个命令：\n\n```bash\n# 列出可用工具\nmcp-cli tools --server sqlite\n\n# 显示提供商配置\nmcp-cli provider list\n\n# 显示当前提供商的可用模型\nmcp-cli models\n\n# 显示特定提供商的模型\nmcp-cli models openai    # 显示 GPT-5、GPT-4、O3 模型\nmcp-cli models anthropic # 显示 Claude 4.5、Claude 3.5 模型\nmcp-cli models ollama    # 显示 gpt-oss、llama3.3 等\n\n# Ping 服务器\nmcp-cli ping --server sqlite\n\n# 列出资源\nmcp-cli resources --server sqlite\n\n# UI 主题管理\nmcp-cli theme                     # 显示当前主题并列出可用主题\nmcp-cli theme dark                # 切换到深色主题\nmcp-cli theme --select            # 交互式主题选择器\nmcp-cli theme --list              # 列出所有可用主题\n\n# 令牌存储管理\nmcp-cli token backends            # 显示可用存储后端\nmcp-cli --token-backend encrypted token list  # 使用特定后端\n```\n\n## 🌐 MCP 应用程序（交互式浏览器 UI）\n\nMCP 应用程序允许工具服务器提供交互式 HTML UI，并在您的浏览器中渲染。当一个工具带有 `_meta.ui` 注解指向 UI 资源时，mcp-cli 会自动启动本地 Web 服务器并在您的浏览器中打开该应用程序。\n\n### 先决条件\n\n```bash\n# 安装应用程序额外包（添加 websocket 依赖）\npip install \"mcp-cli[apps]\"\n```\n\n### 工作原理\n\n1. 连接到提供应用功能的 MCP 服务器\n2. 调用带有 `_meta.ui` 元数据的工具（例如 `show_chart`、`show_table`）\n3. mcp-cli 自动获取 UI 资源，启动本地服务器，并打开您的浏览器\n4. 应用程序通过 WebSocket 实时接收工具结果\n\n### 示例\n\n```bash\n# 连接到带有应用功能的服务器\nmcp-cli --server view_demo\n\n# 在聊天中请求可视化内容：\n> 给我看看销售数据的图表\n# 浏览器自动打开交互式图表\n\n# \u002Ftools 命令显示哪些工具有应用 UI（APP 列）\n> \u002Ftools\n```\n\n### 架构\n\n- **宿主页面** 提供沙箱化的 iframe，包含应用程序 HTML\n- **WebSocket 桥接** 在浏览器和 MCP 服务器之间代理 JSON-RPC\n- **安全性**：iframe 沙箱、CSP 保护、XSS 防护、URL 方案验证\n- **可靠性**：断开连接时的消息队列、指数退避重连、延迟工具结果交付\n\n完整指南请参阅 [MCP 应用程序文档](docs\u002FMCP_APPS.md)。\n\n## 🤖 使用聊天模式\n\n聊天模式提供最先进的界面，支持流式响应和智能工具使用。\n\n### 启动聊天模式\n\n```bash\n# 简单启动，使用默认推理模型（gpt-oss）\nmcp-cli --server sqlite\n\n# 多个服务器\nmcp-cli --server sqlite,filesystem\n\n# 搭配先进推理模型\nmcp-cli --server sqlite --provider openai --model gpt-5\nmcp-cli --server sqlite --provider anthropic --model claude-4-5-opus\n```\n\n### 聊天命令（斜杠命令）\n\n#### 提供商与模型管理\n```bash\n\u002Fprovider                           # 显示当前配置（默认：ollama）\n\u002Fprovider list                      # 列出所有提供商\n\u002Fprovider config                    # 显示详细配置\n\u002Fprovider diagnostic               # 测试提供商连接性\n\u002Fprovider set ollama api_base http:\u002F\u002Flocalhost:11434  # 配置Ollama端点\n\u002Fprovider openai                   # 切换到OpenAI（需API密钥）\n\u002Fprovider anthropic                # 切换到Anthropic（需API密钥）\n\u002Fprovider openai gpt-5             # 切换到OpenAI GPT-5\n\n# 自定义提供商管理\n\u002Fprovider custom                   # 列出自定义提供商\n\u002Fprovider add localai http:\u002F\u002Flocalhost:8080\u002Fv1 gpt-4  # 添加自定义提供商\n\u002Fprovider remove localai           # 移除自定义提供商\n\n\u002Fmodel                             # 显示当前模型（默认：gpt-oss）\n\u002Fmodel llama3.3                    # 切换到不同Ollama模型\n\u002Fmodel gpt-5                       # 切换到GPT-5（若使用OpenAI）\n\u002Fmodel claude-4-5-opus             # 切换到Claude 4.5（若使用Anthropic）\n\u002Fmodels                            # 列出当前提供商可用的模型\n```\n\n#### 工具管理\n```bash\n\u002Ftools                             # 列出可用工具\n\u002Ftools --all                       # 显示工具详细信息\n\u002Ftools --raw                       # 显示原始JSON定义\n\u002Ftools call                        # 交互式工具执行\n\n\u002Ftoolhistory                       # 显示工具执行历史\n\u002Fth -n 5                          # 最近5次工具调用\n\u002Fth 3                             # 第3次调用的详细信息\n\u002Fth --json                        # 完整历史记录为JSON\n```\n\n#### 服务器管理（运行时配置）\n```bash\n\u002Fserver                            # 列出所有已配置的服务器\n\u002Fserver list                       # 列出服务器（别名）\n\u002Fserver list all                   # 包括已禁用的服务器\n\n# 运行时添加服务器（持久化至~\u002F.mcp-cli\u002Fpreferences.json）\n\u002Fserver add \u003Cname> stdio \u003Ccommand> [args...]\n\u002Fserver add sqlite stdio uvx mcp-server-sqlite --db-path test.db\n\u002Fserver add playwright stdio npx @playwright\u002Fmcp@latest\n\u002Fserver add time stdio uvx mcp-server-time\n\u002Fserver add fs stdio npx @modelcontextprotocol\u002Fserver-filesystem \u002Fpath\u002Fto\u002Fdir\n\n# HTTP\u002FSSE服务器示例，带认证\n\u002Fserver add github --transport http --header \"Authorization: Bearer ghp_token\" -- https:\u002F\u002Fapi.github.com\u002Fmcp\n\u002Fserver add myapi --transport http --env API_KEY=secret -- https:\u002F\u002Fapi.example.com\u002Fmcp\n\u002Fserver add events --transport sse -- https:\u002F\u002Fevents.example.com\u002Fsse\n\n# 管理服务器状态\n\u002Fserver enable \u003Cname>              # 启用已禁用的服务器\n\u002Fserver disable \u003Cname>             # 禁用但不删除\n\u002Fserver remove \u003Cname>              # 删除用户添加的服务器\n\u002Fserver ping \u003Cname>                # 测试服务器连接性\n\n# 服务器详情\n\u002Fserver \u003Cname>                     # 显示服务器配置详情\n```\n\n**注意**：通过`\u002Fserver add`添加的服务器存储在`~\u002F.mcp-cli\u002Fpreferences.json`中，并在会话间保持。项目服务器则保存在`server_config.json`中。\n\n#### 多模态附件\n```bash\n\u002Fattach image.png                  # 为下一条消息暂存图片\n\u002Fattach code.py                    # 为下一条消息暂存文本文件\n\u002Fattach list                       # 显示当前暂存的文件\n\u002Fattach clear                      # 清空暂存文件\n\u002Ffile data.csv                     # \u002Fattach的别名\n\u002Fimage screenshot.heic             # \u002Fattach的别名\n\n# 在任何消息中内联引用文件\n@file:screenshot.png 描述你看到的内容\n@file:data.csv 总结这些数据\n\n# 图片URL自动检测\nhttps:\u002F\u002Fexample.com\u002Fphoto.jpg 这张图片里有什么？\n```\n\n#### 对话管理\n```bash\n\u002Fconversation                      # 显示对话历史\n\u002Fch -n 10                         # 最近10条消息\n\u002Fch 5                             # 第5条消息的详细信息\n\u002Fch --json                        # 完整历史记录为JSON\n\n\u002Fsave conversation.json            # 将对话保存到文件\n\u002Fcompact                          # 总结对话\n\u002Fclear                            # 清空对话历史\n\u002Fcls                              # 只清空屏幕\n```\n\n#### 界面定制\n```bash\n\u002Ftheme                            # 交互式主题选择器，带预览\n\u002Ftheme dark                       # 切换到暗色主题\n\u002Ftheme monokai                    # 切换到monokai主题\n\n# 可用主题：default、dark、light、minimal、terminal、monokai、dracula、solarized\n# 主题在会话间保持\n```\n\n#### 令牌管理\n```bash\n\u002Ftoken                            # 列出所有存储的令牌\n\u002Ftoken list                       # 显示所有显式存储的令牌\n\u002Ftoken set \u003Cname>                 # 存储Bearer令牌\n\u002Ftoken get \u003Cname>                 # 获取令牌详细信息\n\u002Ftoken delete \u003Cname>              # 删除一个令牌\n\u002Ftoken clear                      # 清空所有令牌（需确认）\n\u002Ftoken backends                   # 显示可用存储后端\n\n# 示例\n\u002Ftoken set my-api                 # 提示输入令牌值（安全）\n\u002Ftoken get notion --oauth         # 获取Notion服务器的OAuth令牌\n\u002Ftoken list --api-keys            # 只列出提供商的API密钥\n```\n\n**令牌存储后端：**\nMCP CLI支持多种安全令牌存储后端：\n- **Keychain**（macOS） - 使用macOS Keychain（macOS默认）\n- **Windows凭据管理器** - Windows原生存储（Windows默认）\n- **Secret Service** - Linux桌面密钥环（GNOME\u002FKDE）\n- **加密文件** - AES-256加密本地文件（跨平台后备）\n- **HashiCorp Vault** - 企业级密钥管理\n\n通过`--token-backend`覆盖默认后端：\n```bash\n# 使用加密文件存储代替Keychain\nmcp-cli --token-backend encrypted token list\n\n# 使用Vault用于企业环境\nmcp-cli --token-backend vault token list\n```\n\n更多详细说明请参阅[令牌管理指南](docs\u002FTOKEN_MANAGEMENT.md)。\n\n#### 会话控制\n```bash\n\u002Fverbose                          # 切换详细\u002F紧凑显示模式（默认：启用）\n\u002Fconfirm                          # 切换工具调用确认模式（默认：启用）\n\u002Finterrupt                        # 停止正在运行的操作\n\u002Fserver                           # 管理MCP服务器（见上文服务器管理）\n\u002Fhelp                            # 显示所有命令\n\u002Fhelp tools                       # 特定命令的帮助\n\u002Fexit                            # 退出聊天模式\n```\n\n**完整命令文档**请参阅[命令系统指南](docs\u002FCOMMANDS.md)。\n\n### 聊天功能\n\n#### 带推理过程可视化的流式响应\n- **🧠 推理模型**：通过 gpt-oss、GPT-5 和 Claude 4 查看 AI 的思考过程\n- **实时生成**：逐个 token 地观看文本逐步呈现\n- **性能指标**：每秒字数、响应时间\n- **优雅中断**：按 Ctrl+C 即可停止流式输出\n- **渐进渲染**：Markdown 格式随流式传输逐步显示\n\n#### 工具执行\n- 自动发现并使用工具\n- 并发执行并显示进度条\n- 提供详细与简洁两种显示模式\n- 完整的执行历史与耗时记录\n\n#### 多模态附件\n- 可向任意消息中添加图片、文本文件和音频\n- `\u002Fattach` 命令支持暂存、列表与清除（别名：`\u002Ffile`、`\u002Fimage`）\n- 在任意消息中内嵌 `@file:路径` 引用\n- `--attach` CLI 标志用于首次消息的附件\n- 浏览器“+”按钮支持拖放与剪贴板粘贴（配合 `--dashboard` 使用）\n- 仪表板可渲染缩略图、文本预览与音频播放器\n\n#### 供应商集成\n- 无缝切换不同供应商\n- 针对特定模型的优化\n- API 密钥与端点管理\n- 健康监测与诊断\n\n## 🖥️ 使用交互模式\n\n交互模式提供了一个命令行界面，用于直接与服务器交互。\n\n### 启动交互模式\n\n```bash\nmcp-cli interactive --server sqlite\n```\n\n### 交互命令\n\n```bash\nhelp                              # 显示可用命令\nexit                              # 退出交互模式\nclear                             # 清空终端\n\n# 供应商管理\nprovider                          # 显示当前供应商\nprovider list                     # 列出供应商\nprovider anthropic                # 切换供应商\nprovider openai gpt-5             # 切换到 GPT-5\n\n# 模型管理\nmodel                             # 显示当前模型\nmodel gpt-oss                     # 切换到推理模型\nmodel claude-4-5-opus             # 切换到 Claude 4.5\nmodels                            # 列出可用模型\n\n# 工具操作\ntools                             # 列出工具\ntools --all                       # 详细工具信息\ntools call                        # 交互式工具执行\n\n# 服务器操作\nservers                           # 列出服务器\nping                              # Ping 所有服务器\nresources                         # 列出资源\nprompts                           # 列出提示词\n```\n\n## 📄 使用命令模式\n\n命令模式提供了类 Unix 的自动化能力。\n\n### 命令模式选项\n\n```bash\n--input FILE                      # 输入文件（- 表示标准输入）\n--output FILE                     # 输出文件（- 表示标准输出）\n--prompt TEXT                     # 提示模板\n--tool TOOL                       # 执行特定工具\n--tool-args JSON                  # 工具参数，以 JSON 格式传递\n--system-prompt TEXT              # 自定义系统提示\n--raw                             # 不进行格式化，直接输出原始内容\n--single-turn                     # 禁用多轮对话\n--max-turns N                     # 对话最大轮次\n```\n\n### 示例\n\n```bash\n# 使用推理模型处理文本\necho \"分析这些数据\" | mcp-cli cmd --server sqlite --model gpt-oss --input - --output analysis.txt\n\n# 使用 GPT-5 进行复杂分析\nmcp-cli cmd --server sqlite --provider openai --model gpt-5 --prompt \"提供战略分析\" --input report.txt\n\n# 工具执行\nmcp-cli cmd --server sqlite --tool list_tables --raw\n\n# 复杂查询\nmcp-cli cmd --server sqlite --tool read_query --tool-args '{\"query\": \"SELECT COUNT(*) FROM users\"}'\n\n# 使用 GNU Parallel 进行批量处理\nls *.txt | parallel mcp-cli cmd --server sqlite --input {} --output {}.summary --prompt \"总结: {{input}}\"\n```\n\n## 🔧 供应商配置\n\n### Ollama 配置（默认）\n\nOllama 默认在本地运行于 `http:\u002F\u002Flocalhost:11434`。MCP CLI v0.11.1+ 与 CHUK-LLM v0.16+ 包含 **llama.cpp 集成**，可自动发现并复用 Ollama 下载的模型，实现 1.53 倍更快的推理速度（311 vs 204 tokens\u002F秒），且无需重新下载。\n\n要使用推理及其他模型：\n\n```bash\n# 拉取推理及其他模型至 Ollama\nollama pull gpt-oss          # 默认推理模型\nollama pull llama3.3         # 最新 Llama\nollama pull llama3.2         # Llama 3.2\nollama pull qwen3            # Qwen 3\nollama pull qwen2.5-coder    # 编码专注型\nollama pull deepseek-coder   # DeepSeek coder\nollama pull granite3.3       # IBM Granite\nollama pull mistral          # Mistral\nollama pull gemma3           # Google Gemma\nollama pull phi3             # Microsoft Phi\nollama pull codellama        # Code Llama\n\n# 列出可用 Ollama 模型\nollama list\n\n# 配置远程 Ollama 服务器\nmcp-cli provider set ollama api_base http:\u002F\u002Fremote-server:11434\n```\n\n### 云供应商配置\n\n要使用云供应商的高级模型，请配置 API 密钥：\n\n```bash\n# 配置 OpenAI（用于 GPT-5、GPT-4、O3 模型）\nmcp-cli provider set openai api_key sk-your-key-here\n\n# 配置 Anthropic（用于 Claude 4.5、Claude 3.5）\nmcp-cli provider set anthropic api_key sk-ant-your-key-here\n\n# 配置 Azure OpenAI（用于企业级 GPT-5）\nmcp-cli provider set azure_openai api_key sk-your-key-here\nmcp-cli provider set azure_openai api_base https:\u002F\u002Fyour-resource.openai.azure.com\n\n# 配置其他供应商\nmcp-cli provider set gemini api_key your-gemini-key\nmcp-cli provider set groq api_key your-groq-key\n\n# 测试配置\nmcp-cli provider diagnostic openai\nmcp-cli provider diagnostic anthropic\n```\n\n### 自定义 OpenAI 兼容供应商\n\nMCP CLI 支持添加自定义 OpenAI 兼容供应商（LocalAI、自定义代理等）：\n\n```bash\n# 添加自定义供应商（会话间持久化）\nmcp-cli provider add localai http:\u002F\u002Flocalhost:8080\u002Fv1 gpt-4 gpt-3.5-turbo\nmcp-cli provider add myproxy https:\u002F\u002Fproxy.example.com\u002Fv1 custom-model-1 custom-model-2\n\n# 通过环境变量设置 API 密钥（不会存储在配置中）\nexport LOCALAI_API_KEY=your-api-key\nexport MYPROXY_API_KEY=your-api-key\n\n# 列出自定义供应商\nmcp-cli provider custom\n\n# 使用自定义供应商\nmcp-cli --provider localai --server sqlite\nmcp-cli --provider myproxy --model custom-model-1 --server sqlite\n\n# 删除自定义供应商\nmcp-cli provider remove localai\n\n# 运行时供应商（仅限本次会话，不持久化）\nmcp-cli --provider temp-ai --api-base https:\u002F\u002Fapi.temp.com\u002Fv1 --api-key test-key --server sqlite\n```\n\n**安全提示**：API 密钥可安全地存储在操作系统原生密钥链中（macOS Keychain、Windows Credential Manager、Linux Secret Service）或 HashiCorp Vault 中，利用令牌管理系统进行存储。此外，也可使用环境变量，遵循 `{供应商名称}_API_KEY` 格式，或通过 `--api-key` 传递以仅限本次会话使用。详情请参阅 [令牌管理](docs\u002FTOKEN_MANAGEMENT.md)。\n\n### 手动配置\n\n`~\u002F.chuk_llm\u002Fconfig.yaml` 中的 `chuk_llm` 库配置：\n\n```yaml\nollama:\n  api_base: http:\u002F\u002Flocalhost:11434\n  default_model: gpt-oss\n\nopenai:\n  api_base: https:\u002F\u002Fapi.openai.com\u002Fv1\n  default_model: gpt-5\n\nanthropic:\n  api_base: https:\u002F\u002Fapi.anthropic.com\n  default_model: claude-4-5-opus\n\nazure_openai:\n  api_base: https:\u002F\u002Fyour-resource.openai.azure.com\n  default_model: gpt-5\n\ngemini:\n  api_base: https:\u002F\u002Fgenerativelanguage.googleapis.com\n  default_model: gemini-2.0-flash\n\ngroq:\n  api_base: https:\u002F\u002Fapi.groq.com\n  default_model: llama-3.1-70b\n```\n\n可通过以下方式提供 API 密钥：\n1. **安全令牌存储**（推荐）—— 存储在操作系统密钥链\u002F保险库中，参见[令牌管理](docs\u002FTOKEN_MANAGEMENT.md)\n2. **环境变量**—— 在您的 Shell 中导出或添加到 `~\u002F.chuk_llm\u002F.env`：\n\n```bash\nOPENAI_API_KEY=sk-your-key-here\nANTHROPIC_API_KEY=sk-ant-your-key-here\nAZURE_OPENAI_API_KEY=sk-your-azure-key-here\nGEMINI_API_KEY=your-gemini-key\nGROQ_API_KEY=your-groq-key\n```\n\n3. **命令行**—— 通过 `--api-key` 传递，仅用于当前会话（不持久化）\n\n## 📂 服务器配置\n\nMCP CLI 支持两种类型的服务器配置：\n\n1. **项目服务器** (`server_config.json`)：共享的项目级配置\n2. **用户服务器** (`~\u002F.mcp-cli\u002Fpreferences.json`)：个人运行时添加的服务器，跨会话持久化\n\n### 配置文件发现\n\nMCP CLI 按以下优先级顺序查找 `server_config.json`：\n\n1. **显式路径**，通过 `--config-file` 选项指定：\n   ```bash\n   mcp-cli --config-file \u002Fpath\u002Fto\u002Fcustom-config.json\n   ```\n\n2. **当前目录**—— 当从项目目录运行时自动检测：\n   ```bash\n   cd \u002Fpath\u002Fto\u002Fmy-project\n   mcp-cli --server sqlite    # 如果存在 .\u002Fserver_config.json，则使用该文件\n   ```\n\n3. **内置默认值**—— 当通过 `uvx` 运行或从任何没有本地配置的目录运行时：\n   ```bash\n   uvx mcp-cli --server cloudflare_workers    # 使用打包的 server_config.json\n   ```\n\n这意味着您可以：\n- **覆盖每个项目**：在项目目录中放置一个 `server_config.json`，包含特定于项目的服务器配置\n- **全局使用默认值**：从任意位置运行 `uvx mcp-cli`，获取内置默认服务器\n- **明确自定义**：使用 `--config-file` 指定任意配置文件位置\n\n### 内置默认服务器\n\nMCP CLI v0.11.1+ 在内置的 `server_config.json` 中附带了一组扩展的预配置服务器：\n\n| 服务器 | 类型 | 描述 | 配置 |\n|--------|------|-------------|---------------|\n| **sqlite** | STDIO | SQLite 数据库操作 | `uvx mcp-server-sqlite --db-path test.db` |\n| **echo** | STDIO | 测试用回声服务器 | `uvx chuk-mcp-echo stdio` |\n| **math** | STDIO | 数学计算 | `uvx chuk-mcp-math-server` |\n| **playwright** | STDIO | 浏览器自动化 | `npx @playwright\u002Fmcp@latest` |\n| **brave_search** | STDIO | 通过 Brave API 的网页搜索 | 需要 `BRAVE_API_KEY` 令牌 |\n| **notion** | HTTP | Notion 工作区集成 | `https:\u002F\u002Fmcp.notion.com\u002Fmcp` (OAuth) |\n| **cloudflare_workers** | HTTP | Cloudflare Workers 绑定 | `https:\u002F\u002Fbindings.mcp.cloudflare.com\u002Fmcp` (OAuth) |\n| **monday** | HTTP | Monday.com 集成 | `https:\u002F\u002Fmcp.monday.com\u002Fmcp` (OAuth) |\n| **linkedin** | HTTP | LinkedIn 集成 | `https:\u002F\u002Flinkedin.chukai.io\u002Fmcp` |\n| **weather** | HTTP | 天气数据服务 | `https:\u002F\u002Fweather.chukai.io\u002Fmcp` |\n\n**注意**：HTTP 服务器和基于 API 的服务器需要认证。请使用[令牌管理](docs\u002FTOKEN_MANAGEMENT.md)系统配置访问令牌。\n\n要使用这些服务器：\n```bash\n# 从任意位置使用内置服务器\nuvx mcp-cli --server sqlite\nuvx mcp-cli --server echo\nuvx mcp-cli --server math\nuvx mcp-cli --server playwright\n\n# 基于 API 的服务器需要令牌\nmcp-cli token set brave_search --type bearer\nuvx mcp-cli --server brave_search\n\n# HTTP\u002FOAuth 服务器需要 OAuth 认证\nuvx mcp-cli token set notion --oauth\nuvx mcp-cli --server notion\n\n# 同时使用多个服务器\nuvx mcp-cli --server sqlite,math,playwright\n```\n\n### 项目配置\n\n创建一个包含 MCP 服务器配置的 `server_config.json` 文件：\n\n```json\n{\n  \"mcpServers\": {\n    \"sqlite\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"mcp_server.sqlite_server\"],\n      \"env\": {\n        \"DATABASE_PATH\": \"database.db\"\n      }\n    },\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol\u002Fserver-filesystem\", \"\u002Fpath\u002Fto\u002Fallowed\u002Ffiles\"],\n      \"env\": {}\n    },\n    \"brave-search\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@brave\u002Fbrave-search-mcp-server\"],\n      \"env\": {\n        \"BRAVE_API_KEY\": \"${TOKEN:bearer:brave_search}\"\n      }\n    },\n    \"notion\": {\n      \"url\": \"https:\u002F\u002Fmcp.notion.com\u002Fmcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer ${TOKEN:bearer:notion}\"\n      }\n    }\n  }\n}\n```\n\n### 安全令牌替换\n\nMCP CLI 支持从安全存储自动替换令牌，使用 `${TOKEN:namespace:name}` 语法：\n\n**语法**：`${TOKEN:\u003Cnamespace>:\u003Ctoken-name>}`\n\n**示例**：\n```json\n{\n  \"mcpServers\": {\n    \"brave-search\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@brave\u002Fbrave-search-mcp-server\"],\n      \"env\": {\n        \"BRAVE_API_KEY\": \"${TOKEN:bearer:brave_search}\"\n      }\n    },\n    \"api-server\": {\n      \"url\": \"https:\u002F\u002Fapi.example.com\u002Fmcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer ${TOKEN:bearer:my_api}\",\n        \"X-API-Key\": \"${TOKEN:api-key:my_service}\"\n      }\n    }\n  }\n}\n```\n\n**令牌存储**：\n```bash\n# 安全存储令牌（绝不在配置文件中）\nmcp-cli token set brave_search --type bearer\n# 根据提示输入令牌值（隐藏输入）\n\nmcp-cli token set my_api --type bearer --value \"your-token-here\"\n\n# 令牌存储在操作系统原生安全存储中：\n# - macOS：钥匙串\n# - Windows：凭据管理器\n# - Linux：Secret Service（GNOME Keyring\u002FKWallet）\n```\n\n**支持的位置**：\n- `env`：适用于 STDIO 服务器的环境变量\n- `headers`：适用于 HTTP\u002FSSE 服务器的 HTTP 头部\n\n**命名空间**：\n- `bearer`：Bearer 令牌（默认为 `--type bearer`）\n- `api-key`：API 密钥（默认为 `--type api-key`）\n- `oauth`：OAuth 令牌（自动）\n- `generic`：自定义令牌\n\n**优势**：\n- ✅ 绝不在配置文件中存储 API 密钥\n- ✅ 安全共享 `server_config.json`（无敏感信息）\n- ✅ 令牌加密存储在操作系统原生安全存储中\n- ✅ 适用于所有传输类型（STDIO、HTTP、SSE）\n\n完整文档请参阅[令牌管理指南](docs\u002FTOKEN_MANAGEMENT.md)。\n\n### 运行时服务器管理\n\n在运行时动态添加服务器，无需编辑配置文件：\n\n```bash\n# 添加 STDIO 服务器（最常见）\nmcp-cli\n> \u002Fserver add sqlite stdio uvx mcp-server-sqlite --db-path mydata.db\n> \u002Fserver add playwright stdio npx @playwright\u002Fmcp@latest\n> \u002Fserver add time stdio uvx mcp-server-time\n\n# 添加带身份验证的HTTP服务器\n> \u002Fserver add github --transport http --header \"Authorization: Bearer ghp_token\" -- https:\u002F\u002Fapi.github.com\u002Fmcp\n> \u002Fserver add myapi --transport http --env API_KEY=secret -- https:\u002F\u002Fapi.example.com\u002Fmcp\n\n# 添加SSE（服务器发送事件）服务器\n> \u002Fserver add events --transport sse -- https:\u002F\u002Fevents.example.com\u002Fsse\n\n# 管理服务器\n> \u002Fserver list                     # 显示所有服务器\n> \u002Fserver disable sqlite           # 临时禁用\n> \u002Fserver enable sqlite            # 重新启用\n> \u002Fserver remove myapi             # 移除用户添加的服务器\n\n**要点：**\n- 用户添加的服务器会持久化保存在~\u002F.mcp-cli\u002Fpreferences.json中\n- 即使应用重启也能保留\n- 可以在不移除的情况下启用\u002F禁用\n- 支持STDIO、HTTP和SSE传输方式\n- 支持环境变量和头部信息进行身份验证\n\n## 📈 高级使用示例\n\n### 推理模型对比\n\n```bash\n# 对比不同模型的推理过程\n> \u002Fprovider ollama\n> \u002Fmodel gpt-oss\n> 逐步思考这个问题：如果一列火车下午3点从纽约出发……\n[查看gpt-oss的完整思考过程]\n\n> \u002Fprovider openai\n> \u002Fmodel gpt-5\n> 逐步思考这个问题：如果一列火车下午3点从纽约出发……\n[查看GPT-5的推理思路]\n\n> \u002Fprovider anthropic\n> \u002Fmodel claude-4-5-opus\n> 逐步思考这个问题：如果一列火车下午3点从纽约出发……\n[查看Claude 4.5的分析过程]\n```\n\n### 基于推理的本地优先工作流\n\n```bash\n# 从默认的Ollama\u002Fgpt-oss开始（无需API密钥）\nmcp-cli chat --server sqlite\n\n# 对复杂问题使用推理模型\n> 逐步思考这个数据库优化问题\n[gpt-oss展示其完整的思考过程后再作答]\n\n# 对不同任务尝试不同的本地模型\n> \u002Fmodel llama3.3              # 通用型\n> \u002Fmodel qwen2.5-coder         # 用于编码任务\n> \u002Fmodel deepseek-coder        # 替代编码模型\n> \u002Fmodel granite3.3            # IBM的模型\n> \u002Fmodel gpt-oss               # 回到推理模型\n\n# 需要时切换到云端（需提供API密钥）\n> \u002Fprovider openai\n> \u002Fmodel gpt-5\n> 复杂的企业架构设计……\n\n> \u002Fprovider anthropic\n> \u002Fmodel claude-4-5-opus\n> 详细的战略分析……\n\n> \u002Fprovider ollama\n> \u002Fmodel gpt-oss\n> 继续本地处理……\n```\n\n### 多提供商工作流\n\n```bash\n# 从本地推理开始（默认，无需API密钥）\nmcp-cli chat --server sqlite\n\n# 对比不同提供商的响应\n> \u002Fprovider ollama\n> 优化这个SQL查询的最佳方法是什么？\n\n> \u002Fprovider openai gpt-5        # 需要API密钥\n> 优化这个SQL查询的最佳方法是什么？\n\n> \u002Fprovider anthropic claude-4-5-sonnet  # 需要API密钥\n> 优化这个SQL查询的最佳方法是什么？\n\n# 发挥各提供商的优势\n> \u002Fprovider ollama gpt-oss      # 本地推理，隐私保护\n> \u002Fprovider openai gpt-5        # 高级推理\n> \u002Fprovider anthropic claude-4-5-opus  # 深度分析\n> \u002Fprovider groq llama-3.1-70b  # 超快响应\n```\n\n### 带推理的复杂工具工作流\n\n```bash\n# 对复杂数据库任务使用推理模型\n> \u002Fmodel gpt-oss\n> 我需要分析我们的数据库性能。先想想应该检查什么。\n\n[gpt-oss展示思考过程：“首先，我应该检查表结构，然后是索引，再看查询模式……”]\n[工具：list_tables] → products, customers, orders\n\n> 现在分析索引并提出优化建议\n[gpt-oss思考索引分析过程]\n[工具：describe_table] → 展示当前索引\n[工具：read_query] → 分析查询模式\n\n> 根据你的分析制定优化方案\n[完整的推理过程及具体建议]\n```\n\n### 自动化与脚本编写\n\n```bash\n# 使用不同模型进行批量处理\nfor file in data\u002F*.csv; do\n  # 使用推理模型进行分析\n  mcp-cli cmd --server sqlite \\\n    --model gpt-oss \\\n    --prompt \"分析这些数据并思考其中的规律\" \\\n    --input \"$file\" \\\n    --output \"analysis\u002F$(basename \"$file\" .csv)_reasoning.txt\"\n  \n  # 使用编码模型生成脚本\n  mcp-cli cmd --server sqlite \\\n    --model qwen2.5-coder \\\n    --prompt \"生成Python代码来处理这些数据\" \\\n    --input \"$file\" \\\n    --output \"scripts\u002F$(basename \"$file\" .csv)_script.py\"\ndone\n\n# 带推理的流水线\ncat complex_problem.txt | \\\n  mcp-cli cmd --model gpt-oss --prompt \"逐步思考\" --input - | \\\n  mcp-cli cmd --model llama3.3 --prompt \"总结关键点\" --input - > solution.txt\n```\n\n### 性能监控\n\n```bash\n# 检查提供商和模型的性能\n> \u002Fprovider diagnostic\n提供商诊断\n提供商      | 状态      | 响应时间 | 功能      | 模型\nollama        | ✅ 就绪    | 56ms         | 📡🔧         | gpt-oss, llama3.3, qwen3, ...\nopenai        | ✅ 就绪    | 234ms        | 📡🔧👁️      | gpt-5, gpt-4o, o3, ...\nanthropic     | ✅ 就绪    | 187ms        | 📡🔧         | claude-4-5-opus, claude-4-5-sonnet, ...\nazure_openai  | ✅ 就绪    | 198ms        | 📡🔧👁️      | gpt-5, gpt-4o, ...\ngemini        | ✅ 就绪    | 156ms        | 📡🔧👁️      | gemini-2.0-flash, ...\ngroq          | ✅ 就绪    | 45ms         | 📡🔧         | llama-3.1-70b, ...\n\n# 查看可用模型\n> \u002Fmodels\n适用于ollama的模型（当前提供商）\n模型                | 状态\ngpt-oss             | 当前及默认（推理）\nllama3.3            | 可用\nllama3.2            | 可用\nqwen2.5-coder       | 可用\ndeepseek-coder      | 可用\ngranite3.3          | 可用\n...还有6个更多\n\n# 监控带推理的工具执行\n> \u002Fverbose\n> \u002Fmodel gpt-oss\n> 分析数据库并优化最慢的查询\n[显示完整的思考过程]\n[工具执行并计时]\n```\n\n## 🔍 故障排除\n\n### 常见问题\n\n1. **Ollama 未运行**（默认提供者）：\n   ```bash\n   # 启动 Ollama 服务\n   ollama serve\n   \n   # 或者检查是否正在运行\n   curl http:\u002F\u002Flocalhost:11434\u002Fapi\u002Ftags\n   ```\n\n2. **模型未找到**：\n   ```bash\n   # 对于 Ollama（默认），先拉取模型\n   ollama pull gpt-oss      # 理论推理模型\n   ollama pull llama3.3     # 最新 Llama 模型\n   ollama pull qwen2.5-coder # 编码模型\n   \n   # 列出可用模型\n   ollama list\n   \n   # 对于云提供商，查看支持的模型\n   mcp-cli models openai     # 显示 GPT-5、GPT-4、O3 模型\n   mcp-cli models anthropic  # 显示 Claude 4.5、Claude 3.5 模型\n   ```\n\n3. **提供者未找到或 API 密钥缺失**：\n   ```bash\n   # 查看可用提供者\n   mcp-cli provider list\n   \n   # 对于云提供商，设置 API 密钥\n   mcp-cli provider set openai api_key sk-your-key\n   mcp-cli provider set anthropic api_key sk-ant-your-key\n   \n   # 测试连接\n   mcp-cli provider diagnostic openai\n   ```\n\n4. **与 Ollama 的连接问题**：\n   ```bash\n   # 检查 Ollama 是否正在运行\n   ollama list\n   \n   # 测试连接\n   mcp-cli provider diagnostic ollama\n   \n   # 如需自定义端点，可进行配置\n   mcp-cli provider set ollama api_base http:\u002F\u002Flocalhost:11434\n   ```\n\n### 调试模式\n\n启用详细日志记录以进行故障排除：\n\n```bash\nmcp-cli --verbose chat --server sqlite\nmcp-cli --log-level DEBUG interactive --server sqlite\n\n# 将调试日志写入轮转文件（密钥自动脱敏）\nmcp-cli --log-file ~\u002F.mcp-cli\u002Flogs\u002Fdebug.log --server sqlite\n```\n\n## 🔒 安全考虑\n\n### 隐私与本地优先\n- **默认本地运行**：Ollama 与 gpt-oss 在本地运行，确保您的数据隐私\n- **无需云端**：完全功能无需外部 API 依赖\n\n### 令牌与认证安全\n- **安全令牌存储**：令牌存储在操作系统原生凭据存储中（macOS Keychain、Windows Credential Manager、Linux Secret Service），标识为“mcp-cli”服务\n- **多种存储后端**：根据安全需求，可选择钥匙串、加密文件或 HashiCorp Vault\n- **API 密钥**：仅对云提供商（OpenAI、Anthropic 等）需要，使用令牌管理系统安全存储\n- **OAuth 2.0 支持**：使用 PKCE 和资源指示器（RFC 7636、RFC 8707）为 MCP 服务器提供安全认证\n\n### 日志安全\n- **密钥脱敏**：所有日志输出（控制台和文件）自动脱敏 Bearer 令牌、API 密钥（sk-*）、OAuth 访问令牌和授权头\n- **轮转文件日志**：可选 `--log-file` 以 JSON 格式记录，10MB 轮转，保留 3 个备份文件\n\n### 执行安全\n- **工具验证**：所有工具调用在执行前均经过验证\n- **超时保护**：可配置超时防止操作挂起（v0.13+）\n- **熔断器**：自动检测并恢复失败，防止级联故障（v0.13+）\n- **服务器隔离**：每个服务器独立运行\n- **文件访问**：可通过 `--disable-filesystem` 禁用文件系统访问\n- **传输监控**：自动检测连接失败并发出警告（v0.11+）\n\n### MCP 应用程序安全\n- **iframe 沙箱**：应用程序在沙箱 iframe 中运行，权限受限\n- **内容安全策略**：服务器提供的 CSP 域名经过验证和净化\n- **XSS 防护**：工具名称和用户输入内容在模板注入前进行 HTML 转义\n- **URL 方案验证**：`ui\u002Fopen-link` 仅允许 `http:\u002F\u002F` 和 `https:\u002F\u002F` 方案\n- **工具名称验证**：桥接拒绝不符合 MCP 规范字符集的工具名称\n\n## 🚀 性能特性\n\n### LLM 提供者性能（v0.16+）\n- **导入速度提升 52 倍**：通过懒加载，从 735ms 降至 14ms\n- **客户端创建速度提升 112 倍**：自动线程安全缓存\n- **llama.cpp 集成**：推理速度提升 1.53 倍（311 vs 204 tokens\u002Fsec），自动复用 Ollama 模型\n- **动态模型发现**：零开销基于能力的模型选择\n\n### 工具执行性能（v0.13+）\n- **生产中间件**：超时、重试指数退避、熔断器和结果缓存\n- **并发工具执行**：多个工具可同时运行并协调\n- **连接健康监控**：自动检测并恢复传输失败\n- **优化工具管理器**：从 2000+ 行减少至约 800 行，同时保持全部功能\n\n### 运行时性能\n- **本地处理**：默认 Ollama 提供者最小化延迟\n- **推理可见性**：通过 gpt-oss、GPT-5、Claude 4 可查看 AI 思考过程\n- **流式响应**：实时响应生成\n- **连接池**：高效复用客户端连接\n- **缓存**：工具元数据和提供者配置被缓存\n- **异步架构**：全程非阻塞操作\n\n## 📦 依赖项\n\n核心依赖项按功能分组：\n\n- **cli**：终端 UI 和命令框架（Rich、Typer、chuk-term）\n- **dev**：开发工具、测试实用程序、代码检查\n- **chuk-tool-processor v0.22+**：生产级工具执行，带中间件、多种执行策略和可观测性\n- **chuk-llm v0.17+**：统一 LLM 提供者，支持动态模型发现、基于能力的选择和 llama.cpp 集成\n- **chuk-term**：增强终端 UI，支持主题、提示和跨平台\n\n安装特定功能：\n```bash\npip install \"mcp-cli[cli]\"        # 基本 CLI 功能\npip install \"mcp-cli[cli,dev]\"    # 带开发工具的 CLI\npip install \"mcp-cli[apps]\"       # MCP 应用程序（交互式浏览器 UI）\n```\n\n## 🤝 贡献\n\n我们欢迎贡献！请参阅我们的 [贡献指南](CONTRIBUTING.md) 了解详情。\n\n### 开发环境搭建\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fmcp-cli\ncd mcp-cli\npip install -e \".[cli,dev]\"\npre-commit install\n```\n\n### 演示脚本\n\n探索 MCP CLI 的各项功能：\n\n```bash\n# 命令模式演示\n\n# 通用命令模式功能（bash）\nbash examples\u002Fcmd_mode_demo.sh\n\n# 命令模式与 LLM 集成（bash）\nbash examples\u002Fcmd_mode_llm_demo.sh\n\n# Python 集成示例\nuv run examples\u002Fcmd_mode_python_demo.py\n\n# 自定义提供者管理演示\n\n# 交互式 walkthrough 演示（教育用途）\nuv run examples\u002Fcustom_provider_demo.py\n\n# 实际推理工作演示（需 OPENAI_API_KEY）\nuv run examples\u002Fcustom_provider_working_demo.py\n\n# 简单 Shell 脚本演示（需 OPENAI_API_KEY）\nbash examples\u002Fcustom_provider_simple_demo.sh\n\n# 终端管理功能（chuk-term）\nuv run examples\u002Fui_terminal_demo.py\n\n# 输出系统与主题（chuk-term）\nuv run examples\u002Fui_output_demo.py\n\n# 流式 UI 能力（chuk-term）\nuv run examples\u002Fui_streaming_demo.py\n```\n\n### 运行测试\n\n```bash\npytest\npytest --cov=mcp_cli --cov-report=html\n```\n\n## 📜 许可证\n\n本项目采用 Apache License 2.0 许可证——详情请参阅 [LICENSE](LICENSE) 文件。\n\n## 🙏 感谢\n\n- **[CHUK 工具处理器](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fchuk-tool-processor)** - 带中间件和可观测性的生产级异步工具执行框架\n- **[CHUK-LLM](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fchuk-llm)** - 统一的大型语言模型提供商，支持动态模型发现、llama.cpp 集成以及 GPT-5 和 Claude 4.5（v0.17+）\n- **[CHUK-Term](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fchuk-term)** - 增强型终端 UI，支持主题和跨平台\n- **[Rich](https:\u002F\u002Fgithub.com\u002FTextualize\u002Frich)** - 美丽的终端格式化工具\n- **[Typer](https:\u002F\u002Ftyper.tiangolo.com\u002F)** - 命令行界面框架\n- **[Prompt Toolkit](https:\u002F\u002Fgithub.com\u002Fprompt-toolkit\u002Fpython-prompt-toolkit)** - 交互式输入工具\n\n## 🔗 相关项目\n\n- **[模型上下文协议](https:\u002F\u002Fmodelcontextprotocol.io\u002F)** - 核心协议规范\n- **[MCP 服务器](https:\u002F\u002Fgithub.com\u002Fmodelcontextprotocol\u002Fservers)** - MCP 官方服务器实现\n- **[CHUK 工具处理器](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fchuk-tool-processor)** - 带中间件和可观测性的生产级工具执行框架\n- **[CHUK-LLM](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fchuk-llm)** - 大型语言模型提供商抽象层，支持动态模型发现、GPT-5、Claude 4.5、O3 系列以及 llama.cpp 集成\n- **[CHUK-Term](https:\u002F\u002Fgithub.com\u002Fchrishayuk\u002Fchuk-term)** - 终端 UI 库，支持主题和跨平台","# MCP CLI 快速上手指南\n\nMCP CLI 是一个功能强大的命令行工具，用于与模型上下文协议（Model Context Protocol）服务器交互。它支持本地隐私优先的运行模式（默认集成 Ollama），并提供对话管理、工具调用、执行计划及多模态附件等高级功能。\n\n## 环境准备\n\n在开始之前，请确保您的系统满足以下要求：\n\n*   **操作系统**：Linux, macOS, 或 Windows (WSL 推荐)。\n*   **Python 版本**：Python 3.10 或更高版本。\n*   **本地模型运行器（可选但推荐）**：\n    *   若需使用默认的本地隐私模式，请安装 [Ollama](https:\u002F\u002Follama.com\u002F)。\n    *   国内用户可访问 Ollama 中国镜像或社区加速方案进行安装。\n    *   拉取默认推理模型：\n        ```bash\n        ollama pull gpt-oss\n        ```\n        *(注：若 `gpt-oss` 获取困难，可替换为 `llama3.3` 或其他本地模型，并在运行时指定)*\n\n## 安装步骤\n\n推荐使用 pip 进行安装。国内开发者建议使用清华或阿里镜像源以加速下载。\n\n**使用官方源安装：**\n```bash\npip install mcp-cli\n```\n\n**使用国内镜像源安装（推荐）：**\n```bash\npip install mcp-cli -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple\n```\n\n安装完成后，可通过以下命令验证版本：\n```bash\nmcp-cli --version\n```\n\n## 基本使用\n\n### 1. 启动聊天模式（默认配置）\n\n默认情况下，MCP CLI 会自动连接本地 Ollama 服务并使用 `gpt-oss` 推理模型。无需配置 API Key 即可开始对话。\n\n```bash\nmcp-cli\n```\n\n进入交互界面后，您可以直接输入自然语言问题。系统会自动发现并调用可用的工具。\n\n### 2. 指定模型或提供商\n\n如果您想使用其他模型（如 `llama3.3`）或云端提供商（如 OpenAI），可以在启动时通过参数指定：\n\n```bash\n# 使用特定的 Ollama 模型\nmcp-cli --model llama3.3\n\n# 使用 OpenAI 提供商 (需预先配置环境变量 OPENAI_API_KEY)\nmcp-cli --provider openai --model gpt-4o\n```\n\n### 3. 常用交互命令\n\n在聊天界面中，可以使用以下斜杠命令增强体验：\n\n*   **查看令牌用量**：\n    ```text\n    \u002Fusage\n    ```\n*   **添加多模态附件**（图片、代码文件等）：\n    ```text\n    \u002Fattach path\u002Fto\u002Fimage.png\n    ```\n    或者在消息中直接引用：\n    ```text\n    请分析这张图片 @file:path\u002Fto\u002Fimage.png\n    ```\n*   **执行计划管理**（创建和运行多步任务计划）：\n    ```text\n    \u002Fplan create 帮我分析当前目录下的所有 Python 文件并生成报告\n    ```\n*   **导出对话**：\n    ```text\n    \u002Fexport conversation.md\n    ```\n\n### 4. 启用实时仪表盘（可选）\n\n若希望获得可视化的浏览器界面，实时监控对话流、工具调用和执行计划，可添加 `--dashboard` 标志启动：\n\n```bash\nmcp-cli --dashboard\n```\n启动后，终端会提供一个本地 URL，在浏览器中打开即可看到包含消息气泡、令牌统计和 DAG 执行图的交互式面板。\n\n### 5. 脚本化\u002F非交互模式\n\n适用于自动化脚本或管道操作：\n\n```bash\necho \"列出当前目录文件\" | mcp-cli --mode command\n```","某数据工程师需要在本地隐私环境下，指挥 AI 自动执行包含数据抓取、清洗及可视化报表生成的复杂多步任务。\n\n### 没有 mcp-cli 时\n- **上下文受限**：处理长文档或大量历史对话时，因缺乏虚拟内存机制，早期关键信息常被强制丢弃，导致 AI“失忆”无法连贯分析。\n- **流程脆弱**：多步骤任务需人工逐个发送指令，一旦中间环节（如 API 调用）失败，整个流程中断且难以从断点恢复。\n- **结果抽象**：生成的图表或地图仅能以静态文本描述呈现，无法直接在浏览器中交互查看，验证效率极低。\n- **安全隐患**：调试日志中容易明文泄露 API Key 或 OAuth 令牌，存在严重的凭证泄露风险。\n\n### 使用 mcp-cli 后\n- **智能记忆管理**：启用 `--vm` 标志后，mcp-cli 像操作系统一样管理对话上下文，自动将旧数据换出到磁盘，确保 AI 在处理海量数据时依然记得初始需求。\n- **自动化执行计划**：通过 `\u002Fplan` 命令或模型自主规划，mcp-cli 自动生成有向无环图（DAG）并行执行任务；若某步失败，可自动重试或利用检查点功能从断点续跑。\n- **交互式可视化**：触发带有 UI 标注的工具时，mcp-cli 自动在浏览器沙箱中打开动态仪表盘，工程师可实时缩放地图或筛选表格数据。\n- **生产级安全**：内置的脱敏机制自动过滤日志中的敏感令牌，配合结构化文件日志，让合规审计变得轻松无忧。\n\nmcp-cli 通过将操作系统级的内存管理与自动化工作流引入本地 AI 交互，彻底解决了长任务易中断、上下文易丢失及结果难验证的核心痛点。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FIBM_mcp-cli_0f735789.png","IBM","International Business Machines","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002FIBM_251be740.jpg","Open Source @ IBM","ibmdeveloper","https:\u002F\u002Fwww.ibm.com\u002Fopensource\u002F","https:\u002F\u002Fgithub.com\u002FIBM",[83,87,91,94,98],{"name":84,"color":85,"percentage":86},"Python","#3572A5",94.8,{"name":88,"color":89,"percentage":90},"HTML","#e34c26",2.3,{"name":92,"color":93,"percentage":23},"JavaScript","#f1e05a",{"name":95,"color":96,"percentage":97},"CSS","#663399",0.7,{"name":99,"color":100,"percentage":101},"Makefile","#427819",0.2,1936,297,"2026-04-05T03:14:36","Apache-2.0","Linux, macOS, Windows","非必需（默认使用 Ollama 运行本地模型，支持 CPU；若使用特定高性能模型或 llama.cpp 加速可能受益于 GPU，但 README 未指定具体型号或显存要求）","未说明（取决于所选用的本地大语言模型大小，默认配置为 Ollama）",{"notes":110,"python":111,"dependencies":112},"该工具是一个命令行接口（CLI），主要用于连接 MCP 服务器和本地\u002F云端 LLM。默认配置推荐使用 Ollama 运行本地模型（如 gpt-oss），无需 API 密钥且注重隐私。支持多种操作模式（聊天、交互、命令模式）和多模态附件。若启用实验性 AI 虚拟内存或执行计划功能，需依赖额外的 chuk 系列组件。可通过 --dashboard 启动浏览器实时看板。","未说明（作为 PyPI 包发布，通常建议 Python 3.8+）",[113,114,115,116,117,118],"chuk-tool-processor","chuk-llm","chuk-term","chuk-ai-session-manager","chuk-ai-planner","ollama (可选，用于本地推理)",[26,15,53],"2026-03-27T02:49:30.150509","2026-04-06T05:16:27.506375",[123,128,133,138,142,147,152,157],{"id":124,"question_zh":125,"answer_zh":126,"source_url":127},9322,"如何配置远程 MCP 服务器（如基于 SSE 或 HTTP 流）？","目前工具已支持 SSE 和可流式传输的 HTTP (streamable-http) 协议。不过需要注意的是，根据最新标准，SSE 已被弃用，HTTP 流式传输是未来的发展方向。您可以在配置中指定相应的远程服务器地址来使用这些功能。","https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-cli\u002Fissues\u002F68",{"id":129,"question_zh":130,"answer_zh":131,"source_url":132},9323,"如果 Ollama 安装在另一台电脑上，如何配置 host 地址？","您需要修改本地的 `ollama_client.py` 文件，在 `OllamaLLMClient` 类的初始化方法中手动设置 `base_url`。例如：\n```python\nclass OllamaLLMClient(BaseLLMClient): \n    def __init__(self, model: str = \"qwen2.5-coder\"): \n        self.model = model \n        self.base_url = \"http:\u002F\u002FXXX.XXX.XXX.XXX:11434\"  # 在此处添加您的远程 IP 和端口\n```\n对于自定义部署的支持 OpenAI 风格调用的模型，同样需要配置相应的 `base_url`，并在执行 `uv run mcp-cli chat` 时通过 `--model` 参数指定模型名称。","https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-cli\u002Fissues\u002F64",{"id":134,"question_zh":135,"answer_zh":136,"source_url":137},9324,"使用 Ollama (llama3.2) 时模型无法执行多次工具调用或迭代失败尝试怎么办？","该问题在最新版本中应该已经修复。此外，维护者建议在使用工具调用功能时，使用 `qwen` 系列模型代替 `llama3.2`，因为 `qwen` 在此场景下表现更好，能更有效地利用可用工具回答问题。","https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-cli\u002Fissues\u002F11",{"id":139,"question_zh":140,"answer_zh":141,"source_url":137},9325,"运行命令时提示 'unexpected argument --server found' 错误如何解决？","请确保使用正确的命令格式。正确的运行方式应该是 `uv run mcp-cli --server \u003Cserver_name>`（例如 `uv run mcp-cli --server sqlite`）。如果您直接运行 `uv run --server` 而没有跟上 `mcp-cli` 主程序名，或者参数位置不对，就会报此错误。请检查 README 文档中的最新用法说明。",{"id":143,"question_zh":144,"answer_zh":145,"source_url":146},9326,"无法通过 OAuth 登录 Notion 服务器怎么办？","这通常是由于令牌缓存或配置问题导致的。您可以尝试先删除现有的 OAuth 令牌，然后重新登录。具体命令如下：\n1. 删除令牌：`mcp-cli token delete notion --is-oauth`\n2. 重新启动服务器连接：`mcp-cli --server notion`\n系统会再次弹出授权窗口，请按提示完成授权。如果问题依旧，可能是特定平台的兼容性问题，需等待维护者修复。","https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-cli\u002Fissues\u002F190",{"id":148,"question_zh":149,"answer_zh":150,"source_url":151},9327,"安装后运行报错 'ModuleNotFoundError: No module named chuk_llm...' 如何解决？","这通常是由于依赖包 `chuk-llm` 版本不匹配或未正确安装导致的。请尝试以下解决方案：\n1. 确保升级到最新版本的 mcp-cli 和相关依赖。\n2. 如果问题仍然存在，可以尝试手动更新 `chuk-llm` 到最新版本，或者根据项目要求锁定特定版本（早期版本曾建议锁定到 0.1.8，但最新代码可能需要更新的版本）。\n3. 推荐使用 `uv sync --reinstall` 重新同步并安装所有依赖，以确保环境干净且版本一致。","https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-cli\u002Fissues\u002F137",{"id":153,"question_zh":154,"answer_zh":155,"source_url":156},9328,"除了 sqlite 外，其他 MCP 服务器（如 puppeteer, filesystem）无法加载工具怎么办？","多服务器支持功能在早期版本中存在限制，目前已在最新版本中得到大幅改进。如果您遇到只能加载 sqlite 而其他服务器（如 puppeteer, filesystem）不显示工具的情况：\n1. 请确保您使用的是最新版本的 mcp-cli。\n2. 检查 `server_config.json` 配置文件中的命令路径和参数是否正确。\n3. 维护者正在标准化内置服务器列表并增加添加服务器的界面，如果遇到复杂的多服务器配置问题，建议暂时只使用一个服务器进行测试，或关注后续版本更新以获取更好的多服务器支持。","https:\u002F\u002Fgithub.com\u002FIBM\u002Fmcp-cli\u002Fissues\u002F86",{"id":158,"question_zh":159,"answer_zh":160,"source_url":156},9329,"如何在 Windows 或 WSL 环境中正确安装和运行 mcp-cli？","推荐的使用方式是通过 `uv` 工具进行安装和运行，步骤如下：\n1. 安装 UV（如果尚未安装）：`pip install uv`\n2. 同步并安装依赖：`uv sync --reinstall`\n3. 运行命令：`uv run mcp-cli --help`\n\n关于环境选择：\n- 如果在 Windows 上使用 WSL，建议在 WSL 内部安装 Ollama，因为 WSL 可能无法直接访问 Windows 主机上运行的 Ollama 服务。\n- 也可以尝试在 Windows 原生的 Miniconda 环境中运行，避免全局安装。\n- 维护者提示，不同环境下的测试可能存在差异，如遇问题可尝试切换环境或重置 WSL 发行版。",[]]