功能強大的模型上下文協定 (MCP) 命令列介面工具
NOASSERTIONPython 1.4kchrishayukmcp-cli Last Updated: 2025-07-02
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 + 開發工具
貢獻指南
歡迎貢獻!請遵循以下步驟:
- Fork 儲存庫
- 建立功能分支 (
git checkout -b feature/amazing-feature
) - 提交更改 (
git commit -m 'Add some amazing feature'
) - 推送到分支 (
git push origin feature/amazing-feature
) - 開啟合併請求 (Pull Request)
關於模型上下文協議(MCP)
MCP 是一個開放協議,標準化了應用程式為 LLM 提供上下文的方式。可以將 MCP 比作 AI 應用程式的 USB-C 埠。正如 USB-C 為連接設備到各種週邊設備和配件提供了標準化方式,MCP 為連接 AI 模型到各種資料來源和工具提供了標準化方式。