Model Context Protocol (MCP) Network Tools Demo
A comprehensive demonstration of the Model Context Protocol featuring proper LLM-driven tool selection, network utilities, and real-time workflow visualization. This project showcases how MCP enables intelligent AI agents to reason about and execute tools through structured protocols.
Table of Contents
- Features
- Quick Start
- Web UI
- MCP Client Setup
- Configuration
- API Endpoints
- Available Tools
- Development
- Project Structure
- Documentation
- macOS Development Notes
- Changelog
Features
🖥️ MCP Server (Port 8000)
- Network Time Tool: Retrieves accurate time from configurable NTP servers
- Ping Tool: Tests network connectivity and latency to specified hosts
- Redis Caching: Optional Redis integration for response caching
- Environment Configuration: Fully configurable via environment variables
🤖 MCP Client (Port 8001)
- Proper MCP Protocol: LLM receives tool schemas and makes structured tool selection decisions
- Ollama Integration: Local LLM integration with Qwen2.5:7b-instruct model
- Two-Phase Processing: Initial tool selection, then response integration with tool results
- Structured Tool Requests: LLM responds with JSON specifying exact tools and parameters
- Session Management: Context-aware conversations with debug endpoints
🌐 Web UI (Port 5173)
- Modern Chat Interface: Sleek, responsive chat UI built with React + Vite
- MCP Workflow Visualization: Real-time display of complete MCP protocol flow
- Chronological Component Tracking: Shows UI → Client → Ollama → Server interactions
- Detailed Data Exchange: Full request/response payloads and timing information
- Educational Demo Mode: Perfect for understanding how MCP protocol works
- Tool Visibility: Visual badges showing which MCP tools were used in each response
- Mobile Responsive: Works beautifully on desktop, tablet, and mobile devices
> 📖 New to Model Context Protocol? See docs/MCP_EXPLAINED.md for a comprehensive guide to understanding MCP concepts and how they apply to this project.
>
> 🔧 Want to understand the Client Architecture? See docs/CLIENT_ARCHITECTURE.md for details on how the MCP client integrates with local LLMs.
>
> 🤖 Building AI agents for this project? See .github/copilot-instructions.md for AI coding agent guidance.
>
> 🍎 macOS Developer? See docs/MACOS_DEV.md for platform-specific setup and optimizations.
>
> 🐧 Linux Developer? See docs/LINUX_DEV.md for Linux/Ubuntu environment setup.
>
Quick Start
Automated Setup (Recommended)
Use the automated setup script to configure everything:```bash
git clone <repository-url>
cd model-context-protocol
bash scripts/setup.sh
The setup script will:
- ✅ Check Python 3.10+ and Node.js installation
- ✅ Create and activate Python virtual environment
- ✅ Install all Python dependencies (production + testing)
- ✅ Install Node.js dependencies for UI
- ✅ Configure Playwright with Chromium browser
- ✅ Create `.env` and `.env.client` from templates
After setup completes, activate the virtual environment and start services:```bash
source .venv/bin/activate # On Windows: .venv\Scripts\activate
npm start
Manual Setup
-
Clone and Setup:
bash git clone <repository-url> cd model-context-protocol python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate -
Install Dependencies:```bash
# 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
```
-
Configure Environment:
bash cp .env.example .env cp .env.client.example .env.client # Edit .env and .env.client with your settings -
Start All Services:
bash npm start # Or: bash scripts/start.sh -
Test the MCP Server:```bash
# 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 UI
A modern, responsive chat interface is available for easy interaction with the MCP system.
Quick Start with UI
-
Start all services (from project root):
bash npm start # Or: bash scripts/start.sh
This single command starts:
- MCP Server (port 8000)
- MCP Client (port 8001)
- Web UI (port 5173) -
Open in browser: Navigate to
http://localhost:5173
UI Features
The Web UI provides an intuitive chat interface with:
- 🎨 Modern dark theme - Easy on the eyes for extended use
- 💬 Real-time chat - Instant responses from the MCP client
- 🔧 Tool badges - Visual indicators showing which tools (NTP time, ping) were used
- 📱 Fully responsive - Adapts to any screen size
- ⚡ Fast & lightweight - Built with Vite for instant hot-reload during development
- 🗨️ Clear chat - Button to clear conversation history
- 🎯 Auto-scroll - Always shows the latest messages
Example Interactions
Try these queries in the UI:
- "What time is it?" → Uses get_network_time tool
- "Can you ping google.com?" → Uses ping_host tool
- "Hello, what can you help me with?" → General conversation
See ui/README.md for more UI-specific details.
MCP Client Setup
The project includes a complete MCP client that integrates with local Ollama models for intelligent tool usage. For detailed architecture information, see docs/CLIENT_ARCHITECTURE.md and docs/CLIENT_README.md.
Prerequisites
- Install Ollama: Visit ollama.ai and install Ollama
- Pull Qwen2.5 Model:
ollama pull qwen2.5:7b-instruct
Client Setup
-
Configure Client Environment:
bash cp .env.client.example .env.client # Edit .env.client with your preferred settings -
Start the Client (in a new terminal):
bash uvicorn client:app --port 8001 -
Test the Client:```bash
# 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"}'
```
Configuration
The server is configured via environment variables. Copy .env.example to .env and modify as needed:
Redis Configuration
REDIS_HOST: Redis server hostname (default: localhost)REDIS_PORT: Redis server port (default: 6379)REDIS_PASSWORD: Redis password (optional)REDIS_DB: Redis database number (default: 0)
NTP Configuration
NTP_SERVER: Primary NTP server (default: pool.ntp.org)NTP_BACKUP_SERVER: Backup NTP server (default: time.google.com)NTP_TIMEOUT: NTP request timeout in seconds (default: 5)
Server Configuration
SERVER_PORT: FastAPI server port (default: 8000)LOG_LEVEL: Logging level (default: INFO)
Client Configuration (.env.client)
OLLAMA_URL: Ollama server URL (default: http://localhost:11434)OLLAMA_MODEL: Model to use (default: qwen2.5:7b-instruct)MCP_SERVER_URL: MCP server URL (default: http://localhost:8000)CLIENT_PORT: Client server port (default: 8001)
See .env.example and .env.client.example for complete configuration templates.
API Endpoints
MCP Server (Port 8000)
GET /health- Returns server status and Redis connection statusGET /v1/tools/list- List all available toolsPOST /v1/tools/call- Execute a specific toolPOST /v1/generate- LLM generation endpoint with tool reasoning loop
MCP Client (Port 8001)
GET /health- Returns client, Ollama, and MCP server statusGET /tools- List available tools from MCP serverPOST /chat- Chat interface with intelligent tool usagePOST /test-tool- Direct tool testing endpoint
Available Tools
get_network_time
Retrieves accurate time from NTP servers.
- Parameters: None
- Returns: UTC timestamp, readable time, offset, and source server
ping_host
Tests network connectivity and latency.
- Parameters:
- hostname (required): Hostname or IP address to ping
- Returns: Host status, latency, packet loss, and output snippet
Development
The server includes several areas marked for enhancement:
1. Enhanced ping parsing for better latency extraction (see server.py._execute_ping)
2. Robust Redis caching with session management (see server.py.LLMService.generate)
3. Full LLM integration with tool-use reasoning loop (see server.py.LLMService.generate)
4. Redis connection resilience improvements (see server.py startup event)
For detailed development workflows and testing, see:
- test_client.py - End-to-end client testing
- test_config.py - Server configuration validation
- CLIENT_ARCHITECTURE.md - Client implementation details
- .github/copilot-instructions.md - AI agent guidance
Project Structure
Project Structure```
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
## Documentation
This project includes comprehensive documentation for different audiences and purposes:
### 📚 **Core Documentation**
- **docs/MCP_EXPLAINED.md** - Comprehensive introduction to Model Context Protocol concepts
- **docs/CLIENT_ARCHITECTURE.md** - Client architecture and LLM integration details
- **docs/CLIENT_README.md** - Client-specific documentation and usage
- **docs/PROJECT_SUMMARY.md** - High-level project overview and goals
### ️ **Platform-Specific Guides**
- **docs/MACOS_DEV.md** - macOS development setup and platform-specific notes
- **docs/LINUX_DEV.md** - Linux/Ubuntu environment setup guide
- **docs/WINDOWS_DEV.md** - Windows 10/11 development environment setup
### 📝 **Configuration & History**
- **docs/CHANGELOG.md** - Detailed version history and release notes
- **.env.example** - Server environment configuration template
- **.env.client.example** - Client environment configuration template
- **ui/README.md** - Web UI specific documentation and setup
### 🧪 **Testing & Validation**
- **docs/TESTING.md** - Comprehensive testing guide
- **scripts/run-tests.sh** - Unified pytest + Playwright test runner
- **test_client.py** - End-to-end client testing script
- **test_config.py** - Server configuration validation script
- **scripts/test.sh** - Comprehensive shell-based test suite
## Testing
The project includes comprehensive automated testing for both backend and frontend:
### Running All Tests
Use the unified test runner to execute all tests:```bash
npm test
# Or: bash scripts/run-tests.sh
This script will:
1. Install test dependencies if needed
2. Run pytest tests for backend (server and client)
3. Run Playwright tests for UI
4. Display a comprehensive summary with pass/fail status
Backend Testing (pytest)
Run pytest tests separately:```bash
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
**Coverage**: Backend tests cover:
- Health endpoints and Redis connectivity
- Tool listing and schema validation
- Network time tool (NTP synchronization)
- Ping tool (localhost, external hosts, error handling)
- LLM generation endpoints
- Chat functionality with session management
- Input validation and error responses
View HTML coverage report: `open htmlcov/index.html`
### Frontend Testing (Playwright)
Run Playwright UI tests separately:```bash
# 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
Coverage: UI tests cover:
- Chat interface rendering and interactions
- Message sending and receiving
- Tool badge display (get_network_time, ping_host)
- Loading states and error handling
- Clear chat functionality
- Auto-scroll behavior
- Responsive design (mobile/desktop)
- Server error handling
View Playwright report: npx playwright show-report
Prerequisites for Testing
Backend tests require:
- MCP Server running on port 8000
- MCP Client running on port 8001
- Start services: npm start or bash scripts/start.sh
Frontend tests require:
- All backend services running
- UI will auto-start on port 5173 (managed by Playwright config)
Test Organization```
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 Development Notes
This project was developed and tested on macOS. For platform-specific development information, including setup, configuration, and optimization tips for macOS developers, please see our macOS Development Guide.
> 🍎 macOS Users: The project includes specific optimizations and configurations for macOS development environments, including proper handling of network interfaces, NTP server selection, and Ollama integration.
Changelog
v2.0.0 - Complete MCP Client Integration (November 7, 2025)
🤖 MCP Client Implementation
- Ollama Integration: Full integration with local Ollama LLM server
- Qwen2.5:7b-instruct Model: Optimized for reliable tool usage patterns
- Intelligent Tool Routing: Automatic detection of time and network queries
- Direct Tool Testing:
/test-toolendpoint for manual tool execution - Session Management: Context-aware conversation handling
- Health Monitoring: Complete system status across all components
🧠 Smart Query Processing
- Time Query Detection: Automatic triggering of
get_network_timetool - Network Query Detection: Automatic triggering of
ping_hosttool - Hostname Extraction: Intelligent parsing of hostnames from user queries
- Fallback Responses: Graceful handling of non-tool-related queries
🔧 Client Architecture
- Async Operations: Non-blocking client-server communication
- Error Handling: Comprehensive error management across all operations
- Configuration Management: Separate client environment configuration
- Multi-Model Support: Easy switching between Ollama models
📊 Dual-Server Architecture
- MCP Server: Port 8000 - Tool execution and caching
- MCP Client: Port 8001 - LLM integration and chat interface
- Independent Operation: Each server can run and be tested independently
- Seamless Communication: Automatic tool discovery and execution
🧪 Enhanced Testing
- Client Test Suite:
test_client.pyfor end-to-end validation - Live Demonstrations: Working examples of all functionality
- Model Validation: Tested with multiple Ollama models
- Performance Metrics: Response time and accuracy measurements
v1.0.0 - Initial MCP Server Release (November 7, 2025)
🚀 Core Features
- FastAPI Server: Full async/await FastAPI implementation with automatic OpenAPI documentation
- Network Tools Focus: Specialized MCP server for network utilities only
- Redis Integration: Async Redis client with connection pooling and graceful fallback
- Environment Configuration: Complete .env-based configuration system
🔧 Available Tools
get_network_time: NTP-based network time synchronization- Configurable NTP servers (primary/backup)
- Millisecond precision with offset calculation
- Graceful fallback to system time
- Configurable timeout settings
ping_host: Network connectivity and latency testing- Cross-platform ping implementation (Windows/Linux/macOS)
- Packet loss detection and reporting
- Latency measurement and parsing
- Configurable ping count
🏗️ Architecture
- Pydantic Schemas: Type-safe request/response models
- Service Layer: Clean separation of concerns with ToolService and LLMService
- Async Operations: Non-blocking operations for all network calls
- Error Handling: Comprehensive error handling with detailed error responses
📊 API Endpoints
GET /health- Server and Redis connection statusGET /v1/tools/list- List available tools with schemaPOST /v1/tools/call- Execute tools with argumentsPOST /v1/generate- LLM integration endpoint (with mock implementation)
⚙️ Configuration System
- Redis Configuration: Host, port, password, database selection
- NTP Configuration: Primary/backup servers, timeout settings
- Server Configuration: Port, logging level
- Environment Files:
.envsupport with.env.exampletemplate - Git Integration: Proper
.gitignorefor sensitive configuration
🧪 Testing & Validation
- Health Checks: Redis connectivity validation
- Configuration Testing:
test_config.pyscript for end-to-end validation - API Testing: cURL examples and automated test script
- Cross-platform Support: Tested on macOS, designed for Linux/Windows compatibility
📚 Documentation
- Comprehensive README: Setup, configuration, and usage instructions
- Environment Templates:
.env.examplewith detailed comments - API Examples: Complete cURL examples for all endpoints
- Configuration Guide: Detailed explanation of all environment variables
🔒 Security & Best Practices
- Environment Variables: Sensitive configuration excluded from version control
- Type Safety: Full Pydantic validation for all inputs/outputs
- Error Isolation: Tools failures don't crash the server
- Resource Management: Proper async resource cleanup
📦 Dependencies
fastapi- Modern web frameworkuvicorn[standard]- ASGI server with performance optimizationspydantic- Data validation and serializationredis[asyncio]- Async Redis clientntplib- Network Time Protocol clientpython-dotenv- Environment variable managementrequests- HTTP client for testing
🎯 Future Enhancements (Marked for Implementation)
- Task 1: Enhanced ping parsing with robust latency extraction
- Task 2: Advanced Redis caching with session-based context management
- Task 3: Full LLM integration with tool-use reasoning loop
- Task 4: Redis connection resilience and connection pooling improvements
We are going to build an MCP server we can got to do things on our behalf with an LLM model.