MCP Business AI Transformation
Enterprise-grade MCP (Model Context Protocol) server with multi-agent system for business AI transformation.
🏗️ Architecture Overview
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Agent Layer │◄──►│ MCP Gateway │◄──►│ Business APIs │
│ (Orchestrator) │ │ (Protocol Hub) │ │ (External) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ LLM Fabric │ │ State Manager │ │ Monitoring Hub │
│ (Multi-Model) │ │ (Redis+Postgres) │ │ (Observability) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
🚀 Features
Core MCP Server
- FastAPI-based high-performance server
- MCP Protocol compliant (2024-11-05 spec)
- Multi-provider LLM support (Evolution Foundation Models, OpenAI, HuggingFace)
- Circuit breaker pattern for external API resilience
- Rate limiting with Redis-based sliding window
- JWT & API Key authentication
- Prometheus metrics and OpenTelemetry tracing
Multi-Agent System
- Specialized Agents: Data Analyst, API Executor, Business Validator, Report Generator
- Agent Registry for dynamic agent management
- Message Bus for inter-agent communication
- Task Orchestration with intelligent agent selection
- LangChain/LlamaIndex integration for advanced AI capabilities
Enterprise Features
- Real-time Dashboard with React + TypeScript
- Business Domain Support: Finance, Healthcare, Retail, Manufacturing, Technology
- Observability Stack: Prometheus, Grafana, Jaeger
- Docker Compose for easy deployment
- Production-ready with security best practices
🛠️ Technology Stack
Frontend
- Next.js 15 with App Router
- TypeScript 5 for type safety
- Tailwind CSS 4 with shadcn/ui components
- Real-time updates with WebSocket support
Backend
- Python 3.11 with FastAPI
- PostgreSQL for persistent storage
- Redis for caching and rate limiting
- AsyncIO for high concurrency
AI/ML
- Evolution Foundation Models (Cloud.ru)
- OpenAI API compatibility
- LangChain for agent orchestration
- LlamaIndex for data indexing
DevOps
- Docker containerization
- Prometheus monitoring
- Grafana dashboards
- Jaeger distributed tracing
📦 Quick Start
Prerequisites
- Docker & Docker Compose
- Node.js 18+ (for local development)
- Python 3.11+ (for local development)
Environment Configuration
Create a .env file:
# API Keys
EVOLUTION_API_KEY=your_evolution_api_key
OPENAI_API_KEY=your_openai_api_key
HUGGINGFACE_API_KEY=your_huggingface_api_key
# Security
SECRET_KEY=your-super-secret-key-change-in-production
# Database (optional, defaults work with Docker)
DATABASE_URL=postgresql+asyncpg://postgres:password@localhost:5432/mcp_db
REDIS_URL=redis://localhost:6379
Start the System
# Start all services
docker-compose up -d
# View logs
docker-compose logs -f
# Stop services
docker-compose down
Access Points
- Frontend Dashboard: http://localhost:3000
- MCP Server API: http://localhost:8000
- API Documentation: http://localhost:8000/docs
- Grafana Dashboard: http://localhost:3001 (admin/admin)
- Prometheus: http://localhost:9091
- Jaeger Tracing: http://localhost:16686
🔧 Development
Local Development Setup
Backend (MCP Server)
cd mcp_server
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
Agent System
cd agent_system
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python main.py
Frontend
npm install
npm run dev
Project Structure
├── src/ # Next.js frontend
│ ├── app/ # App Router pages
│ ├── components/ # React components
│ └── lib/ # Utility functions
├── mcp_server/ # FastAPI MCP server
│ ├── app/ # Application code
│ │ ├── api/v1/ # API endpoints
│ │ ├── core/ # Core services
│ │ └── middleware/ # Custom middleware
│ └── tests/ # Test suite
├── agent_system/ # Multi-agent system
│ ├── core/ # Agent framework
│ ├── agents/ # Specialized agents
│ └── llm/ # LLM providers
├── docker-compose.yml # Multi-service deployment
└── docs/ # Documentation
📊 API Usage
MCP Protocol
The server implements the MCP protocol for tool and resource management:
# Initialize connection
curl -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {}
}
}'
# List available tools
curl -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list"
}'
# Execute a tool
curl -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "financial_analyzer",
"arguments": {
"data": {...}
}
}
}'
REST API
# Create a business task
curl -X POST http://localhost:8000/api/v1/resources/tasks \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-d '{
"title": "Financial Analysis Q4",
"description": "Analyze quarterly financial data",
"domain": "finance",
"priority": "high"
}'
# Get system status
curl -X GET http://localhost:8000/api/v1/admin/system/status
# Health check
curl -X GET http://localhost:8000/api/v1/health
🔍 Monitoring & Observability
Metrics
- Request latency and throughput
- Agent performance and task completion rates
- LLM token usage and costs
- External API success rates and circuit breaker status
Tracing
- Distributed tracing with Jaeger
- Request correlation IDs
- Agent communication tracing
Logging
- Structured logging with correlation IDs
- Log levels: DEBUG, INFO, WARNING, ERROR
- JSON format for easy parsing
🔒 Security
Authentication
- JWT tokens for user authentication
- API keys for service-to-service communication
- Rate limiting per user/API key
Authorization
- Role-based access control (RBAC)
- Resource-level permissions
- CORS configuration
Data Protection
- Input validation and sanitization
- SQL injection prevention
- XSS protection headers
🚀 Deployment
Production Deployment
# Set production environment variables
export NODE_ENV=production
export DEBUG=false
# Deploy with production configurations
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
Cloud.ru Evolution AI Agents
The system is designed to deploy on Cloud.ru Evolution AI Agents platform:
- Container Registry: Push Docker images to Cloud.ru registry
- AI Agent Configuration: Configure agent endpoints and API keys
- Load Balancing: Set up load balancer for high availability
- Monitoring: Configure Cloud.ru monitoring integration
🤝 Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🆘 Support
- Documentation: Check the
/docsdirectory - API Docs: Visit http://localhost:8000/docs
- Issues: Create an issue on GitHub
- Discussions: Join our GitHub Discussions
🗺️ Roadmap
Phase 1: Core Infrastructure ✅
- MCP Server implementation
- Multi-agent system
- LLM provider integration
- Basic monitoring
Phase 2: Advanced Features (In Progress)
- Advanced agent orchestration
- Custom tool development framework
- Advanced analytics and reporting
- Multi-tenancy support
Phase 3: Enterprise Features (Planned)
- Advanced security features
- Compliance certifications
- Advanced monitoring and alerting
- Performance optimization
Phase 4: AI/ML Enhancements (Future)
- Custom model training
- Advanced prompt engineering
- Multi-modal AI capabilities
- AutoML integration
Built with ❤️ for enterprise AI transformation
