MCP HTTP Advanced Host-Client-Server Application

License: MIT Coverage: 90%+

A production-ready implementation of the Model Context Protocol (MCP) over HTTP with LLM tool integration, featuring OpenAI GPT models, comprehensive security, resilience patterns, and enterprise testing.

🎯 Key Features

Core Capabilities

✅ HTTP-based MCP - Distributed tool protocol over HTTP
✅ LLM Integration - OpenAI GPT model with function calling
✅ Filesystem Tools - Read/write files with security
✅ Web UI - Gradio interface for exploration and testing
✅ AI Agent - Autonomous tool execution based on user intent

Production Ready

✅ Configuration Management - JSON config with env var substitution
✅ Security - Path traversal prevention, input validation, UTF-8 enforcement
✅ Resilience - Connection retry, heartbeat verification, error recovery
✅ Logging - Structured logging with configurable levels
✅ Testing - 75+ tests with 90%+ coverage, CI/CD pipeline
✅ Documentation - Comprehensive guides for configuration and testing

📦 What's Included

🎯 mcp_http_server.py          HTTP MCP Server (FastMCP)
🎨 mcp_http_client_app.py      Web UI (Gradio) for exploration
🤖 mcp_http_host_app.py        AI Agent with OpenAI integration
📋 mcp_config.py               Configuration management with priority resolution
⚙️  mcp_config.json            Production configuration
🧪 tests/                      75+ test cases with pytest
🔄 .github/workflows/ci_cd.yml  GitHub Actions CI/CD pipeline
📚 Documentation               Guides for quick start, config, testing, and review

🚀 Quick Start (5 minutes)

Prerequisites

python 3.9+          # For async/await and type hints
pip package manager  # For dependency installation
OpenAI API key       # For GPT model access

Installation

Clone and setup

git clone <repo>
cd advanced-mcp-host-client-server-app
pip install -r requirements.txt

Set API key
```
export OPENAI_API_KEY=sk-your-key-here
```

Start server

python mcp_http_server.py
# Server running on http://127.0.0.1:8000

Start AI Host (new terminal)

python mcp_http_host_app.py http://127.0.0.1:8000 ./workspace
# Access at http://127.0.0.1:7862

Chat with AI
- Go to http://127.0.0.1:7862
- Type: "List the files in workspace"
- AI calls list_files tool automatically!

See QUICKSTART.md for detailed setup instructions.

📖 Documentation

Document	Purpose
QUICKSTART.md	5-minute setup and common tasks
CONFIG.md	Configuration reference with examples
TESTING.md	Testing guide with 75+ test cases
PROJECT_REVIEW.md	Complete technical review and architecture

🏗️ Architecture

Component Diagram

┌──────────────────────────────────────────────────────┐
│              MCP Application Suite                    │
└──────────────────────────────────────────────────────┘

    GUI Client                AI Host App            API Clients
   (Gradio UI)         (GPT + Tool Calling)       (Custom clients)
        │                     │                        │
        └─────────────────────┼────────────────────────┘
                              │
                         HTTP/Streamable
                              │
                    ┌─────────▼──────────┐
                    │  HTTP MCP Server   │
                    │   (FastMCP)        │
                    │                    │
                    │ • File Tools       │
                    │ • Resources        │
                    │ • Prompts          │
                    │ • Analysis         │
                    └────────────────────┘
                              │
                         Workspace
                    (./workspace files)

Component Responsibilities

mcp_http_server.py: Exposes filesystem and analysis tools via HTTP MCP
mcp_http_client_app.py: Web UI for exploring tools, resources, and prompts
mcp_http_host_app.py: LLM agent that calls tools autonomously
mcp_config.py: Centralized configuration with priority resolution
tests/: Comprehensive test suite for reliability

🔒 Security Features

Feature	Purpose	Example
Roots Validation	Prevent directory traversal	Blocks `../../etc/passwd`
Path Checking	Block absolute paths	Rejects `/etc/passwd`
Input Validation	Sanitize parameters	Checks for special chars
UTF-8 Encoding	Prevent encoding attacks	Enforces UTF-8 on files
Error Safety	No path disclosure	Returns safe error messages

⚙️ Configuration

Three Tiers (Priority)

1. Command-line arguments  (Highest priority)
   └─ python app.py --model gpt-4o

2. Configuration file
   └─ mcp_config.json with "model": "gpt-4o-mini"

3. Environment variables
   └─ export OPENAI_MODEL=gpt-4o-mini

4. Hardcoded defaults      (Lowest priority)
   └─ DEFAULT_MODEL = "gpt-4o-mini"

Example mcp_config.json

{
  "openai": {
    "api_key": "${OPENAI_API_KEY}",
    "model": "gpt-4o-mini"
  },
  "server": {
    "host": "127.0.0.1",
    "port": 8000
  },
  "gui": {
    "host": "127.0.0.1",
    "port": 7862
  },
  "logging": {
    "level": "INFO"
  }
}

See CONFIG.md for complete configuration guide.

🧪 Testing

Run All Tests

pip install -r requirements-test.txt
pytest tests/ -v

Test Coverage

Overall: 90%+
Config module: 95%+
Server module: 90%+
Client module: 85%+

Test Types

Unit Tests (60%): Fast, isolated component tests
Security Tests (20%): Vulnerability and attack prevention
Integration Tests (20%): Real-world scenarios

See TESTING.md for comprehensive testing guide.

🔄 Resilience Features

Feature	Impact	Details
Connection Retry	Automatic recovery	3 attempts, 1s delay
Heartbeat	Detects dead connections	2s verification timeout
History Bounded	Prevents token overflow	Max 20 messages
Error Recovery	Graceful degradation	Logs errors, continues

📊 Performance

Metric	Value
Server Throughput	~100+ requests/second
Tool Call Latency	<50ms (local network)
Connection Time	<1 second (with retry)
Memory Baseline	~100MB
Max History	20 messages (bounded)

🚀 Deployment

Local Development

# Terminal 1: Server
python mcp_http_server.py

# Terminal 2: GUI Client
python mcp_http_client_app.py http://localhost:8000 ./workspace

# Terminal 3: AI Host
python mcp_http_host_app.py http://localhost:8000 ./workspace

Docker

docker build -t mcp-app .
docker run -e OPENAI_API_KEY=$OPENAI_API_KEY -p 8000:8000 -p 7862:7862 mcp-app

GitHub Actions CI/CD

✅ Automated testing on Python 3.9-3.11
✅ Runs on Linux, macOS, Windows
✅ Code quality checks (pylint, black, flake8, mypy)
✅ Security checks (bandit, safety)
✅ Coverage reporting

See PROJECT_REVIEW.md for deployment details.

🛠️ Tools & Technologies

Core

FastMCP 2.12.5: MCP server framework
OpenAI SDK 2.6.1: GPT model integration
Gradio 5.49.1: Web UI framework
Uvicorn 0.38.0: ASGI server
HTTPx: HTTP client

Testing

Pytest 7.4.3: Test framework
Pytest-asyncio: Async test support
Pytest-cov: Coverage reporting
Black, Pylint, Flake8, MyPy: Code quality

📝 API Reference

Server Tools

read_file(filepath: str) -> str
  # Read file from workspace

write_file(filepath: str, content: str) -> str
  # Write file to workspace

list_files(directory: str) -> List[str]
  # List directory contents

analyze_code(code: str, focus: str = "") -> str
  # Analyze code with LLM

Client Methods

await client.connect()
await client.list_tools()
await client.call_tool(name, arguments)
await client.list_resources()
await client.read_resource(uri)
await client.list_prompts()
await client.get_prompt(name, arguments)

🔐 Security Considerations

✅ Implemented

Path traversal prevention
Input validation on all parameters
UTF-8 encoding enforcement
Error message safety
Dependency security checks (CI/CD)

⚠️ To Implement

API authentication
Authorization/RBAC
Rate limiting
Request signing
Data encryption at rest

See PROJECT_REVIEW.md for security details.

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

All PRs must:

✅ Pass all tests
✅ Maintain 90%+ coverage
✅ Pass code quality checks
✅ Include documentation

📋 Project Status

✅ Completed

HTTP MCP server with filesystem tools
Gradio web UI for tool exploration
OpenAI integration with function calling
Configuration management system
75+ test cases with CI/CD pipeline
Comprehensive documentation
Security hardening
Resilience patterns

🚧 In Progress

Enhanced monitoring and metrics
Performance optimization
Extended logging

📋 Planned

Multi-instance load balancing
Persistent conversation storage
Database-backed file storage
Authentication/authorization
WebSocket support
Batch operations
Custom tool templates

📄 License

This project is licensed under the MIT License - see LICENSE file for details.

👥 Author

Deepak Upadhyay - Engineering

🙏 Acknowledgments

FastMCP team for MCP server framework
OpenAI for GPT model APIs
Gradio for web UI components
Python async/await ecosystem

📞 Support

For issues, questions, or feature requests:

Check Documentation
- QUICKSTART.md - Common tasks
- CONFIG.md - Configuration help
- TESTING.md - Test documentation
Review Examples
- Check tests/ for usage examples
- Review mcp_config.json for setup
Debug Issues
- Enable debug logging: LOG_LEVEL=DEBUG
- Check PROJECT_REVIEW.md for architecture
- Run tests: pytest -v to verify setup

🎓 Learning Resources

Version: 1.0.0 Last Updated: 2024 Status: Production Ready ✅

Made with ❤️ for the agentic engineering community.