MCP CLI - Model Context Protocol Command Line Interface

MCP CLI - 模型上下文协议命令行界面

一款功能强大、功能丰富的命令行界面，可用于与模型上下文协议服务交互。此客户端集成了 CHUK Tool Processor 和 CHUK-LLM，支持工具调用、对话管理和多种运行模式，让你能够与大模型无缝通信。

默认配置：MCP CLI 默认使用 Ollama 和 gpt-oss 推理模型，在本地运行并注重隐私，无需 API 密钥。

🆕 最近更新（v0.16）

AI 虚拟内存（实验性）

• --vm 标志：启用类似操作系统的虚拟内存来管理对话上下文，由 chuk-ai-session-manager 提供支持
• --vm-budget：控制对话事件的令牌预算（系统提示词不计入此上限），促使系统更早地清退内容并创建页面
• --vm-mode：选择虚拟机模式——passive（由运行时管理，默认）、relaxed（虚拟机感知对话）或 strict（由模型驱动分页并使用工具）
• /memory 命令：在对话期间查看虚拟内存状态——页表、工作集利用率、清退指标、TLB 统计信息（别名：/vm、/mem）
• 多模态 page_fault：图像页面会返回多块内容（文本 + image_url），让多模态模型能够重新分析调取的图像
• /memory page <id> --download：将页面内容导出到本地文件，并使用适合内容模态的扩展名（.txt、.json、.png）

执行计划（Tier 6）

• /plan 命令：创建、检查和执行可复现的工具调用图——create、list、show、run、delete、resume
• 模型驱动的规划（--plan-tools）：大模型可在对话期间自主创建并执行计划，无需使用 /plan 命令。需要多步骤编排时，它会调用 plan_create_and_execute；简单任务则使用常规工具。每个步骤都会在终端实时显示进度
• 并行批量执行：通过拓扑分批（Kahn 的 BFS）并发运行相互独立的计划步骤，且可配置 max_concurrency
• 变量解析：支持 ${var}、${var.field} 嵌套访问，以及 "https://${api.host}/users" 之类的模板字符串——单个引用会保留原有类型
• 试运行模式：跟踪计划中的工具调用而不实际执行，可安全地检查生产环境
• 检查点与恢复：每批执行后都会持久化执行状态；可使用 /plan resume <id> 恢复中断的计划
• Guard 集成：计划遵守现有的预算、单工具限制和失控检测 Guard
• DAG 可视化：使用 ASCII 图形和状态指示符（○/◉/●/✗）及并行标记（∥）进行展示
• 重新规划：步骤失败时可选择使用基于大模型的重新规划（enable_replan=True）
• 由以下项目提供支持：chuk-ai-planner 基于图的计划 DSL

MCP 应用（SEP-1865）

• 交互式 HTML UI：MCP 服务可提供交互式 HTML 应用（图表、表格、地图、Markdown 查看器），并在浏览器中渲染
• 沙盒 iframe：应用在安全的沙盒 iframe 中运行，并受 CSP 保护
• WebSocket 桥接：浏览器应用与 MCP 服务之间的实时双向通信
• 自动启动：调用带有 _meta.ui 注释的工具时，会自动在浏览器中打开相应应用
• 会话可靠性：支持消息排队、通过指数退避机制重新连接，以及延迟交付工具结果

生产环境强化

• 机密信息脱敏：所有日志输出（控制台和文件）都会自动对 Bearer 令牌、API 密钥、OAuth 令牌和 Authorization 标头进行脱敏
• 结构化文件日志：可选的 --log-file 标志可启用轮换 JSON 日志文件（10MB，3 个备份），日志级别为 DEBUG
• 按服务设置超时：服务配置支持覆盖 tool_timeout 和 init_timeout，按服务级 → 全局级 → 默认值的顺序解析
• 线程安全的 OAuth：使用 asyncio.Lock 序列化并发 OAuth 流程，并通过写时复制修改标头
• 服务健康监控：/health 命令、失败时的健康检查诊断，以及可选的 --health-interval 后台轮询

性能与优化

• O(1) 工具查找：使用索引查找工具，取代 O(n) 线性扫描
• 缓存的大模型工具元数据：按提供商缓存，并自动失效
• 启动进度：初始化期间实时显示进度消息
• 令牌用量跟踪：按轮次和累计跟踪，并提供 /usage 命令（别名：/tokens、/cost）
• 会话持久化：保存、加载和列出对话会话，每 10 轮自动保存（/sessions）
• 对话导出：将对话导出为 Markdown 或 JSON，并附带元数据（/export）

仪表板（实时浏览器 UI）

• --dashboard 标志：在聊天模式下同时启动实时浏览器仪表板
• Agent 终端：实时对话视图，包含消息气泡、流式令牌和附件呈现
• 活动流：工具调用/结果对、推理步骤和用户附件事件
• 计划查看器：以 DAG 形式直观呈现执行计划进度
• 工具注册表：浏览发现的工具，并从浏览器触发执行
• 配置面板：查看和切换提供商、模型及系统提示词
• 文件附件：使用“+”按钮上传浏览器文件，并支持拖放和粘贴剪贴板内容

多模态附件

• /attach 命令：为下一条消息暂存文件——图片、文本/代码和音频（别名：/file、/image）
• --attach CLI 标志：将文件附加到第一条消息（可重复使用：--attach img.png --attach code.py）
• 行内 @file: 引用：在消息中的任意位置提及 @file:path/to/file，即可附加相应文件
• 图片 URL 检测：消息中的 HTTP/HTTPS 图片 URL 会自动作为视觉内容发送
• 支持的格式：PNG、JPEG、GIF、WebP、HEIC（图片），MP3、WAV（音频），以及 25 种以上文本/代码扩展名
• 仪表板呈现：图片缩略图、可展开的文本预览、音频播放器和文件徽标
• 浏览器上传：仪表板聊天输入框中的“+”按钮支持拖放和粘贴剪贴板内容

代码质量

• 核心/UI 分离：核心模块仅使用 logging，不导入 UI
• 4,300+ 项测试：全面的测试套件，包含分支覆盖率、集成测试和 60% 的最低覆盖率门槛
• 15 项架构原则：已记录并强制执行（参见 architecture.md）
• 完整路线图：第 1–6 阶段已完成，第 7–12 阶段已规划（跟踪、记忆范围、技能、调度、多 Agent）

🔄 架构概览

MCP CLI 基于模块化架构构建，职责划分清晰：

• CHUK Tool Processor：生产级异步工具执行，支持中间件（重试、断路器、速率限制）、多种执行策略和可观测性
• CHUK-LLM：统一的大模型提供商，支持动态模型发现、基于能力的选择以及 llama.cpp 集成（比 Ollama 快 1.53 倍，并自动复用模型）
• CHUK-Term：增强型终端 UI，支持主题、跨平台终端管理和丰富格式
• MCP CLI：命令编排和集成层（本项目）

🌟 功能

多种运行模式

• 聊天模式：支持流式响应和自动调用工具的对话界面（默认：Ollama/gpt-oss）
• 交互模式：通过命令驱动的 Shell 界面直接操作服务
• 命令模式：适用于脚本自动化和管道的 Unix 友好模式
• 直接命令：无需进入交互模式即可运行单条命令

高级聊天界面

• 流式响应：实时生成响应并即时更新 UI
• 推理可见性：使用推理模型（gpt-oss、GPT-5、Claude 4.5）时查看 AI 的思考过程
• 并发工具执行：同时执行多个工具，同时保持对话顺序
• 智能中断：使用 Ctrl+C 中断流式响应或工具执行
• 性能指标：响应耗时、每秒字数和执行统计信息
• 丰富的格式：Markdown 渲染、语法高亮和进度指示器
• Token 用量跟踪：通过 /usage 命令查看每轮及累计 API token 用量
• 多模态附件：通过 /attach、--attach、@file: 引用或浏览器上传，为消息添加图像、文本文件和音频
• 会话持久化：自动保存并手动保存/加载对话会话
• 对话导出：导出为 Markdown 或 JSON，并包含元数据和 token 用量

全面的提供商支持

MCP CLI 支持 CHUK-LLM 中的所有提供商和模型，包括前沿推理模型：

提供商	主要模型	特殊功能
Ollama（默认）	🧠 gpt-oss、llama3.3、llama3.2、qwen3、qwen2.5-coder、deepseek-coder、granite3.3、mistral、gemma3、phi3、codellama	本地推理模型，注重隐私，无需 API 密钥
OpenAI	🚀 GPT-5 系列（gpt-5、gpt-5-mini、gpt-5-nano）、GPT-4o 系列、O3 系列（o3、o3-mini）	高级推理、函数调用、视觉
Anthropic	🧠 Claude 4.5 系列（claude-4-5-opus、claude-4-5-sonnet）、Claude 3.5 Sonnet	增强推理、长上下文
Azure OpenAI 🏢	企业级 GPT-5、GPT-4 模型	私有端点、合规性、审计日志
Google Gemini	Gemini 2.0 Flash、Gemini 1.5 Pro	多模态、快速推理
Groq ⚡	Llama 3.1 模型、Mixtral	超快推理（每秒 500+ tokens）
Perplexity 🌐	Sonar 模型	实时网页搜索并附带引文
IBM watsonx 🏢	Granite、Llama 模型	企业级合规性
Mistral AI 🇪🇺	Mistral Large、Medium	欧洲模型，高效

强大的工具系统（由 CHUK Tool Processor v0.22+ 提供支持）

• 自动发现：自动检测并编录服务提供的工具
• 提供商适配：自动清理工具名称，使其兼容各提供商
• 生产级执行：通过中间件层实现超时、重试、指数退避、缓存和熔断器
• 多种执行策略：进程内执行（快速）、隔离子进程执行（安全）或通过 MCP 远程执行
• 并发执行：可同时运行多个工具，并进行适当协调
• 丰富的进度显示：实时进度指示器和执行计时
• 工具历史记录：完整记录所有工具执行情况，便于审计
• 中间件：通过 CTP 实现指数退避重试、熔断器和速率限制
• 流式工具调用：支持返回流式数据的工具

MCP Apps（交互式 UI）

• 基于浏览器的 UI：MCP 服务可提供交互式 HTML 应用，并在浏览器中渲染
• 自动检测：带有 _meta.ui 注解的工具会在调用时自动启动浏览器应用
• 沙盒执行：应用在安全的沙盒 iframe 中运行，并受到内容安全策略保护
• WebSocket 桥接：在浏览器应用与 MCP 工具服务器之间建立实时 JSON-RPC 桥接
• 会话持久化：断开连接时对消息进行排队、自动重新连接，并延迟传递工具结果
• structuredContent 支持：完全符合 MCP 规范，包括结构化内容的提取与转发

执行计划（由 chuk-ai-planner 提供支持）

• 创建计划：使用基于大模型的计划 Agent，根据自然语言描述生成执行计划
• 模型驱动的规划：使用 --plan-tools 时，大模型会自主决定何时规划——复杂的多步骤任务会调用 plan_create_and_execute，简单任务则使用常规工具
• DAG 执行：计划是有向无环图——独立步骤分批并行运行，依赖步骤则等待
• 变量解析：步骤输出绑定到变量（result_variable），后续步骤通过 ${var} 或 ${var.field} 引用
• 试运行模式：跟踪计划将执行的操作，但不实际运行任何工具——适用于生产环境
• 检查点：每个批次完成后保存执行状态；恢复被中断的计划时，无需重新运行已完成的步骤
• 防护集成：计划与对话共享预算和每个工具的限制——不会绕过限制
• 重新规划：步骤失败时，可选择调用大模型为剩余工作生成修订后的计划
• DAG 可视化：ASCII 渲染结果会显示依赖结构、批次分组和并行标记
• 持久化：计划以 JSON 格式存储在 ~/.mcp-cli/plans/

高级配置管理

• 环境集成：通过环境变量配置 API 密钥和设置
• 基于文件的配置：YAML 和 JSON 配置文件
• 用户偏好设置：持久保存当前启用的提供方和模型设置
• 验证与诊断：内置提供方健康检查和配置验证

增强的用户体验

• 跨平台支持：通过 chuk-term 针对 Windows、macOS 和 Linux 进行平台特定优化
• 丰富的控制台输出：由 chuk-term 提供支持，内置 8 种主题（default、dark、light、minimal、terminal、monokai、dracula、solarized）
• 高级终端管理：跨平台终端操作，包括清屏、调整大小、颜色检测和光标控制
• 交互式 UI 组件：通过 chuk-term 的提示词系统处理用户输入（ask、confirm、select_from_list、select_multiple）
• 命令补全：所有界面均支持上下文感知的 Tab 补全
• 全面的帮助：提供详细的帮助系统，包含示例和用法模式
• 优雅的错误处理：提供易于理解的错误消息和故障排除提示

📚 文档

docs/ 目录中提供了全面的文档：

项目

• 架构 - 15 项设计原则、模块布局和编码规范
• 路线图 - 愿景、已完成的阶段（1-5）以及计划中的阶段（6-12：计划、跟踪、技能、调度、多 Agent、远程会话）

核心文档

• 命令系统 - 统一命令系统、模式及其在所有模式中的用法的完整指南
• 令牌管理 - 面向提供方和服务的全面令牌管理，包括 OAuth、Bearer 令牌和 API 密钥

专题文档

• 执行计划 - 计划创建、并行执行、变量解析、检查点、守卫和重新规划
• 仪表板 - 实时浏览器 UI，包含 Agent 终端、活动流和文件上传
• 附件 - 多模态文件附件：图像、文本、音频和浏览器上传
• MCP Apps - 由 MCP 服务提供的交互式浏览器 UI（SEP-1865）
• OAuth 身份验证 - OAuth 流程、存储后端和 MCP 服务集成
• 流式集成 - 实时响应流式传输架构
• 包管理 - 依赖项组织和功能组

UI 文档

• 主题 - 主题系统和自定义
• 输出系统 - 丰富的控制台输出和格式设置
• 终端管理 - 跨平台终端操作

测试文档

• 单元测试 - 测试结构和模式
• 测试覆盖率 - 覆盖率要求和报告

📋 前置条件

• Python 3.11 或更高版本
• 本地运行（默认）：
  • Ollama：从 ollama.ai 安装
  • 拉取默认推理模型：ollama pull gpt-oss
• 云服务提供商（可选）：
  • OpenAI：OPENAI_API_KEY 环境变量（用于 GPT-5、GPT-4、O3 模型）
  • Anthropic：ANTHROPIC_API_KEY 环境变量（用于 Claude 4.5、Claude 3.5）
  • Azure：AZURE_OPENAI_API_KEY 和 AZURE_OPENAI_ENDPOINT（用于企业版 GPT-5）
  • Google：GEMINI_API_KEY（用于 Gemini 模型）
  • Groq：GROQ_API_KEY（用于快速 Llama 模型）
  • 自定义服务提供商：特定于服务提供商的配置
• MCP 服务：服务配置文件（默认：server_config.json）

🚀 安装

使用 Ollama 快速开始（默认）

1. 安装 Ollama（如果尚未安装）：

# macOS/Linux
curl -fsSL https://ollama.ai/install.sh | sh

# Or visit https://ollama.ai for other installation methods

2. 拉取默认推理模型：

ollama pull gpt-oss  # Open-source reasoning model with thinking visibility

3. 安装并运行 MCP CLI：

# Using uvx (recommended)
uvx mcp-cli --help

# Or install from source
git clone https://github.com/chrishayuk/mcp-cli
cd mcp-cli
pip install -e "."
mcp-cli --help

# Optional: Enable MCP Apps (interactive browser UIs)
pip install -e ".[apps]"

使用不同的模型

# === LOCAL MODELS (No API Key Required) ===

# Use default reasoning model (gpt-oss)
mcp-cli --server sqlite

# Use other Ollama models
mcp-cli --model llama3.3              # Latest Llama
mcp-cli --model qwen2.5-coder         # Coding-focused
mcp-cli --model deepseek-coder        # Another coding model
mcp-cli --model granite3.3            # IBM Granite

# === CLOUD PROVIDERS (API Keys Required) ===

# GPT-5 Family (requires OpenAI API key)
mcp-cli --provider openai --model gpt-5          # Full GPT-5 with reasoning
mcp-cli --provider openai --model gpt-5-mini     # Efficient GPT-5 variant
mcp-cli --provider openai --model gpt-5-nano     # Ultra-lightweight GPT-5

# GPT-4 Family
mcp-cli --provider openai --model gpt-4o         # GPT-4 Optimized
mcp-cli --provider openai --model gpt-4o-mini    # Smaller GPT-4

# O3 Reasoning Models
mcp-cli --provider openai --model o3             # O3 reasoning
mcp-cli --provider openai --model o3-mini        # Efficient O3

# Claude 4.5 Family (requires Anthropic API key)
mcp-cli --provider anthropic --model claude-4-5-opus    # Most advanced Claude
mcp-cli --provider anthropic --model claude-4-5-sonnet  # Balanced Claude 4.5
mcp-cli --provider anthropic --model claude-3-5-sonnet  # Claude 3.5

# Enterprise Azure (requires Azure configuration)
mcp-cli --provider azure_openai --model gpt-5    # Enterprise GPT-5

# Other Providers
mcp-cli --provider gemini --model gemini-2.0-flash      # Google Gemini
mcp-cli --provider groq --model llama-3.1-70b          # Fast Llama via Groq

🧰 全局配置

默认配置

MCP CLI 的默认设置：

• 服务提供商：ollama（本地，无需 API 密钥）
• 模型：gpt-oss（开源推理模型，可查看思考过程）

命令行参数

所有模式和命令均可使用以下全局选项：

• --server：指定要连接的服务（以逗号分隔）
• --config-file：服务配置文件的路径（默认：server_config.json）
• --provider：大模型服务提供商（默认：ollama）
• --model：要使用的特定模型（Ollama 默认使用 gpt-oss）
• --disable-filesystem：禁用文件系统访问（默认：启用）
• --api-base：覆盖 API 端点 URL
• --api-key：覆盖 API 密钥（Ollama 无需此项）
• --token-backend：覆盖令牌存储后端（auto、keychain、windows、secretservice、encrypted、vault）
• --verbose：启用详细日志记录
• --quiet：隐藏非必要输出
• --log-file：将调试日志写入轮转文件（自动隐藏机密信息）
• --vm：[实验性] 启用 AI 虚拟内存以管理上下文
• --vm-budget：VM 模式下对话事件的令牌预算（默认：128000，另加系统提示词）
• --vm-mode：VM 模式——passive（默认）、relaxed 或 strict
• --dashboard：在聊天模式旁启动实时浏览器仪表板 UI
• --attach：将文件附加到第一条消息（可重复使用：--attach img.png --attach code.py）
• --plan-tools：启用模型驱动的规划——由大模型自主创建并执行多步计划
• --no-tools：完全禁用 MCP 工具调用——不连接任何 MCP 服务，直接与大模型聊天

环境变量

# Override defaults
export LLM_PROVIDER=ollama              # Default provider (already the default)
export LLM_MODEL=gpt-oss                # Default model (already the default)

# For cloud providers (optional)
export OPENAI_API_KEY=sk-...           # For GPT-5, GPT-4, O3 models
export ANTHROPIC_API_KEY=sk-ant-...    # For Claude 4.5, Claude 3.5
export AZURE_OPENAI_API_KEY=sk-...     # For enterprise GPT-5
export AZURE_OPENAI_ENDPOINT=https://...
export GEMINI_API_KEY=...              # For Gemini models
export GROQ_API_KEY=...                # For Groq fast inference

# Tool configuration
export MCP_TOOL_TIMEOUT=120            # Tool execution timeout (seconds)

🌐 可用模式

1. 聊天模式（默认）

提供自然语言界面，支持流式响应和自动使用工具：

# Default mode with Ollama/gpt-oss reasoning model (no API key needed)
mcp-cli --server sqlite

# See the AI's thinking process with reasoning models
mcp-cli --server sqlite --model gpt-oss     # Open-source reasoning
mcp-cli --server sqlite --provider openai --model gpt-5  # GPT-5 reasoning
mcp-cli --server sqlite --provider anthropic --model claude-4-5-opus  # Claude 4.5 reasoning

# Use different local models
mcp-cli --server sqlite --model llama3.3
mcp-cli --server sqlite --model qwen2.5-coder

# Switch to cloud providers (requires API keys)
mcp-cli chat --server sqlite --provider openai --model gpt-5
mcp-cli chat --server sqlite --provider anthropic --model claude-4-5-sonnet

# Launch with real-time browser dashboard
mcp-cli --server sqlite --dashboard

# Attach files to the first message
mcp-cli --server sqlite --attach image.png --attach data.csv

2. 交互模式

由命令驱动的 Shell 界面，可直接执行服务操作：

mcp-cli interactive --server sqlite

# With specific models
mcp-cli interactive --server sqlite --model gpt-oss       # Local reasoning
mcp-cli interactive --server sqlite --provider openai --model gpt-5  # Cloud GPT-5

3. 命令模式

适用于 Unix 的界面，可用于自动化和脚本编写：

# Process text with reasoning models
mcp-cli cmd --server sqlite --model gpt-oss --prompt "Think through this step by step" --input data.txt

# Use GPT-5 for complex reasoning
mcp-cli cmd --server sqlite --provider openai --model gpt-5 --prompt "Analyze this data" --input data.txt

# Execute tools directly
mcp-cli cmd --server sqlite --tool list_tables --output tables.json

# Pipeline-friendly processing
echo "SELECT * FROM users LIMIT 5" | mcp-cli cmd --server sqlite --tool read_query --input -

4. 直接命令

无需进入交互模式即可执行单条命令：

# List available tools
mcp-cli tools --server sqlite

# Show provider configuration
mcp-cli provider list

# Show available models for current provider
mcp-cli models

# Show models for specific provider
mcp-cli models openai    # Shows GPT-5, GPT-4, O3 models
mcp-cli models anthropic # Shows Claude 4.5, Claude 3.5 models
mcp-cli models ollama    # Shows gpt-oss, llama3.3, etc.

# Ping servers
mcp-cli ping --server sqlite

# List resources
mcp-cli resources --server sqlite

# UI Theme Management
mcp-cli theme                     # Show current theme and list available
mcp-cli theme dark                # Switch to dark theme
mcp-cli theme --select            # Interactive theme selector
mcp-cli theme --list              # List all available themes

# Token Storage Management
mcp-cli token backends            # Show available storage backends
mcp-cli --token-backend encrypted token list  # Use specific backend

🌐 MCP Apps（交互式浏览器 UI）

MCP Apps 支持工具服务提供可在浏览器中呈现的交互式 HTML UI。当工具具有指向 UI 资源的 _meta.ui 注解时，mcp-cli 会自动启动本地 Web 服务，并在浏览器中打开应用。

前提条件

# Install the apps extra (adds websockets dependency)
pip install "mcp-cli[apps]"

工作原理

1. 连接到提供启用应用工具的 MCP 服务
2. 调用具有 _meta.ui 元数据的工具（例如 show_chart、show_table）
3. mcp-cli 会自动获取 UI 资源、启动本地服务并打开浏览器
4. 应用通过 WebSocket 实时接收工具结果

示例

# Connect to a server with app-enabled tools
mcp-cli --server view_demo

# In chat, ask for something visual:
> Show me the sales data as a chart
# Browser opens automatically with an interactive chart

# The /tools command shows which tools have app UIs (APP column)
> /tools

架构

• 宿主页：提供包含应用 HTML 的沙盒 iframe
• WebSocket 桥接：在浏览器与 MCP 服务之间代理 JSON-RPC
• 安全性：iframe 沙盒、CSP 防护、XSS 防护、URL 方案验证
• 可靠性：断开连接时进行消息排队、指数退避重连、延迟交付工具结果

完整指南请参阅 MCP Apps 文档。

🤖 使用聊天模式

聊天模式提供最先进的界面，支持流式响应和智能工具使用。

启动聊天模式

# Simple startup with default reasoning model (gpt-oss)
mcp-cli --server sqlite

# Multiple servers
mcp-cli --server sqlite,filesystem

# With advanced reasoning models
mcp-cli --server sqlite --provider openai --model gpt-5
mcp-cli --server sqlite --provider anthropic --model claude-4-5-opus

聊天命令（斜杠命令）

提供商与模型管理

/provider                           # Show current configuration (default: ollama)
/provider list                      # List all providers
/provider config                    # Show detailed configuration
/provider diagnostic               # Test provider connectivity
/provider set ollama api_base http://localhost:11434  # Configure Ollama endpoint
/provider openai                   # Switch to OpenAI (requires API key)
/provider anthropic                # Switch to Anthropic (requires API key)
/provider openai gpt-5             # Switch to OpenAI GPT-5

# Custom Provider Management
/provider custom                   # List custom providers
/provider add localai http://localhost:8080/v1 gpt-4  # Add custom provider
/provider remove localai           # Remove custom provider

/model                             # Show current model (default: gpt-oss)
/model llama3.3                    # Switch to different Ollama model
/model gpt-5                       # Switch to GPT-5 (if using OpenAI)
/model claude-4-5-opus             # Switch to Claude 4.5 (if using Anthropic)
/models                            # List available models for current provider

工具管理

/tools                             # List available tools
/tools --all                       # Show detailed tool information
/tools --raw                       # Show raw JSON definitions
/tools call                        # Interactive tool execution

/toolhistory                       # Show tool execution history
/th -n 5                          # Last 5 tool calls
/th 3                             # Details for call #3
/th --json                        # Full history as JSON

服务管理（运行时配置）

/server                            # List all configured servers
/server list                       # List servers (alias)
/server list all                   # Include disabled servers

# Add servers at runtime (persists in ~/.mcp-cli/preferences.json)
/server add <name> stdio <command> [args...]
/server add sqlite stdio uvx mcp-server-sqlite --db-path test.db
/server add playwright stdio npx @playwright/mcp@latest
/server add time stdio uvx mcp-server-time
/server add fs stdio npx @modelcontextprotocol/server-filesystem /path/to/dir

# HTTP/SSE server examples with authentication
/server add github --transport http --header "Authorization: Bearer ghp_token" -- https://api.github.com/mcp
/server add myapi --transport http --env API_KEY=secret -- https://api.example.com/mcp
/server add events --transport sse -- https://events.example.com/sse

# Manage server state
/server enable <name>              # Enable a disabled server
/server disable <name>             # Disable without removing
/server remove <name>              # Remove user-added server
/server ping <name>                # Test server connectivity

# Server details
/server <name>                     # Show server configuration details

注意：通过 /server add 添加的服务会存储在 ~/.mcp-cli/preferences.json 中，并在不同会话间保留。项目服务仍保存在 server_config.json 中。

多模态附件

/attach image.png                  # Stage an image for the next message
/attach code.py                    # Stage a text file
/attach list                       # Show currently staged files
/attach clear                      # Clear staged files
/file data.csv                     # Alias for /attach
/image screenshot.heic             # Alias for /attach

# Inline file references (in any message)
@file:screenshot.png describe what you see
@file:data.csv summarize this data

# Image URLs are auto-detected
https://example.com/photo.jpg what is in this image?

对话管理

/conversation                      # Show conversation history
/ch -n 10                         # Last 10 messages
/ch 5                             # Details for message #5
/ch --json                        # Full history as JSON

/save conversation.json            # Save conversation to file
/compact                          # Summarize conversation
/clear                            # Clear conversation history
/cls                              # Clear screen only

UI 自定义

/theme                            # Interactive theme selector with preview
/theme dark                       # Switch to dark theme
/theme monokai                    # Switch to monokai theme

# Available themes: default, dark, light, minimal, terminal, monokai, dracula, solarized
# Themes are persisted across sessions

令牌管理

/token                            # List all stored tokens
/token list                       # List all tokens explicitly
/token set <name>                 # Store a bearer token
/token get <name>                 # Get token details
/token delete <name>              # Delete a token
/token clear                      # Clear all tokens (with confirmation)
/token backends                   # Show available storage backends

# Examples
/token set my-api                 # Prompts for token value (secure)
/token get notion --oauth         # Get OAuth token for Notion server
/token list --api-keys            # List only provider API keys

令牌存储后端： MCP CLI 支持多个安全的令牌存储后端：

• Keychain（macOS）——使用 macOS Keychain（macOS 上的默认选项）
• Windows Credential Manager ——Windows 原生存储（Windows 上的默认选项）
• Secret Service ——Linux 桌面密钥环（GNOME/KDE）
• Encrypted File ——AES-256 加密的本地文件（跨平台回退选项）
• HashiCorp Vault ——企业级密钥管理

使用 --token-backend 覆盖默认后端：

# Use encrypted file storage instead of keychain
mcp-cli --token-backend encrypted token list

# Use vault for enterprise environments
mcp-cli --token-backend vault token list

完整文档请参阅 令牌管理指南。

会话控制

/verbose                          # Toggle verbose/compact display (Default: Enabled)
/confirm                          # Toggle tool call confirmation (Default: Enabled)
/interrupt                        # Stop running operations
/server                           # Manage MCP servers (see Server Management above)
/help                            # Show all commands
/help tools                       # Help for specific command
/exit                            # Exit chat mode

完整的命令文档请参阅 命令系统指南。

聊天功能

流式响应与推理过程可见性

• 🧠 推理模型：查看 AI 的思考过程，支持 gpt-oss、GPT-5、Claude 4
• 实时生成：观察文本逐个 token 显示
• 性能指标：每秒字数、响应时间
• 优雅中断：按 Ctrl+C 停止流式输出
• 渐进式渲染：Markdown 随流式输出逐步格式化

工具执行

• 自动发现和使用工具
• 并发执行并显示进度指示器
• 详细和紧凑显示模式
• 完整的执行历史记录和计时信息

多模态附件

• 在任何消息中附加图像、文本文件和音频
• /attach 命令支持暂存、列出和清除（别名：/file、/image）
• 在任何消息中内联使用 @file:path 引用文件
• 使用 --attach CLI 标志为第一条消息添加附件
• 浏览器中的“+”按钮支持拖放和粘贴剪贴板内容（需使用 --dashboard）
• Dashboard 可呈现缩略图、文本预览和音频播放器

提供商集成

• 在不同提供商之间无缝切换
• 针对特定模型进行优化
• API 密钥和端点管理
• 健康状态监控和诊断

🖥️ 使用交互模式

交互模式提供命令 shell，可直接与服务交互。

启动交互模式

mcp-cli interactive --server sqlite

交互命令

help                              # Show available commands
exit                              # Exit interactive mode
clear                             # Clear terminal

# Provider management
provider                          # Show current provider
provider list                     # List providers
provider anthropic                # Switch provider
provider openai gpt-5             # Switch to GPT-5

# Model management
model                             # Show current model
model gpt-oss                     # Switch to reasoning model
model claude-4-5-opus             # Switch to Claude 4.5
models                            # List available models

# Tool operations
tools                             # List tools
tools --all                       # Detailed tool info
tools call                        # Interactive tool execution

# Server operations
servers                           # List servers
ping                              # Ping all servers
resources                         # List resources
prompts                           # List prompts

📄 使用命令模式

命令模式提供适用于 Unix 的自动化功能。

命令模式选项

--input FILE                      # Input file (- for stdin)
--output FILE                     # Output file (- for stdout)
--prompt TEXT                     # Prompt template
--tool TOOL                       # Execute specific tool
--tool-args JSON                  # Tool arguments as JSON
--system-prompt TEXT              # Custom system prompt
--raw                             # Raw output without formatting
--single-turn                     # Disable multi-turn conversation
--max-turns N                     # Maximum conversation turns

示例

# Text processing with reasoning models
echo "Analyze this data" | mcp-cli cmd --server sqlite --model gpt-oss --input - --output analysis.txt

# Use GPT-5 for complex analysis
mcp-cli cmd --server sqlite --provider openai --model gpt-5 --prompt "Provide strategic analysis" --input report.txt

# Tool execution
mcp-cli cmd --server sqlite --tool list_tables --raw

# Complex queries
mcp-cli cmd --server sqlite --tool read_query --tool-args '{"query": "SELECT COUNT(*) FROM users"}'

# Batch processing with GNU Parallel
ls *.txt | parallel mcp-cli cmd --server sqlite --input {} --output {}.summary --prompt "Summarize: {{input}}"

🔧 提供商配置

Ollama 配置（默认）

Ollama 默认在本地的 http://localhost:11434 上运行。MCP CLI v0.11.1+ 与 CHUK-LLM v0.16+ 集成了 llama.cpp，可自动发现并复用 Ollama 已下载的模型，无需重新下载，推理速度提升 1.53 倍（311 对比 204 tokens/sec）。

要使用推理模型及其他模型：

# Pull reasoning and other models for Ollama
ollama pull gpt-oss          # Default reasoning model
ollama pull llama3.3         # Latest Llama
ollama pull llama3.2         # Llama 3.2
ollama pull qwen3            # Qwen 3
ollama pull qwen2.5-coder    # Coding-focused
ollama pull deepseek-coder   # DeepSeek coder
ollama pull granite3.3       # IBM Granite
ollama pull mistral          # Mistral
ollama pull gemma3           # Google Gemma
ollama pull phi3             # Microsoft Phi
ollama pull codellama        # Code Llama

# List available Ollama models
ollama list

# Configure remote Ollama server
mcp-cli provider set ollama api_base http://remote-server:11434

云提供商配置

要使用具有高级模型的云提供商，请配置 API 密钥：

# Configure OpenAI (for GPT-5, GPT-4, O3 models)
mcp-cli provider set openai api_key sk-your-key-here

# Configure Anthropic (for Claude 4.5, Claude 3.5)
mcp-cli provider set anthropic api_key sk-ant-your-key-here

# Configure Azure OpenAI (for enterprise GPT-5)
mcp-cli provider set azure_openai api_key sk-your-key-here
mcp-cli provider set azure_openai api_base https://your-resource.openai.azure.com

# Configure other providers
mcp-cli provider set gemini api_key your-gemini-key
mcp-cli provider set groq api_key your-groq-key

# Test configuration
mcp-cli provider diagnostic openai
mcp-cli provider diagnostic anthropic

自定义 OpenAI 兼容提供商

MCP CLI 支持添加自定义 OpenAI 兼容提供商（LocalAI、自定义代理等）：

# Add a custom provider (persisted across sessions)
mcp-cli provider add localai http://localhost:8080/v1 gpt-4 gpt-3.5-turbo
mcp-cli provider add myproxy https://proxy.example.com/v1 custom-model-1 custom-model-2

# Set API key via environment variable (never stored in config)
export LOCALAI_API_KEY=your-api-key
export MYPROXY_API_KEY=your-api-key

# List custom providers
mcp-cli provider custom

# Use custom provider
mcp-cli --provider localai --server sqlite
mcp-cli --provider myproxy --model custom-model-1 --server sqlite

# Remove custom provider
mcp-cli provider remove localai

# Runtime provider (session-only, not persisted)
mcp-cli --provider temp-ai --api-base https://api.temp.com/v1 --api-key test-key --server sqlite

安全说明：API 密钥可以使用令牌管理系统安全地存储在操作系统原生密钥链（macOS Keychain、Windows Credential Manager、Linux Secret Service）或 HashiCorp Vault 中。或者，按照 {PROVIDER_NAME}_API_KEY 的格式使用环境变量，或通过 --api-key 传入，仅用于当前会话。详情请参阅令牌管理。

手动配置

chuk_llm 库在 ~/.chuk_llm/config.yaml 中的配置：

ollama:
  api_base: http://localhost:11434
  default_model: gpt-oss

openai:
  api_base: https://api.openai.com/v1
  default_model: gpt-5

anthropic:
  api_base: https://api.anthropic.com
  default_model: claude-4-5-opus

azure_openai:
  api_base: https://your-resource.openai.azure.com
  default_model: gpt-5

gemini:
  api_base: https://generativelanguage.googleapis.com
  default_model: gemini-2.0-flash

groq:
  api_base: https://api.groq.com
  default_model: llama-3.1-70b

可通过以下方式提供 API 密钥：

1. 安全令牌存储（推荐）——存储在操作系统密钥链/Vault 中，参阅令牌管理
2. 环境变量——在 shell 中导出，或添加到 ~/.chuk_llm/.env：

OPENAI_API_KEY=sk-your-key-here
ANTHROPIC_API_KEY=sk-ant-your-key-here
AZURE_OPENAI_API_KEY=sk-your-azure-key-here
GEMINI_API_KEY=your-gemini-key
GROQ_API_KEY=your-groq-key

3. 命令行——传入 --api-key，仅用于当前会话（不会持久保存）

📂 服务配置

MCP CLI 支持两种类型的服务配置：

1. 项目服务（server_config.json）：共享的项目级配置
2. 用户服务（~/.mcp-cli/preferences.json）：个人在运行时添加、可在各会话间保留的服务

配置文件发现

MCP CLI 按照以下优先级顺序搜索 server_config.json：

1. 通过 --config-file 选项指定的显式路径：

   mcp-cli --config-file /path/to/custom-config.json
   

2. 当前目录——从项目目录运行时自动检测：

   cd /path/to/my-project
   mcp-cli --server sqlite    # Uses ./server_config.json if it exists
   

3. 内置默认配置——通过 uvx 运行，或从没有本地配置的任意目录运行时使用：

   uvx mcp-cli --server cloudflare_workers    # Uses packaged server_config.json
   

这意味着你可以：

• 按项目覆盖：在项目目录中放置 server_config.json，配置项目专用的服务
• 全局使用默认配置：在任意位置运行 uvx mcp-cli，即可获取内置默认服务
• 显式自定义：使用 --config-file 指定任意配置文件的位置

内置默认服务

MCP CLI v0.11.1+ 在内置的 server_config.json 中提供了更多预配置服务：

服务	类型	描述	配置
sqlite	STDIO	SQLite 数据库操作	uvx mcp-server-sqlite --db-path test.db
echo	STDIO	用于测试的 Echo 服务	uvx chuk-mcp-echo stdio
math	STDIO	数学计算	uvx chuk-mcp-math-server
playwright	STDIO	浏览器自动化	npx @playwright/mcp@latest
brave_search	STDIO	通过 Brave API 进行网页搜索	需要 BRAVE_API_KEY 令牌
notion	HTTP	Notion 工作区集成	https://mcp.notion.com/mcp (OAuth)
cloudflare_workers	HTTP	Cloudflare Workers 绑定	https://bindings.mcp.cloudflare.com/mcp (OAuth)
monday	HTTP	Monday.com 集成	https://mcp.monday.com/mcp (OAuth)
linkedin	HTTP	LinkedIn 集成	https://linkedin.chukai.io/mcp
weather	HTTP	天气数据服务	https://weather.chukai.io/mcp

注意：HTTP 服务和基于 API 的服务需要身份验证。使用令牌管理系统配置访问令牌。

要使用这些服务：

# Use bundled servers from anywhere
uvx mcp-cli --server sqlite
uvx mcp-cli --server echo
uvx mcp-cli --server math
uvx mcp-cli --server playwright

# API-based servers require tokens
mcp-cli token set brave_search --type bearer
uvx mcp-cli --server brave_search

# HTTP/OAuth servers require OAuth authentication
uvx mcp-cli token set notion --oauth
uvx mcp-cli --server notion

# Use multiple servers simultaneously
uvx mcp-cli --server sqlite,math,playwright

项目配置

创建 server_config.json 文件来配置 MCP 服务：

{
  "mcpServers": {
    "sqlite": {
      "command": "python",
      "args": ["-m", "mcp_server.sqlite_server"],
      "env": {
        "DATABASE_PATH": "database.db"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"],
      "env": {}
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server"],
      "env": {
        "BRAVE_API_KEY": "${TOKEN:bearer:brave_search}"
      }
    },
    "notion": {
      "url": "https://mcp.notion.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TOKEN:bearer:notion}"
      }
    }
  }
}

安全令牌替换

MCP CLI 支持使用 ${TOKEN:namespace:name} 语法从安全存储中自动替换令牌：

语法：${TOKEN:<namespace>:<token-name>}

示例：

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server"],
      "env": {
        "BRAVE_API_KEY": "${TOKEN:bearer:brave_search}"
      }
    },
    "api-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TOKEN:bearer:my_api}",
        "X-API-Key": "${TOKEN:api-key:my_service}"
      }
    }
  }
}

令牌存储：

# Store tokens securely (never in config files!)
mcp-cli token set brave_search --type bearer
# Enter token value when prompted (hidden input)

mcp-cli token set my_api --type bearer --value "your-token-here"

# Tokens are stored in OS-native secure storage:
# - macOS: Keychain
# - Windows: Credential Manager
# - Linux: Secret Service (GNOME Keyring/KWallet)

支持的位置：

• env：STDIO 服务的环境变量
• headers：HTTP/SSE 服务的 HTTP 标头

命名空间：

• bearer：Bearer 令牌（--type bearer 的默认值）
• api-key：API 密钥（--type api-key 的默认值）
• oauth：OAuth 令牌（自动）
• generic：自定义令牌

优势：

• ✅ 永不在配置文件中存储 API 密钥
• ✅ 安全地共享 server_config.json（不含机密信息）
• ✅ 令牌加密存储在操作系统原生安全存储中
• ✅ 适用于所有传输类型（STDIO、HTTP、SSE）

完整文档请参阅令牌管理指南。

运行时服务管理

无需编辑配置文件，即可在运行时动态添加服务：

# Add STDIO servers (most common)
mcp-cli
> /server add sqlite stdio uvx mcp-server-sqlite --db-path mydata.db
> /server add playwright stdio npx @playwright/mcp@latest
> /server add time stdio uvx mcp-server-time

# Add HTTP servers with authentication
> /server add github --transport http --header "Authorization: Bearer ghp_token" -- https://api.github.com/mcp
> /server add myapi --transport http --env API_KEY=secret -- https://api.example.com/mcp

# Add SSE (Server-Sent Events) servers
> /server add events --transport sse -- https://events.example.com/sse

# Manage servers
> /server list                     # Show all servers
> /server disable sqlite           # Temporarily disable
> /server enable sqlite            # Re-enable
> /server remove myapi             # Remove user-added server

要点：

• 用户添加的服务会保存在 ~/.mcp-cli/preferences.json 中
• 应用重启后仍会保留
• 可启用或禁用，无需移除
• 支持 STDIO、HTTP 和 SSE 传输
• 支持用于身份验证的环境变量和标头

📈 高级用法示例

推理模型对比

# Compare reasoning across different models
> /provider ollama
> /model gpt-oss
> Think through this problem step by step: If a train leaves New York at 3 PM...
[See the complete thinking process with gpt-oss]

> /provider openai
> /model gpt-5
> Think through this problem step by step: If a train leaves New York at 3 PM...
[See GPT-5's reasoning approach]

> /provider anthropic
> /model claude-4-5-opus
> Think through this problem step by step: If a train leaves New York at 3 PM...
[See Claude 4.5's analytical process]

基于本地优先的推理工作流

# Start with default Ollama/gpt-oss (no API key needed)
mcp-cli chat --server sqlite

# Use reasoning model for complex problems
> Think through this database optimization problem step by step
[gpt-oss shows its complete thinking process before answering]

# Try different local models for different tasks
> /model llama3.3              # General purpose
> /model qwen2.5-coder         # For coding tasks
> /model deepseek-coder        # Alternative coding model
> /model granite3.3            # IBM's model
> /model gpt-oss               # Back to reasoning model

# Switch to cloud when needed (requires API keys)
> /provider openai
> /model gpt-5
> Complex enterprise architecture design...

> /provider anthropic
> /model claude-4-5-opus
> Detailed strategic analysis...

> /provider ollama
> /model gpt-oss
> Continue with local processing...

多提供商工作流

# Start with local reasoning (default, no API key)
mcp-cli chat --server sqlite

# Compare responses across providers
> /provider ollama
> What's the best way to optimize this SQL query?

> /provider openai gpt-5        # Requires API key
> What's the best way to optimize this SQL query?

> /provider anthropic claude-4-5-sonnet  # Requires API key
> What's the best way to optimize this SQL query?

# Use each provider's strengths
> /provider ollama gpt-oss      # Local reasoning, privacy
> /provider openai gpt-5        # Advanced reasoning
> /provider anthropic claude-4-5-opus  # Deep analysis
> /provider groq llama-3.1-70b  # Ultra-fast responses

使用推理的复杂工具工作流

# Use reasoning model for complex database tasks
> /model gpt-oss
> I need to analyze our database performance. Think through what we should check first.
[gpt-oss shows thinking: "First, I should check the table structure, then indexes, then query patterns..."]
[Tool: list_tables] → products, customers, orders

> Now analyze the indexes and suggest optimizations
[gpt-oss thinks through index analysis]
[Tool: describe_table] → Shows current indexes
[Tool: read_query] → Analyzes query patterns

> Create an optimization plan based on your analysis
[Complete reasoning process followed by specific recommendations]

自动化与脚本编写

# Batch processing with different models
for file in data/*.csv; do
  # Use reasoning model for analysis
  mcp-cli cmd --server sqlite \
    --model gpt-oss \
    --prompt "Analyze this data and think through patterns" \
    --input "$file" \
    --output "analysis/$(basename "$file" .csv)_reasoning.txt"
  
  # Use coding model for generating scripts
  mcp-cli cmd --server sqlite \
    --model qwen2.5-coder \
    --prompt "Generate Python code to process this data" \
    --input "$file" \
    --output "scripts/$(basename "$file" .csv)_script.py"
done

# Pipeline with reasoning
cat complex_problem.txt | \
  mcp-cli cmd --model gpt-oss --prompt "Think through this step by step" --input - | \
  mcp-cli cmd --model llama3.3 --prompt "Summarize the key points" --input - > solution.txt

性能监控

# Check provider and model performance
> /provider diagnostic
Provider Diagnostics
Provider      | Status      | Response Time | Features      | Models
ollama        | ✅ Ready    | 56ms         | 📡🔧         | gpt-oss, llama3.3, qwen3, ...
openai        | ✅ Ready    | 234ms        | 📡🔧👁️      | gpt-5, gpt-4o, o3, ...
anthropic     | ✅ Ready    | 187ms        | 📡🔧         | claude-4-5-opus, claude-4-5-sonnet, ...
azure_openai  | ✅ Ready    | 198ms        | 📡🔧👁️      | gpt-5, gpt-4o, ...
gemini        | ✅ Ready    | 156ms        | 📡🔧👁️      | gemini-2.0-flash, ...
groq          | ✅ Ready    | 45ms         | 📡🔧         | llama-3.1-70b, ...

# Check available models
> /models
Models for ollama (Current Provider)
Model                | Status
gpt-oss             | Current & Default (Reasoning)
llama3.3            | Available
llama3.2            | Available
qwen2.5-coder       | Available
deepseek-coder      | Available
granite3.3          | Available
... and 6 more

# Monitor tool execution with reasoning
> /verbose
> /model gpt-oss
> Analyze the database and optimize the slowest queries
[Shows complete thinking process]
[Tool execution with timing]

🔍 故障排除

常见问题

1. Ollama 未运行（默认提供商）：

   # Start Ollama service
   ollama serve
   
   # Or check if it's running
   curl http://localhost:11434/api/tags
   

2. 找不到模型：

   # For Ollama (default), pull the model first
   ollama pull gpt-oss      # Reasoning model
   ollama pull llama3.3     # Latest Llama
   ollama pull qwen2.5-coder # Coding model
   
   # List available models
   ollama list
   
   # For cloud providers, check supported models
   mcp-cli models openai     # Shows GPT-5, GPT-4, O3 models
   mcp-cli models anthropic  # Shows Claude 4.5, Claude 3.5 models
   

3. 找不到提供商或缺少 API 密钥：

   # Check available providers
   mcp-cli provider list
   
   # For cloud providers, set API keys
   mcp-cli provider set openai api_key sk-your-key
   mcp-cli provider set anthropic api_key sk-ant-your-key
   
   # Test connection
   mcp-cli provider diagnostic openai
   

4. Ollama 连接问题：

   # Check Ollama is running
   ollama list
   
   # Test connection
   mcp-cli provider diagnostic ollama
   
   # Configure custom endpoint if needed
   mcp-cli provider set ollama api_base http://localhost:11434
   

调试模式

启用详细日志以排查问题：

mcp-cli --verbose chat --server sqlite
mcp-cli --log-level DEBUG interactive --server sqlite

# Write debug logs to a rotating file (secrets are automatically redacted)
mcp-cli --log-file ~/.mcp-cli/logs/debug.log --server sqlite

🔒 安全注意事项

隐私与本地优先

• 默认在本地运行：Ollama 搭配 gpt-oss 在本地运行，保护你的数据隐私
• 无需云服务：无需依赖外部 API 即可使用完整功能

令牌与身份验证安全

• 安全的令牌存储：令牌存储在操作系统原生凭据存储中（macOS 钥匙串、Windows 凭据管理器、Linux Secret Service），服务标识符为 "mcp-cli"
• 多种存储后端：可根据安全需求选择钥匙串、加密文件或 HashiCorp Vault
• API 密钥：仅云服务提供商（OpenAI、Anthropic 等）需要 API 密钥，并通过令牌管理系统安全存储
• OAuth 2.0 支持：使用 PKCE 和资源指示符为 MCP 服务提供安全身份验证（RFC 7636、RFC 8707）

日志安全

• 机密信息脱敏：所有日志输出（控制台和文件）都会自动对 Bearer 令牌、API 密钥（sk-*）、OAuth 访问令牌和 Authorization 标头进行脱敏
• 滚动文件日志：可选的 --log-file，采用 JSON 格式，按 10MB 滚动，并保留 3 个备份文件

执行安全

• 工具验证：所有工具调用在执行前都会经过验证
• 超时保护：可配置超时，防止操作挂起（v0.13+）
• 断路器：自动检测故障并恢复，防止故障级联（v0.13+）
• 服务隔离：每个服务都在独立进程中运行
• 文件访问：可使用 --disable-filesystem 禁用文件系统访问
• 传输监控：自动检测连接故障并发出警告（v0.11+）

MCP Apps 安全

• Iframe 沙箱：应用在权限受限的沙箱 iframe 中运行
• 内容安全策略：验证并清理服务端提供的 CSP 域名
• 防止 XSS：在将工具名称和用户提供的内容注入模板前进行 HTML 转义
• URL 方案验证：ui/open-link 仅允许 http:// 和 https:// 方案
• 工具名称验证：桥接程序会拒绝不符合 MCP 规范字符集的工具名称
• WebSocket 来源验证（v0.20.1+）：本地 app-host 服务会拒绝 Origin 标头与自身 http://localhost:<port> 宿主页不匹配的任何 WebSocket 握手，防止无关网页连接到正在运行的应用桥接程序
• 工具权限强制执行（v0.20.1+）：当资源声明了允许调用的工具白名单时，桥接程序会对每次 tools/call 强制执行该白名单，而不只是检查工具名称语法
• 防 SSRF 的资源获取（v0.20.1+）：直接获取 HTTP(S) 资源时，会在连接前检查私有地址、环回地址和链路本地地址范围，并在每次重定向时重新检查

仪表板安全（v0.20.1+）

• WebSocket 来源验证：仪表板的 WebSocket 服务采用与 MCP Apps 相同的 Origin 检查
• 经过清理的 Markdown 渲染：助手聊天消息通过 DOMPurify 渲染，而非使用手写的清理器
• 经过转义的视图元数据：在将服务端声明的视图名称和图标插入面板标题前进行 HTML 转义
• 经过清理的 Agent/会话路径：在将 Agent 和会话标识符用作文件系统路径组件前进行清理

计划执行安全（v0.20.1+）

• 强制工具确认：计划执行（/plan、plan_create_and_execute）遵循与交互式聊天流程相同的确认工具偏好设置和受信任域名策略；如果需要确认但没有可用的提示，则拒绝调用，而不会在未经确认的情况下执行

🚀 性能特性

大模型提供商性能（v0.16+）

• 导入速度提升 52 倍：通过延迟加载，将耗时从 735ms 降至 14ms
• 客户端创建速度提升 112 倍：自动进行线程安全缓存
• llama.cpp 集成：通过自动复用 Ollama 模型，推理速度提升 1.53 倍（311 对 204 tokens/sec）
• 动态模型发现：基于能力选择模型，零开销

工具执行性能（v0.13+）

• 生产级中间件：超时、指数退避重试、熔断器和结果缓存
• 并发工具执行：多个工具可在适当协调下同时运行
• 连接健康监控：自动检测传输故障并从中恢复
• 优化的工具管理器：在保留所有功能的同时，从 2000 多行精简至约 800 行

运行时性能

• 本地处理：默认使用 Ollama 提供程序，以最大限度降低延迟
• 推理可见性：查看 gpt-oss、GPT-5 和 Claude 4 的 AI 思考过程
• 流式响应：实时生成响应
• 连接池：高效复用客户端连接
• 缓存：缓存工具元数据和提供程序配置
• 异步架构：全程采用非阻塞操作

📦 依赖项

核心依赖项按功能分组：

• cli：终端 UI 和命令框架（Rich、Typer、chuk-term）
• dev：开发工具、测试实用程序和代码检查工具
• chuk-tool-processor v0.22+：生产级工具执行，支持中间件、多种执行策略和可观测性
• chuk-llm v0.17+：统一的大模型提供程序，支持动态模型发现、基于能力的选择和 llama.cpp 集成
• chuk-term：增强型终端 UI，支持主题、提示词和跨平台使用

安装指定功能：

pip install "mcp-cli[cli]"        # Basic CLI features
pip install "mcp-cli[cli,dev]"    # CLI with development tools
pip install "mcp-cli[apps]"       # MCP Apps (interactive browser UIs)

🤝 参与贡献

欢迎贡献！详情请参阅贡献指南。

开发环境设置

git clone https://github.com/chrishayuk/mcp-cli
cd mcp-cli
pip install -e ".[cli,dev]"
pre-commit install

演示脚本

探索 MCP CLI 的功能：

# Command Mode Demos

# General cmd mode features (bash)
bash examples/cmd_mode_demo.sh

# LLM integration with cmd mode (bash)
bash examples/cmd_mode_llm_demo.sh

# Python integration example
uv run examples/cmd_mode_python_demo.py

# Custom Provider Management Demos

# Interactive walkthrough demo (educational)
uv run examples/custom_provider_demo.py

# Working demo with actual inference (requires OPENAI_API_KEY)
uv run examples/custom_provider_working_demo.py

# Simple shell script demo (requires OPENAI_API_KEY)
bash examples/custom_provider_simple_demo.sh

# Terminal management features (chuk-term)
uv run examples/ui_terminal_demo.py

# Output system with themes (chuk-term)
uv run examples/ui_output_demo.py

# Streaming UI capabilities (chuk-term)
uv run examples/ui_streaming_demo.py

运行测试

pytest
pytest --cov=mcp_cli --cov-report=html

📜 许可证

本项目采用 Apache License 2.0 许可，详情请参阅 LICENSE 文件。

🙏 致谢

• CHUK Tool Processor - 生产级异步工具执行，支持中间件和可观测性
• CHUK-LLM - 统一的大模型提供程序，支持动态模型发现、llama.cpp 集成，以及 GPT-5/Claude 4.5（v0.17+）
• CHUK-Term - 增强型终端 UI，支持主题和跨平台使用
• Rich - 美观的终端格式化
• Typer - 命令行框架
• Prompt Toolkit - 交互式输入

🔗 相关项目

• Model Context Protocol - 核心协议规范
• MCP Servers - 官方 MCP 服务实现
• CHUK Tool Processor - 生产级工具执行，支持中间件和可观测性
• CHUK-LLM - 大模型提供程序抽象，支持动态模型发现、GPT-5、Claude 4.5、O3 系列和 llama.cpp 集成
• CHUK-Term - 终端 UI 库，支持主题和跨平台使用