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

项目概述

MCP-CLI是一个功能强大、特性丰富的命令行界面工具，专门用于与模型上下文协议（Model Context Protocol，MCP）服务器交互。该工具通过集成CHUK-MCP协议库，为用户提供了与大语言模型（LLM）的无缝通信能力。

该客户端支持工具使用、对话管理和多种操作模式，核心协议实现已迁移到独立的包中，使得CLI专注于提供丰富的用户体验，而协议库负责处理通信层。

核心特性

🔄 多种操作模式

• 聊天模式（Chat Mode）：对话式界面，支持直接LLM交互和自动化工具使用
• 交互模式（Interactive Mode）：命令驱动界面，用于直接服务器操作
• 命令模式（Command Mode）：Unix友好模式，支持脚本化自动化和管道操作
• 直接命令：无需进入交互模式即可运行单个命令

🌐 多提供商支持

• OpenAI集成：支持gpt-4o-mini、gpt-4o、gpt-4-turbo等模型
• Ollama集成：支持llama3.2、qwen2.5-coder等本地模型
• 可扩展架构：支持添加其他提供商

🛠️ 强大的工具系统

• 自动发现服务器提供的工具
• 服务器感知的工具执行
• 工具调用历史跟踪和分析
• 支持复杂的多步骤工具链

💬 高级对话管理

• 完整的对话历史跟踪
• 支持过滤和查看特定消息范围
• JSON导出功能，用于调试或分析
• 对话压缩功能，减少token使用

🎨 丰富的用户体验

• 上下文感知的命令自动完成
• 彩色格式化的控制台输出
• 长时间运行操作的进度指示器
• 详细的帮助和文档

🔧 可靠的资源管理

• 适当的异步IO资源清理
• 优雅的错误处理
• 干净的终端恢复
• 支持多个同时服务器连接

系统要求

• Python 3.11或更高版本
• 对于OpenAI：需要在OPENAI_API_KEY环境变量中设置有效的API密钥
• 对于Ollama：需要本地Ollama安装
• 服务器配置文件（默认：server_config.json）
• CHUK-MCP协议库

安装方法

标准安装

# 克隆仓库
git clone https://github.com/chrishayuk/mcp-cli
cd mcp-cli

# 安装包和开发依赖
pip install -e ".[cli,dev]"

# 运行CLI
mcp-cli --help

使用UV管理依赖

# 安装UV（如果未安装）
pip install uv

# 安装依赖
uv sync --reinstall

# 使用UV运行
uv run mcp-cli --help

使用指南

全局选项

所有命令都支持以下全局选项：

• --server：指定要连接的服务器（多个服务器用逗号分隔）
• --config-file：服务器配置文件路径（默认：server_config.json）
• --provider：使用的LLM提供商（openai或ollama，默认：openai）
• --model：使用的特定模型（依赖于提供商的默认值）
• --disable-filesystem：禁用文件系统访问（默认：true）

聊天模式

聊天模式提供与LLM的对话界面，在需要时自动使用可用工具：

# 基础聊天模式
mcp-cli chat --server sqlite

# 指定提供商和模型
mcp-cli chat --server sqlite --provider openai --model gpt-4o
mcp-cli chat --server sqlite --provider ollama --model llama3.2

聊天模式斜杠命令

在聊天模式中，可以使用以下斜杠命令：

帮助命令：

• /help：显示可用命令
• /help <command>：显示特定命令的详细帮助
• /quickhelp或/qh：显示常用命令的快速参考

工具相关：

• /tools：显示所有可用工具及其服务器信息
• /tools --all：显示包含参数的详细工具信息
• /tools --raw：显示原始工具定义
• /toolhistory或/th：显示当前会话中的工具调用历史

对话管理：

• /conversation或/ch：显示对话历史
• /save <filename>：将对话历史保存到JSON文件
• /compact：将对话历史压缩为摘要

界面控制：

• /cls：清除屏幕但保留对话历史
• /clear：清除屏幕和对话历史
• /verbose或/v：切换详细和简洁工具显示模式

交互模式

交互模式提供命令行界面，使用斜杠命令进行直接服务器交互：

mcp-cli interactive --server sqlite

交互模式命令

• /ping：检查服务器是否响应
• /prompts：列出可用提示
• /tools：列出可用工具
• /resources：列出可用资源
• /chat：进入聊天模式
• /exit或/quit：退出程序

命令模式

命令模式提供Unix友好的接口，用于自动化和管道集成：

mcp-cli cmd --server sqlite [options]

命令模式选项

• --input：输入文件路径（使用-表示stdin）
• --output：输出文件路径（使用-表示stdout，默认）
• --prompt：提示模板（使用{{input}}作为输入占位符）
• --raw：输出原始文本而不格式化
• --tool：直接调用特定工具
• --tool-args：工具调用的JSON参数
• --system-prompt：自定义系统提示

命令模式示例

# 总结文档
mcp-cli cmd --server sqlite --input document.md --prompt "Summarize this: {{input}}" --output summary.md

# 处理stdin并输出到stdout
cat document.md | mcp-cli cmd --server sqlite --input - --prompt "Extract key points: {{input}}"

# 直接调用工具
mcp-cli cmd --server sqlite --tool list_tables --raw
mcp-cli cmd --server sqlite --tool read_query --tool-args '{"query": "SELECT COUNT(*) FROM users"}'

# 批量处理
ls *.md | parallel mcp-cli cmd --server sqlite --input {} --output {}.summary.md --prompt "Summarize: {{input}}"

直接命令

无需进入交互模式即可运行单个命令：

# 列出可用工具
mcp-cli tools list --server sqlite

# 调用特定工具
mcp-cli tools call --server sqlite

# 列出可用提示
mcp-cli prompts list --server sqlite

# 检查服务器连接
mcp-cli ping --server sqlite

# 列出可用资源
mcp-cli resources list --server sqlite

配置文件

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

{
  "mcpServers": {
    "sqlite": {
      "command": "python",
      "args": ["-m", "mcp_server.sqlite_server"],
      "env": {
        "DATABASE_PATH": "your_database.db"
      }
    },
    "another-server": {
      "command": "python",
      "args": ["-m", "another_server_module"],
      "env": {}
    }
  }
}

项目结构

src/
├── mcp_cli/
│   ├── chat/                    # 聊天模式实现
│   │   ├── commands/            # 聊天斜杠命令
│   │   │   ├── __init__.py      # 命令注册系统
│   │   │   ├── conversation.py  # 对话管理
│   │   │   ├── help.py          # 帮助命令
│   │   │   ├── tools.py         # 工具命令
│   │   │   └── ...
│   │   ├── chat_context.py      # 聊天会话状态管理
│   │   ├── chat_handler.py      # 主聊天循环处理器
│   │   ├── command_completer.py # 命令自动完成
│   │   └── ui_manager.py        # 用户界面
│   ├── commands/                # CLI命令
│   │   ├── chat.py              # 聊天命令
│   │   ├── cmd.py               # 命令模式
│   │   ├── interactive.py       # 交互模式
│   │   └── ...
│   ├── llm/                     # LLM客户端实现
│   │   ├── providers/           # 提供商特定客户端
│   │   │   ├── base.py          # 基础LLM客户端
│   │   │   └── openai_client.py # OpenAI实现
│   │   └── llm_client.py        # 客户端工厂
│   ├── ui/                      # 用户界面组件
│   │   ├── colors.py            # 颜色定义
│   │   └── ui_helpers.py        # UI工具
│   ├── main.py                  # 主入口点
│   └── config.py                # 配置加载器

使用示例

自动工具执行

在聊天模式中，MCP CLI可以自动执行服务器提供的工具：

You: What tables are available in the database?
Assistant: Let me check for you.
[Tool Call: list_tables]
I found the following tables in the database:
- users
- products  
- orders
- categories

You: How many users do we have?
Assistant: I'll query the database for that information.
[Tool Call: read_query]
There are 873 users in the database.

自动化脚本

命令模式支持强大的自动化脚本：

#!/bin/bash
# 分析多个文档的示例脚本

# 处理当前目录中的所有markdown文件
for file in *.md; do
    echo "Processing $file..."
    
    # 生成摘要
    mcp-cli cmd --server sqlite --input "$file" \
        --prompt "Summarize this document: {{input}}" \
        --output "${file%.md}.summary.md"
    
    # 提取实体
    mcp-cli cmd --server sqlite --input "$file" \
        --prompt "Extract all company names, people, and locations from this text: {{input}}" \
        --output "${file%.md}.entities.txt" --raw
done

# 创建综合报告
echo "Creating final report..."
cat *.entities.txt | mcp-cli cmd --server sqlite --input - \
    --prompt "Analyze these entities and identify the most frequently mentioned:" \
    --output report.md

对话历史管理

跟踪和管理对话历史：

> /conversation
Conversation History (12 messages)
# | Role | Content
1 | system | You are an intelligent assistant capable of using t...
2 | user | What tables are available in the database?
3 | assistant | Let me check for you.
4 | assistant | [Tool call: list_tables]
...

> /conversation 4
Message #4 (Role: assistant)
[Tool call: list_tables]
Tool Calls:
1. ID: call_list_tables_12345678, Type: function, Name: list_tables
Arguments: {}

> /save conversation.json
Conversation saved to conversation.json

> /compact
Conversation history compacted with summary.
Summary:
The user asked about database tables, and I listed the available tables (users, products, orders, categories). The user then asked about the number of users, and I queried the database to find there are 873 users.

依赖管理

CLI使用可选的依赖组进行组织：

• cli：丰富的终端UI、命令自动完成和提供商集成
• dev：开发工具和测试工具
• wasm：（为未来WebAssembly支持保留）
• chuk-mcp：协议实现库（核心依赖）

安装特定extras：

pip install "mcp-cli[cli]"        # 基础CLI功能
pip install "mcp-cli[cli,dev]"    # CLI + 开发工具

贡献指南

欢迎贡献！请遵循以下步骤：

1. Fork仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开Pull Request

关于模型上下文协议（MCP）

MCP是一个开放协议，标准化了应用程序为LLM提供上下文的方式。可以将MCP比作AI应用程序的USB-C端口。正如USB-C为连接设备到各种外围设备和配件提供了标准化方式，MCP为连接AI模型到各种数据源和工具提供了标准化方式。