📖 MCP Orchestration Platform - Kompletní Manuál

Model Context Protocol (MCP) microservices orchestration platform s unified HTTP interface

Docker

Python 3.11+

Node.js 18+

PostgreSQL

Redis

📋 Obsah

1. 🎯 Úvod a přehled
2. 🏗️ Architektura systému
3. 🚀 Rychlý start
4. 🔧 Konfigurace
5. 🛠️ MCP služby
6. 📡 API dokumentace
7. 🧪 Testování
8. 🔒 Bezpečnost
9. 📊 Monitoring a diagnostika
10. 🤖 Claude AI Agent
11. 🚀 Deployment
12. 🛠️ Troubleshooting
13. 📈 Výkonnost a škálování
14. 🔧 Vývoj a přispívání

🎯 Úvod a přehled

Co je MCP Orchestration Platform?

MCP Orchestration Platform je enterprise-level microservices systém implementující Model Context Protocol (MCP) specifikaci. Poskytuje unified HTTP interface pro AI agenty a aplikace s 28+ specializovanými nástroji napříč 7 core službami.

✨ Klíčové vlastnosti

🎯 Unified HTTP Interface - Jediný endpoint pro všechny MCP služby
🏗️ Service Mesh Architecture - Containerized microservices se shared infrastructure
🔄 Automatic Health Monitoring - Built-in service discovery a health checks
🔐 Security-First Design - Environment-based secrets, žádné hardcoded credentials
📊 Vector Database Integration - Advanced AI memory s semantic search
🧪 Comprehensive Testing - Unit, performance, security, a failure recovery testy
📈 Production Monitoring - Redis caching, PostgreSQL persistence, logging

🏗️ Architektura systému

High-Level Architecture

┌─────────────────┐    ┌──────────────────────────────────────┐
│   HTTP Client   │────│           ZEN Coordinator            │
└─────────────────┘    │         (Port 7000)                 │
                       │    HTTP ↔ MCP Protocol Bridge        │
                       └──────────────────────────────────────┘
                                          │
                       ┌──────────────────┼──────────────────┐
                       │                  │                  │
            ┌──────────▼────┐  ┌─────────▼────┐  ┌─────────▼────┐
            │ Filesystem MCP │  │ Memory MCP   │  │ Terminal MCP │
            │   (7001)       │  │   (7005)     │  │   (7003)     │
            └───────────────┘  └──────────────┘  └──────────────┘
                       │                  │                  │
                       └──────────────────┼──────────────────┘
                                          │
                       ┌──────────────────▼──────────────────┐
                       │        Shared Infrastructure        │
                       │  PostgreSQL │ Redis │ Qdrant Vector │
                       │   (5432)    │ (6379)│    (6333)     │
                       └─────────────────────────────────────┘

🔒 Security Architecture

Zero Trust Network Model

Platforma implementuje Zero Trust security model:

Single Entry Point: Pouze ZEN Coordinator (port 7000) je exposed externally
Internal Isolation: MCP služby (7001-7013) nejsou přímo dostupné
Service Mesh: Všechna internal komunikace je kontrolována a monitorována
Authentication: JWT-based authentication pro API access
Authorization: Role-based access control pro MCP tools

🚀 Rychlý start

Prerequisites

Docker & Docker Compose (20.10+)
Python 3.11+
Node.js 18+
PostgreSQL 13+
Redis 6+
4GB+ RAM (doporučeno)
Linux/macOS/WSL2

1. Clone & Configure

git clone https://github.com/milhy545/orchestration.git
cd orchestration

# Copy environment template
cp .env.example .env

# Edit .env with your API keys
nano .env

2. Launch Everything

# Start all services
docker-compose up -d

# Verify health
./scripts/health-check.sh

3. Test the System

# Run comprehensive tests
./tests/unit/orchestration_workflow_test.sh

# Performance benchmarking
./tests/performance/stress_load_test.sh

4. Access the System

ZEN Coordinator: http://localhost:7000
Health Check: http://localhost:7000/health
Services List: http://localhost:7000/services
Tools List: http://localhost:7000/tools/list

🔧 Konfigurace

Environment Variables

Vytvořte .env soubor s následujícími proměnnými:

# Database Configuration
MCP_DATABASE_URL=postgresql://mcp_admin:change_me_in_production@postgresql:5432/mcp_unified
POSTGRES_DB=mcp_unified
POSTGRES_USER=mcp_admin
POSTGRES_PASSWORD=change_me_in_production

# Redis Configuration
REDIS_URL=redis://redis:6379

# Qdrant Vector Database
QDRANT_URL=http://qdrant-vector:6333

# API Keys
PERPLEXITY_API_KEY=your_perplexity_api_key_here
GEMINI_API_KEY=your_gemini_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# Security
JWT_SECRET_KEY=your_jwt_secret_key_here
ENCRYPTION_KEY=your_encryption_key_here

🛠️ MCP služby

Core Services

Filesystem MCP (Port 7001)

Účel: File operations a filesystem management

Nástroje:

file_read - Čtení souborů
file_write - Zápis souborů
file_list - Listování adresářů
file_search - Vyhledávání souborů
file_analyze - Analýza souborů

Git MCP (Port 7002)

Účel: Version control operations

Nástroje:

git_status - Git status
git_commit - Git commit
git_push - Git push
git_pull - Git pull
git_log - Git log

Terminal MCP (Port 7003)

Účel: Command execution a system operations

Nástroje:

execute_command - Spuštění příkazů
system_info - System information
process_list - Seznam procesů
disk_usage - Disk usage

Memory MCP (Port 7005)

Účel: Simple key-value storage

Nástroje:

store_memory - Uložení paměti
search_memories - Vyhledávání paměti
retrieve_memory - Načtení paměti
delete_memory - Smazání paměti

📡 API dokumentace

ZEN Coordinator API

Health Check

GET /health

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "services": {
    "postgresql": "healthy",
    "redis": "healthy",
    "qdrant": "healthy"
  }
}

Services List

GET /services

Response:

{
  "services": [
    {
      "name": "filesystem-mcp",
      "port": 7001,
      "status": "healthy",
      "tools": ["file_read", "file_write", "file_list"]
    }
  ]
}

MCP Tool Execution

POST /mcp
Content-Type: application/json

{
  "tool": "file_read",
  "arguments": {
    "path": "/path/to/file.txt"
  }
}

🧪 Testování

Test Suite Structure

tests/
├── unit/                    # Unit testy
│   ├── memory_crud_test.sh
│   └── orchestration_workflow_test.sh
├── performance/             # Performance testy
│   └── stress_load_test.sh
├── security/               # Security testy
│   └── security_assessment_test.sh
└── failure/                # Failure recovery testy
    └── failure_recovery_test.sh

Spuštění testů

# Všechny testy
./tests/run_all_tests.sh

# Unit testy
./tests/unit/orchestration_workflow_test.sh

# Performance testy
./tests/performance/stress_load_test.sh

# Security testy
./tests/security/security_assessment_test.sh

# Failure recovery testy
./tests/failure/failure_recovery_test.sh

🔒 Bezpečnost

Security Features

Environment-based Configuration - Žádné hardcoded secrets
Container Isolation - Služby běží v izolovaných kontejnerech
Network Segmentation - Internal Docker network
Credential Management - PostgreSQL authentication
API Key Protection - External service keys via environment
Data Persistence Security - Separate data volumes

📊 Monitoring a diagnostika

Health Monitoring

# System health check
./scripts/health-check.sh

# Service status monitoring
docker ps --format 'table {{.Names}}\t{{.Status}}'

# Resource monitoring
docker stats

Logging

# ZEN Coordinator logs
docker logs mega-orchestrator

# Specific service logs
docker logs mcp-filesystem

# All services logs
docker-compose logs

🤖 Claude AI Agent

Claude Agent System

Claude Agent je pokročilý AI systém pro koordinaci MCP služeb:

Komponenty

haiku_agent.py - Hlavní Claude agent
claude_session_bridge.py - Session management
anthropic_oauth_setup.py - OAuth setup
claude_agent_start.sh - Spouštěcí skript

Spuštění

# Start Claude Agent
cd claude-agent
./claude_agent_start.sh

# Test agent
python test_agent.py

🚀 Deployment

Production Deployment

1. Environment Setup

# Production environment
export NODE_ENV=production
export LOG_LEVEL=info
export ENABLE_METRICS=true

2. Database Migration

# Run migrations
./scripts/migrate-to-postgresql.py

# Backup before migration
./scripts/backup-databases.sh

🛠️ Troubleshooting

Common Issues

1. Service Not Starting

# Check logs
docker logs [service-name]

# Check health
curl http://localhost:7000/health

# Restart service
docker-compose restart [service-name]

2. Database Connection Issues

# Check PostgreSQL
docker exec -it mcp-postgresql psql -U mcp_admin -d mcp_unified

# Check Redis
docker exec -it mcp-redis redis-cli ping

📈 Výkonnost a škálování

Performance Optimization

1. Caching Strategy

# Redis caching
@cache.memoize(timeout=300)
def expensive_operation():
    # Expensive computation
    pass

2. Database Optimization

-- Index optimization
CREATE INDEX idx_memory_type ON memories(memory_type);
CREATE INDEX idx_importance ON memories(importance);

🔧 Vývoj a přispívání

Development Setup

# Development environment
git clone https://github.com/milhy545/orchestration.git
cd orchestration

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

# Start development services
docker-compose -f docker-compose.dev.yml up -d

Adding New MCP Service

Create Service Directory
Create Dockerfile
Add to docker-compose.yml
Register in ZEN Coordinator

✅ Závěr

MCP Orchestration Platform je kompletní enterprise architecture která demonstruje:

✅ Scalable Design Patterns
✅ Security Best Practices
✅ Comprehensive Testing
✅ Production Monitoring
✅ Service Mesh Architecture
✅ AI Integration Patterns

Perfektní pro learning, extending, nebo použití jako foundation pro production systems.