使用说明

MCP客户端

用于测试模型上下文协议（MCP）服务器的最小客户端，具有AI集成功能，支持OpenAI和Ollama（本地LLM）。

特性

MCP服务器集成：连接到任何MCP服务器（Python脚本或Docker容器）
多服务器支持：通过配置和使用多个MCP服务器 conf/mcp-servers.json
基于Docker的服务器：通过Docker的官方MCP服务器（获取、文件系统、内存、git、时间）
服务器自检：列出可用的工具、提示和资源 --members 选项
人工智能聊天：使用AI驱动的工具执行交互式聊天 --chat 选项
双LLM支持：使用OpenAI API或本地Ollama模型
自动检测：自动选择最佳可用提供程序

安装

克隆或下载存储库
安装依赖项：

# Using pip
pip install -e .

# Or using uv (recommended)
uv sync

设置您的法学硕士提供者：

选项A:OpenAI（云）

export OPENAI_API_KEY="your-openai-api-key"

选项B:Ollama（本地-建议用于MacBook M3）

从以下位置安装Ollamahttps://ollama.ai
拉一个推荐的模型：

# Best balance for MacBook M3 (default)
ollama pull qwen2.5:7b

# Other excellent options:
ollama pull llama3.2:3b      # Fast and efficient (3GB RAM)
ollama pull llama3.2:1b      # Ultra lightweight (1GB RAM)
ollama pull phi4:14b         # High quality (8GB RAM)

Ollama自动运行 http://localhost:11434

基于Docker的MCP服务器（新！）

客户端现在支持在Docker容器中运行的官方MCP服务器。这些服务器已在中预先配置 conf/mcp-servers.json.

快速设置

使管理脚本可执行:
```
chmod +x mcp-servers.sh
```
拉取Docker镜像:
```
./mcp-servers.sh pull
```
列出可用服务器:
```
python3 -m mcp_client --list-servers
```

可用的Docker服务器

服务器	描述
获取	Web内容提取和转换为Markdown
文件系统	使用沙盒访问保护文件操作
记忆	基于知识图的持久记忆
版本控制系统	Git存储库操作
时间	时间和时区实用程序

有关详细文档，请参阅： conf/MCP_SERVERS_GUIDE.md

用法

列出可用服务器

显示所有已配置的MCP服务器：

python3 -m mcp_client --list-servers

使用基于Docker的服务器

按名称使用任何配置的服务器：

# Fetch server - web content fetching
python3 -m mcp_client --server fetch --chat

# Filesystem server - file operations
python3 -m mcp_client --server filesystem --members

# Memory server - knowledge graph
python3 -m mcp_client --server memory --chat --provider ollama

# Git server - repository operations
python3 -m mcp_client --server git --members

# Time server - timezone utilities
python3 -m mcp_client --server time --chat

使用自定义Python服务器（传统模式）

你仍然可以直接使用Python脚本服务器：

# List server capabilities
python3 -m mcp_client examples/mcp_server/mcp_server.py --members

# Start interactive chat
python3 -m mcp_client examples/mcp_server/mcp_server.py --chat

交互式聊天模式选项

# Auto-detect provider (uses Ollama if available, otherwise OpenAI)
python3 -m mcp_client --server fetch --chat

# Explicitly use Ollama with default model (qwen2.5:7b)
python3 -m mcp_client --server fetch --chat --provider ollama

# Use a specific Ollama model
python3 -m mcp_client --server fetch --chat --provider ollama --model llama3.2:3b

# Use OpenAI
python3 -m mcp_client --server fetch --chat --provider openai

# Use specific OpenAI model
python3 -m mcp_client --server fetch --chat --provider openai --model gpt-4o

# Enable verbose Docker output (for debugging)
python3 -m mcp_client --server fetch --chat --docker-verbose

配置

环境变量

您可以使用环境变量配置客户端：

# OpenAI configuration
export OPENAI_API_KEY="sk-..."
export OPENAI_MODEL="gpt-4o-mini"  # Default model

# Ollama configuration
export OLLAMA_MODEL="qwen2.5:7b"   # Default model
export OLLAMA_BASE_URL="http://localhost:11434"  # Default URL

服务器配置文件

MCP服务器配置在 conf/mcp-servers.json。此文件包括：

服务器名称和描述
Docker镜像和命令
环境变量
挂载目录（用于文件系统/git服务器）
卷配置（用于内存服务器）
能力和工具

要添加新服务器，请按照现有模式编辑此文件。看 conf/README.md 了解详情。

提供商选择逻辑

客户端自动按以下顺序选择提供者：

如果 --provider 如果指定了，请使用该提供程序
如果 OPENAI_API_KEY 已设置，请使用OpenAI
否则，请使用Ollama（当地）

Docker管理脚本

这 mcp-servers.sh 该脚本有助于管理基于Docker的MCP服务器：

# Pull all official MCP server images
./mcp-servers.sh pull

# Build images locally from source
./mcp-servers.sh build

# List installed images
./mcp-servers.sh list

# Test a specific server
./mcp-servers.sh test fetch

# Show information about servers
./mcp-servers.sh info

# Clean up (remove images and volumes)
./mcp-servers.sh clean

# Show help
./mcp-servers.sh help

MacBook M3的推荐型号

基于您的MacBook M3硬件：

型号	大小	RAM	最适合
qwen2.5:7b	4.7GB	8GB	最佳整体平衡（默认）
llama3.2:3b	2GB	4GB	响应速度快，质量好
llama3.2:1b	1GB	2GB	超快速、简单的任务
phi4:14b	8GB	12GB	最高质量，较慢

示例会话

$ python3 -m mcp_client --server fetch --chat --provider ollama

Using configured server: fetch
Description: Web content fetching and conversion for efficient LLM usage
LLM: Ollama with model: qwen2.5:7b

MCP Client's Chat Started!
Type your queries or 'quit' to exit.

You: Fetch the content from https://example.com

[Used fetch({'url': 'https://example.com', 'max_length': 5000})]
Assistant: I've fetched the content from example.com. The page contains...

You: quit

Goodbye!

需求

Python>=3.13
MCP Python SDK(mcp>=1.22.0)
OpenAI Python SDK(openai>=2.8.1)-可选，用于OpenAI支持
Ollama Python SDK(ollama>=0.4.0)-可选，用于本地LLM支持
Docker>=20.10.0-基于Docker的服务器需要
OpenAI API密钥（如果使用OpenAI）
Ollama在本地安装（如果使用本地型号）

建筑

客户端使用模块化架构：

核心组件

MCPClient：支持Python和Docker服务器的主客户端类
ServerConfigLoader：从JSON加载和管理服务器配置
BaseQueryHandler：LLM提供者的抽象基类
OpenAIQueryHandler：OpenAI API实现
OllamaQueryHandler：Olama当地实施
create_query_handler()：具有自动检测功能的出厂功能

服务器类型

Python脚本服务器 （遗留）：使用MCP SDK直接编写Python脚本
Docker服务器 （新增）：Docker容器中的官方MCP服务器

这种设计使得添加新的服务器和LLM提供程序变得容易。

故障排除

Docker问题

# Check if Docker is running
docker info

# Check if images are available
docker images | grep mcp

# Pull missing images
./mcp-servers.sh pull

# Enable verbose output
python3 -m mcp_client --server fetch --chat --docker-verbose

Ollama连接问题

# Check if Ollama is running
curl http://localhost:11434/api/tags

# Start Ollama if needed
ollama serve

未找到型号

# List available models
ollama list

# Pull the missing model
ollama pull qwen2.5:7b

OpenAI API关键问题

# Check if key is set
echo $OPENAI_API_KEY

# Set it if missing
export OPENAI_API_KEY="your-key-here"

服务器配置问题

# List available servers
python3 -m mcp_client --list-servers

# Check configuration file
cat conf/mcp-servers.json

# Validate JSON syntax
python3 -c "import json; json.load(open('conf/mcp-servers.json'))"

文档

主要文件：此自述文件
Docker服务器指南: conf/MCP_SERVERS_GUIDE.md
配置README: conf/README.md
MCP官方文件: https://modelcontextprotocol.io
MCP服务器存储库: https://github.com/modelcontextprotocol/servers

项目结构

mcp-client/
├── conf/
│   ├── mcp-servers.json          # Server configurations
│   ├── MCP_SERVERS_GUIDE.md      # Detailed server documentation
│   └── README.md                  # Configuration quick start
├── examples/
│   └── mcp_server/                # Example Python MCP server
├── src/mcp_client/
│   ├── __init__.py
│   ├── __main__.py                # Entry point
│   ├── cli.py                     # Command-line interface
│   ├── config.py                  # Server configuration loader
│   ├── mcp_client.py              # Main client class
│   ├── handlers.py                # LLM provider handlers
│   └── chat.py                    # Chat interface
├── mcp-servers.sh                 # Docker management script
├── pyproject.toml                 # Project configuration
└── README.md                      # This file

贡献

欢迎投稿！需要改进的地方：

额外的LLM提供商支持
更多MCP服务器集成
增强的错误处理
性能优化
文档改进

许可证

MIT许可证-请参阅 LICENSE.txt

链接

仓库: https://github.com/joao-parana/mcp-client
问题: https://github.com/joao-parana/mcp-client/issues
MCP协议: https://modelcontextprotocol.io
官方MCP服务器: https://github.com/modelcontextprotocol/servers