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 模型到各種資料來源和工具提供了標準化方式。