MCP协议命令行客户端

MCP客户端

用于与模型上下文协议（MCP）服务器交互的命令行客户端。支持基于stdio、SSE和HTTP的传输，并通过Azure OpenAI集成进行工具调用。

特性

• 多种传输协议

  • Stdio（本地Python/Node服务器和npm包）
  • SSE（服务器发送事件）
  • 流式HTTP（基于HTTP POST的JSON-RPC）
  • SSE和HTTP之间的自动检测和回退

• 工具执行

  • 从MCP服务器自动发现工具
  • Azure OpenAI集成用于智能工具选择
  • 具有工具调用处理功能的多回合对话
  • 对话历史管理

• 开发者友好

  • 全面记录 logs/mcp_client.log
  • 支持向stdio服务器传递额外参数
  • 具有刷新功能的交互式聊天循环

安装

来源

# Clone or download the repository
cd mcp-client

# Install with UV (recommended)
uv sync

# Or with pip
pip install -e .

需求

• Python 3.13+
• Azure OpenAI API凭据（用于工具执行）

配置

LLM配置文件（llms.json）

此客户端使用存储在中的LLM配置文件 llms.json （通过CLI管理）。

要管理配置文件，请执行以下操作：

mcp-client -l

配置文件看起来像：

[
  {
    "name": "default-azure-openai",
    "type": "azure_openai",
    "endpoint": "https://<your-resource>.openai.azure.com/openai/v1/",
    "api_key": "<YOUR_API_KEY>",
    "model": "<your-deployment-name>",
    "api_version": "2024-12-01-preview"
  }
]

笔记：

• 目前仅支持API密钥身份验证。
• 对于Azure OpenAI兼容的端点， model 是您的部署名称。

指令文件（Instruction_files.json）

您可以存储一个或多个markdown指令文件（例如，内部Copilot指令提示），并在聊天会话期间应用一个。

• 在交互模式下：选择 i=管理指令文件 列出/添加/删除已保存的文件。
• 保存指令文件路径： mcp-client -i （提示）或 mcp-client -i <path>.
• 使用指令文件运行一次聊天： mcp-client -c -i <path>.
• 如果你跑 mcp-client -c 没有 -i，客户端将询问您是否要使用已保存的指令文件。

例子：

mcp-client -c -i InstructionFiles/copilot-instructions.md

护栏（减少幻觉）

此客户端可以在严格模式下运行，不鼓励LLM编造细节。在严格模式下，助理应：

• 当关键上下文缺失时，提出1-3个澄清问题
• 避免发明模式/标识符/命令/配置键
• 说它不知道何时无法从对话和工具输出中确定正确答案
• 用占位符将任何示例明确标记为模板

使用以下环境变量进行配置：

# Strict mode (default: true)
MCP_STRICT_MODE=true

# Lower temperature reduces creative guesswork (default: 0)
AZURE_OPENAI_TEMPERATURE=0

用法

快速启动（推荐）

1. 安装依赖项：

uv sync

2. 添加LLM配置文件：

mcp-client -l

3. 开始聊天（您将选择LLM配置文件和MCP服务器）：

mcp-client -c

基本命令

mcp-client <server_script_path_or_url> [extra_args...]

如果要为此运行应用指令文件：

mcp-client <server_script_path_or_url> -i InstructionFiles/copilot-instructions.md

例子

交互模式

如果你跑 mcp-client 没有参数，您将看到一个简单的菜单：

Options: m=manage MCP servers, l=manage LLM profiles, i=manage instruction files, c=chat, q=quit

在聊天模式下，键入您的问题，客户端将根据需要调用工具。

特殊命令

• quit 或 exit --关闭客户端
• refresh --清除对话历史记录

建筑

核心组件

• MCP客户端 --主类处理所有MCP服务器通信
  • connect_to_server() --自动检测并连接到任何MCP服务器
  • connect_to_sse_server() --SSE运输处理程序
  • connect_to_http_server() --流式HTTP处理程序
  • connect_to_stdio_server() --Stdio运输处理器
  • process_query() --用于工具调用的Azure OpenAI集成
  • chat_loop() --交互式用户界面

运输选择

客户端会自动检测服务器类型：

• URL（http/https） → 先尝试SSE，然后回到HTTP
• 文件路径（.py/.js） → 使用stdio传输
• 包名 （例如。， @playwright/mcp) → 使用npx+stdio

日志记录

所有活动都记录到 logs/mcp_client.log。请检查此文件以了解：

• 连接详情
• 每个服务器提供的工具
• 查询处理信息
• 工具执行结果
• 错误诊断

发展

项目结构

mcp-client/
├── client/
│   ├── __init__.py
│   ├── __main__.py          # CLI entry point
│   ├── mcp_client.py        # Core MCPClient class
├── logs/                    # Generated logs
├── pyproject.toml           # Package metadata
├── README.md                # This file
└── requirements.txt         # Dependencies (optional)

以开发模式运行

# From the project root
python -m client https://learn.microsoft.com/api/mcp

建筑

uv pip install build
python -m build

这将创建：

• dist/mcp_client-0.1.0-py3-none-any.whl （车轮）
• dist/mcp_client-0.1.0.tar.gz （来源）

故障排除

“ModuleNotFoundError:没有名为'client'的模块”

• 确保你已经跑过了 uv sync 从项目根

“mcp客户端：找不到命令”

• 激活您的虚拟环境： .venv\Scripts\Activate.ps1 （PowerShell）或 source .venv/bin/activate （Linux/Mac）
• 重新安装： uv sync

Azure OpenAI错误

• 验证 llms.json 具有有效的配置文件，并且您选择了它
• 检查部署名称是否匹配 model

连接失败

• 对于URL：检查网络连接以及端点是否可访问
• 对于本地服务器：验证文件路径是否正确
• 检查 client/logs/mcp_client.log 有关详细的错误信息

安全

• llms.json, servers.json，以及 instruction_files.json 是本地配置文件（通常为gitignored）。
• 对待 llms.json 就像一个秘密，因为它包含你的API密钥。
• 定期轮换Azure OpenAI API密钥。

许可证

MIT许可证——有关详细信息，请参阅许可证文件

支持

对于问题或疑问：

1. 检查 client/logs/mcp_client.log 用于详细诊断
2. 验证Azure OpenAI凭据和配置
3. 确保MCP服务器正在运行且可访问
4. 根据您的用例查看上面的示例

贡献

欢迎投稿！请随时提交问题或拉取请求。