convez.ai
MCP ServerIntegração & APIsAvançado
Deepak31mu

MCP Host-Client-Server Avançado

Deepak31mu/advanced-mcp-host-client-server-app

Protocolo MCP distribuído sobre HTTP com agentes IA e integração GPT

Ver no GitHub
InicialPluginScore · de 0 a 100

Implementação production-ready do Model Context Protocol (MCP) sobre HTTP com integração LLM e modelos OpenAI GPT. Inclui servidor FastMCP, interface Gradio para exploração, agente IA autônomo e padrões enterprise de segurança e resiliência.

Instalação

$npx convez-ai Deepak31mu/advanced-mcp-host-client-server-app

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
14%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Construir aplicações de IA distribuídas com context protocol
  • Integrar modelos GPT com execução autônoma de ferramentas
  • Implementar servidores MCP com segurança e resiliência

Veredito

MCP server robusto com arquitetura enterprise, cobertura de testes 90%+ e documentação completa. Ideal para produção, mas exige familiaridade com protocolos HTTP, async Python e integração de APIs LLM.

README

A tradução para o português deste README ainda está na fila.

MCP HTTP Advanced Host-Client-Server Application

CI/CD Python 3.9+ 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

  1. Clone and setup

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

    export OPENAI_API_KEY=sk-your-key-here
    
  3. Start server

    python mcp_http_server.py
    # Server running on http://127.0.0.1:8000
    
  4. 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
    
  5. 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

DocumentPurpose
QUICKSTART.md5-minute setup and common tasks
CONFIG.mdConfiguration reference with examples
TESTING.mdTesting guide with 75+ test cases
PROJECT_REVIEW.mdComplete 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

FeaturePurposeExample
Roots ValidationPrevent directory traversalBlocks ../../etc/passwd
Path CheckingBlock absolute pathsRejects /etc/passwd
Input ValidationSanitize parametersChecks for special chars
UTF-8 EncodingPrevent encoding attacksEnforces UTF-8 on files
Error SafetyNo path disclosureReturns 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

FeatureImpactDetails
Connection RetryAutomatic recovery3 attempts, 1s delay
HeartbeatDetects dead connections2s verification timeout
History BoundedPrevents token overflowMax 20 messages
Error RecoveryGraceful degradationLogs errors, continues

📊 Performance

MetricValue
Server Throughput~100+ requests/second
Tool Call Latency<50ms (local network)
Connection Time<1 second (with retry)
Memory Baseline~100MB
Max History20 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

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit changes (git commit -m 'Add amazing feature')
  4. Push to branch (git push origin feature/amazing-feature)
  5. 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:

  1. Check Documentation

  2. Review Examples

  3. 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.

Ver o original no GitHub

Bom para

Relacionados