使用说明

模型上下文协议（MCP）网络工具演示

模型上下文协议的全面演示，包括正确的LLM驱动工具选择、网络实用程序和实时工作流可视化。该项目展示了MCP如何使智能AI代理通过结构化协议推理和执行工具。

特性

🖥️ MCP服务器（端口8000）

网络时间工具：从可配置的NTP服务器检索准确的时间
Ping工具：测试指定主机的网络连接和延迟
Redis缓存：可选的Redis集成用于响应缓存
环境配置：可通过环境变量完全配置

🤖 MCP客户端（端口8001）

正确的MCP协议：LLM接收工具模式并做出结构化的工具选择决策
Olama集成：本地LLM与Qwen2.5:7b-结构模型的集成
两阶段处理：初始工具选择，然后与工具结果进行响应集成
结构化工具请求：LLM以JSON响应，指定确切的工具和参数
会话管理：与调试端点的上下文感知对话

🌐 Web用户界面（端口5173）

现代聊天界面：使用React+Vite构建的流畅、响应式聊天UI
MCP工作流可视化：完整MCP协议流的实时显示
按时间顺序跟踪组件：显示UI→ 客户端→ 奥拉玛→ 服务器交互
详细数据交换：完整的请求/响应有效载荷和时间信息
教育演示模式：非常适合理解MCP协议的工作原理
工具可见性：显示每次响应中使用了哪些MCP工具的视觉徽章
移动响应：在台式机、平板电脑和移动设备上运行良好

📖 新的模型上下文协议？ 看 docs/MCP_EXPLAINED.md 了解MCP概念及其如何应用于本项目的全面指南。

🔧 想了解客户端架构吗？ 看 docs/CLIENT_ARCHITECTURE.md 有关MCP客户端如何与本地LLM集成的详细信息。

🤖 为这个项目构建人工智能代理？ 看 .github/copilot-instructions.md 用于AI编码代理指导。

🍎 macOS开发人员？ 看 docs/MACOS_DEV.md 用于平台特定的设置和优化。

🐧 Linux开发人员？ 看 docs/LINUX_DEV.md 用于Linux/Ubuntu环境设置。

快速开始

自动设置（推荐）

使用自动设置脚本配置所有内容：

git clone <repository-url>
cd model-context-protocol
bash scripts/setup.sh

安装脚本将：

✅ 检查Python 3.10+和Node.js安装
✅ 创建并激活Python虚拟环境
✅ 安装所有Python依赖项（生产+测试）
✅ 为UI安装Node.js依赖项
✅ 使用Chromium浏览器配置Playwright
✅ 创建 .env 和 .env.client 从模板

安装完成后，激活虚拟环境并启动服务：

source .venv/bin/activate  # On Windows: .venv\Scripts\activate
npm start

手动设置

克隆和设置:

git clone <repository-url>
cd model-context-protocol
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

再进行:

# Install all dependencies (Python + Node.js + UI + Playwright)
npm run install:all

# Or install separately:
pip install -r requirements.txt
pip install -r requirements-test.txt
cd ui && npm install && npx playwright install chromium

配置环境:

cp .env.example .env
cp .env.client.example .env.client
# Edit .env and .env.client with your settings

启动所有服务:
```
npm start
# Or: bash scripts/start.sh
```

测试MCP服务器:

# Health check
curl http://localhost:8000/health

# List available tools
curl http://localhost:8000/v1/tools/list

# Test network time
curl -X POST http://localhost:8000/v1/tools/call \
  -H "Content-Type: application/json" \
  -d '{"tool_name": "get_network_time", "arguments": {}, "session_id": "test"}'

# Test ping
curl -X POST http://localhost:8000/v1/tools/call \
  -H "Content-Type: application/json" \
  -d '{"tool_name": "ping_host", "arguments": {"hostname": "google.com"}, "session_id": "test"}'

Web用户界面

现代、响应式聊天界面可用于与MCP系统轻松交互。

UI快速入门

启动所有服务 （从项目根开始）：
```
npm start
# Or: bash scripts/start.sh
```
此单个命令启动：
- MCP服务器（端口8000）
- MCP客户端（端口8001）
- Web用户界面（端口5173）
在浏览器中打开：导航到 http://localhost:5173

UI功能

Web UI提供了一个直观的聊天界面，包括：

🎨 现代黑暗主题 -易于眼睛长时间使用
💬 实时聊天 -MCP客户端的即时响应
🔧 工具徽章 -显示使用了哪些工具（NTP时间、ping）的视觉指示器
📱 完全响应 -适应任何屏幕尺寸
⚡ 快速轻便 -使用Vite构建，可在开发过程中即时热加载
🗨️ 清除聊天 -清除对话历史记录的按钮
🎯 自动滚动 -始终显示最新消息

交互示例

在UI中尝试这些查询：

“现在几点了？”→ Uses get_network_time 工具
“你能ping谷歌吗？”→ Uses ping_host 工具
“你好，你能帮我什么吗？”→ 一般对话

看 ui/README.md 了解更多特定于UI的详细信息。

MCP客户端设置

该项目包括一个完整的MCP客户端，该客户端与当地Ollama模型集成，用于智能工具使用。有关详细的体系结构信息，请参见 docs/CLIENT_ARCHITECTURE.md 和 docs/CLIENT_README.md.

先决条件

安装Ollama：参观奥拉玛并安装Ollama
拉动Qwen2.5型号: ollama pull qwen2.5:7b-instruct

客户端设置

配置客户端环境:

cp .env.client.example .env.client
# Edit .env.client with your preferred settings

启动客户端 （在新航站楼中）：
```
uvicorn client:app --port 8001
```

测试客户端:

# Health check
curl http://localhost:8001/health

# Chat with time question
curl -X POST http://localhost:8001/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "What time is it?", "session_id": "demo"}'

# Chat with ping question
curl -X POST http://localhost:8001/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Can you ping google.com?", "session_id": "demo"}'

# General conversation
curl -X POST http://localhost:8001/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, what can you help me with?", "session_id": "demo"}'

配置

服务器是通过环境变量配置的。复制 .env.example 到 .env 并根据需要进行修改：

Redis配置

REDIS_HOST：Redis服务器主机名（默认值：localhost）
REDIS_PORT：Redis服务器端口（默认值：6379）
REDIS_PASSWORD：Redis密码（可选）
REDIS_DB：Redis数据库编号（默认值：0）

NTP配置

NTP_SERVER：主NTP服务器（默认：pool.NTP.org）
NTP_BACKUP_SERVER：备份NTP服务器（默认：time.google.com）
NTP_TIMEOUT：NTP请求超时（秒）（默认值：5）

服务器配置

SERVER_PORT：FastAPI服务器端口（默认值：8000）
LOG_LEVEL：日志记录级别（默认值：INFO）

客户端配置（.env.Client）

OLLAMA_URL：ollama服务器URL（默认值：http://localhost:11434)
OLLAMA_MODEL：要使用的模型（默认值：qwen2.5:7b-struct）
MCP_SERVER_URL：MCP服务器URL（默认值：http://localhost:8000)
CLIENT_PORT：客户端-服务器端口（默认值：8001）

看 .env.示例和 .env.client.example 获取完整的配置模板。

API终点

MCP服务器（端口8000）

GET /health -返回服务器状态和Redis连接状态
GET /v1/tools/list -列出所有可用工具
POST /v1/tools/call -执行特定工具
POST /v1/generate -带有工具推理循环的LLM生成端点

MCP客户端（端口8001）

GET /health -返回客户端、Ollama和MCP服务器状态
GET /tools -列出MCP服务器上的可用工具
POST /chat -聊天界面，智能工具使用
POST /test-tool -直接工具测试端点

可用工具

get_network_time

从NTP服务器检索准确的时间。

参数：无
退货：UTC时间戳、可读时间、偏移量和源服务器

ping_host

测试网络连接和延迟。

参数:
- hostname （必填）：ping的主机名或IP地址
退货：主机状态、延迟、数据包丢失和输出片段

发展

服务器包括几个标记为增强的区域：

增强ping解析以更好地提取延迟（请参阅 server.py._execute_ping)
具有会话管理功能的强大Redis缓存（请参阅 server.py.LLMService.generate)
LLM与工具使用推理循环完全集成（参见 server.py.LLMService.generate)
Redis连接弹性改进（参见 server.py 启动事件）

有关详细的开发工作流程和测试，请参阅：

test_client.py -端到端客户端测试
test_config.py -服务器配置验证
客户_建筑.md -客户端实施细节
.github/copilot-instructions.md -AI代理指导

项目结构

model-context-protocol/
├── server.py             # MCP Server (FastAPI, port 8000)
├── client.py             # MCP Client (Ollama integration, port 8001)
├── requirements.txt      # Python dependencies (server + client)
├── requirements-test.txt # Python test dependencies
├── package.json          # NPM scripts for unified commands
├── .env.example          # Server environment template
├── .env.client.example   # Client environment template
├── docs/                 # Documentation
│   ├── CHANGELOG.md      # Version history
│   ├── CLIENT_ARCHITECTURE.md
│   ├── CLIENT_README.md
│   ├── LINUX_DEV.md
│   ├── MACOS_DEV.md
│   ├── MCP_EXPLAINED.md
│   ├── PROJECT_SUMMARY.md
│   ├── TESTING.md
│   └── WINDOWS_DEV.md
├── scripts/              # Shell scripts
│   ├── start.sh          # Start all services
│   ├── run-tests.sh      # Run all tests
│   └── test.sh           # Quick test suite
├── tests/                # Backend tests (pytest)
│   ├── conftest.py       # Test fixtures
│   ├── test_server.py    # Server tests
│   └── test_client.py    # Client tests
├── ui/                   # Web UI (React + Vite)
│   ├── src/
│   │   ├── App.jsx       # Main chat component
│   │   ├── App.css       # Styles
│   │   └── main.jsx      # Entry point
│   ├── tests/            # UI tests (Playwright)
│   │   └── ui.spec.js
│   ├── playwright.config.js
│   └── package.json
├── test_client.py        # End-to-end client test
└── test_config.py        # Configuration validation

文档

该项目包括针对不同受众和目的的全面文档：

📚 核心文件

docs/MCP_EXPLAINED.md -模型上下文协议概念的全面介绍
docs/CLIENT_ARCHITECTURE.md -客户端架构和LLM集成细节
docs/CLIENT_README.md -客户特定的文档和使用
文档/项目_ SUMMARY.md -高级项目概述和目标

�️ 平台特定指南

docs/MACOS_DEV.md -macOS开发设置和平台特定说明
docs/LINUX_DEV.md -Linux/Ubuntu环境设置指南
docs/WINDOWS_DEV.md -Windows 10/11开发环境设置

📝 配置和历史记录

docs/CHANGELOG.md -详细的版本历史和发行说明
.env.示例 -服务器环境配置模板
.env.client.example -客户端环境配置模板
ui/README.md -Web UI特定文档和设置

🧪 测试与验证

docs/TEST.md -全面的测试指南
scripts/run-tests.sh -统一的pytest+Playwright测试运行器
test_client.py -端到端客户端测试脚本
test_config.py -服务器配置验证脚本
scripts/test.sh -全面的基于外壳的测试套件

测试

该项目包括后端和前端的全面自动化测试：

运行所有测试

使用统一的测试运行器执行所有测试：

npm test
# Or: bash scripts/run-tests.sh

此脚本将：

如果需要，安装测试依赖项
对后端（服务器和客户端）运行pytest测试
运行UI的Playwright测试
显示通过/失败状态的综合摘要

后端测试（pytest）

单独运行pytest测试：

# Install test dependencies
pip install -r requirements-test.txt

# Run all tests with coverage
pytest tests/ --cov=. --cov-report=term-missing --cov-report=html -v

# Run specific test files
pytest tests/test_server.py -v
pytest tests/test_client.py -v

覆盖：后端测试包括：

健康端点和Redis连接
工具列表和模式验证
网络时间工具（NTP同步）
Ping工具（本地主机、外部主机、错误处理）
LLM生成端点
会话管理聊天功能
输入验证和错误响应

查看HTML覆盖率报告： open htmlcov/index.html

前端测试（剧作家）

单独运行Playwright UI测试：

# From project root
cd ui

# Install Playwright dependencies
npm install
npx playwright install chromium

# Run tests
npx playwright test

# Run tests with UI
npx playwright test --ui

# Run specific test file
npx playwright test tests/ui.spec.js

覆盖：UI测试包括：

聊天界面渲染和交互
消息发送和接收
工具徽章显示（get_network_time、ping_host）
加载状态和错误处理
清晰的聊天功能
自动滚动行为
响应式设计（移动/桌面）
服务器错误处理

查看剧作家报告： npx playwright show-report

测试的先决条件

后端测试需要：

MCP服务器在端口8000上运行
MCP客户端在端口8001上运行
启动服务： npm start 或 bash scripts/start.sh

前端测试要求：

所有后端服务正在运行
UI将在端口5173上自动启动（由Playwright配置管理）

测试组织

tests/                    # Backend tests (pytest)
├── conftest.py          # Shared fixtures
├── test_server.py       # MCP server tests
└── test_client.py       # MCP client tests

ui/tests/                # Frontend tests (Playwright)
└── ui.spec.js          # UI end-to-end tests

macOS开发说明

该项目是在macOS上开发和测试的。有关特定于平台的开发信息，包括macOS开发人员的设置、配置和优化提示，请参阅我们的 macOS开发指南.

🍎 macOS用户：该项目包括针对macOS开发环境的具体优化和配置，包括正确处理网络接口、NTP服务器选择和Ollama集成。

更新日志

v2.0.0-完成MCP客户端集成（2025年11月7日）

🤖 MCP客户端实现

Olama集成：与本地Ollama LLM服务器完全集成
Qwen2.5:7b-结构模型：针对可靠的工具使用模式进行了优化
智能刀具路径：自动检测时间和网络查询
直接工具测试: /test-tool 手动工具执行的端点
会话管理：上下文感知对话处理
健康监测：所有组件的完整系统状态

🧠 智能查询处理

时间查询检测：自动触发 get_network_time 工具
网络查询检测：自动触发 ping_host 工具
主机名提取：从用户查询中智能解析主机名
回退响应：优雅地处理与工具无关的查询

🔧 客户端体系结构

异步操作：无阻塞客户端-服务器通信
错误处理：对所有操作进行全面的错误管理
配置管理：单独的客户端环境配置
多模型支持：在Olama车型之间轻松切换

📊 双服务器架构

MCP服务器：端口8000-工具执行和缓存
MCP客户端：端口8001-LLM集成和聊天接口
独立经营：每台服务器都可以独立运行和测试
无缝沟通：自动工具发现和执行

🧪 增强测试

客户端测试套件: test_client.py 用于端到端验证
现场演示：所有功能的工作示例
模型验证：经过多个Olama型号的测试
性能指标：响应时间和精度测量

v1.0.0-初始MCP服务器版本（2025年11月7日）

🚀 核心功能

FastAPI服务器：带有自动OpenAPI文档的完整async/await FastAPI实现
网络工具焦点：仅用于网络实用程序的专用MCP服务器
Redis集成：具有连接池和优雅回退的异步Redis客户端
环境配置：完整的基于.env的配置系统

🔧 可用工具

get_network_time：基于NTP的网络时间同步
- 可配置的NTP服务器（主/备份）
- 毫秒精度，带偏移计算
- 优雅地回退到系统时间
- 可配置的超时设置
ping_host：网络连接和延迟测试
- 跨平台ping实现（Windows/Linux/macOS）
- 丢包检测和报告
- 延迟测量和解析
- 可配置ping计数

🏗️ 建筑

Pydantic 模式：类型安全请求/响应模型
服务层：与ToolService和LLMService的关注点完全分离
异步操作：所有网络呼叫的非阻塞操作
错误处理：全面的错误处理和详细的错误响应

📊 API终点

GET /health -服务器和Redis连接状态
GET /v1/tools/list -列出具有模式的可用工具
POST /v1/tools/call -使用参数执行工具
POST /v1/generate -LLM集成端点（带模拟实现）

⚙️ 配置系统

Redis配置：主机、端口、密码、数据库选择
NTP配置：主/备份服务器，超时设置
服务器配置：端口、日志级别
环境文件: .env 支持 .env.example 模板
Git集成：适当 .gitignore 用于敏感配置

🧪 测试与验证

健康检查：Redis连接验证
配置测试: test_config.py 端到端验证脚本
API测试：cURL示例和自动测试脚本
与跨平台支持：在macOS上测试，专为Linux/Windows兼容性而设计

📚 文档

全面自述：设置、配置和使用说明
环境模板: .env.example 附有详细评论
API示例：所有端点的完整cURL示例
配置指南：所有环境变量的详细说明

🔒 安全与最佳实践

环境变量：敏感配置排除在版本控制之外
类型安全：对所有输入/输出进行完整的Pydantic验证
错误隔离：工具故障不会导致服务器崩溃
资源管理：正确的异步资源清理

📦 依赖项

fastapi -现代web框架
uvicorn[standard] -ASGI服务器，性能优化
pydantic -数据验证和序列化
redis[asyncio] -异步Redis客户端
ntplib -网络时间协议客户端
python-dotenv -环境变量管理
requests -用于测试的HTTP客户端

🎯 未来的增强功能（标记为实施）

任务1：增强ping解析，具有强大的延迟提取功能
任务2：具有基于会话的上下文管理的高级Redis缓存
任务3：与工具使用推理循环完全集成LLM
任务4：Redis连接弹性和连接池改进

我们将构建一个MCP服务器，我们可以用LLM模型代表我们做事。

使用说明

模型上下文协议（MCP）网络工具演示

目录

特性

🖥️ MCP服务器 （端口8000）

🤖 MCP客户端 （端口8001）

🌐 Web用户界面 （端口5173）

快速开始

自动设置（推荐）

手动设置

Web用户界面

UI快速入门

UI功能

交互示例

MCP客户端设置

先决条件

客户端设置

配置

Redis配置

NTP配置

服务器配置

客户端配置（.env.Client）

API终点

MCP服务器（端口8000）

MCP客户端（端口8001）

可用工具

get_network_time

ping_host

发展

项目结构

项目结构

文档

📚 核心文件

�️ 平台特定指南

📝 配置和历史记录

🧪 测试与验证

测试

运行所有测试

后端测试（pytest）

前端测试（剧作家）

测试的先决条件

测试组织

macOS开发说明

更新日志

v2.0.0-完成MCP客户端集成（2025年11月7日）

🤖 MCP客户端实现

🧠 智能查询处理

🔧 客户端体系结构

📊 双服务器架构

🧪 增强测试

v1.0.0-初始MCP服务器版本（2025年11月7日）

🚀 核心功能

🔧 可用工具

🏗️ 建筑

📊 API终点

⚙️ 配置系统

🧪 测试与验证

📚 文档

🔒 安全与最佳实践

📦 依赖项

🎯 未来的增强功能 （标记为实施）

相关 MCP

MySQL查询服务器

Qdrant向量搜索MCP服务器

知识图谱记忆系统

Prometheus MCP 服务器

Python解释器服务

JavaFX绘图协议服务

🖥️ MCP服务器（端口8000）

🤖 MCP客户端（端口8001）

🌐 Web用户界面（端口5173）

🎯 未来的增强功能（标记为实施）