universe-ai-mcp

miltonvve/universe-ai-mcp

3.2

If you are the rightful owner of universe-ai-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

Universe AI is a robust MCP server designed to coordinate multiple AI agents for complex business tasks.

Tools
1
Resources
0
Prompts
0

Universe AI - MCP Orchestration Server

Overview

Universe AI is a production-ready Model Context Protocol (MCP) server that orchestrates multiple AI agents to solve complex business tasks. Built with Test-Driven Development (TDD) methodology and a modular monolith architecture, it provides enterprise-grade orchestration, context management, and self-healing capabilities.

Key Features

  • MCP Protocol Implementation: Full JSON-RPC 2.0 protocol with HTTP SSE transport
  • Multi-Agent Orchestration: Coordinate multiple AI agents with parallel execution
  • Visual Output Engine: Intent detection and dynamic task planning
  • Context Assembly Engine: Intelligent context management with token optimization
  • Self-Healing Architecture: Circuit breakers, retry policies, and error recovery
  • Blackboard Pattern: Azure-backed shared state for agent collaboration
  • 5.5 Layer Test Gauntlet: Comprehensive testing framework with 80%+ coverage
  • Module Boundary Enforcement: Prevent distributed monolith anti-patterns

Quick Start

Prerequisites

  • Node.js 18+
  • PostgreSQL 14+
  • Redis 6+
  • Docker & Docker Compose
  • Azure account (for production)

Installation

# Clone repository
git clone https://github.com/yourusername/universe-ai.git
cd universe-ai

# Install dependencies
npm install

# Setup environment
cp .env.example .env
# Edit .env with your configuration

# Setup database
npm run db:migrate
npm run db:seed

# Run tests to verify setup
npm test

Development

# Start development server with hot reload
npm run dev

# Run specific test layers
npm run test:unit        # Layer 1: Unit tests
npm run test:integration # Layer 2: Integration tests
npm run test:e2e         # Layer 3: End-to-end tests
npm run test:load        # Layer 4: Load tests
npm run test:gauntlet    # Run full test suite

# Validate module boundaries
npm run validate:all

# Format and lint
npm run format
npm run lint:fix

Docker Deployment

# Build and start all services
npm run docker:build
npm run docker:up

# Access services
# MCP Server: http://localhost:8200
# Admin UI: http://localhost:8201
# Metrics: http://localhost:8202

Project Structure

universe-ai/
ā”œā”€ā”€ src/
ā”‚   ā”œā”€ā”€ mcp/                 # MCP Server implementation
ā”‚   ā”‚   ā”œā”€ā”€ server.ts         # JSON-RPC 2.0 server
ā”‚   ā”‚   ā”œā”€ā”€ transport/        # HTTP SSE transport layer
ā”‚   ā”‚   ā””ā”€ā”€ handlers/         # Request handlers
ā”‚   ā”œā”€ā”€ modules/
ā”‚   ā”‚   ā”œā”€ā”€ voe/             # Visual Output Engine
ā”‚   ā”‚   ā”œā”€ā”€ moa/             # Multi-Agent Orchestrator
ā”‚   ā”‚   ā”œā”€ā”€ cae/             # Context Assembly Engine
ā”‚   ā”‚   ā”œā”€ā”€ blackboard/      # Blackboard pattern
ā”‚   ā”‚   ā””ā”€ā”€ error-recovery/  # Self-healing mechanisms
ā”‚   ā”œā”€ā”€ shared/              # Shared interfaces and types
ā”‚   ā”‚   ā”œā”€ā”€ interfaces/      # Service contracts
ā”‚   ā”‚   ā”œā”€ā”€ types/           # Common types
ā”‚   ā”‚   ā””ā”€ā”€ contracts/       # Communication rules
ā”‚   ā””ā”€ā”€ database/            # Database layer
ā”‚       ā”œā”€ā”€ migrations/      # Schema migrations
ā”‚       ā””ā”€ā”€ repositories/    # Data access layer
ā”œā”€ā”€ tests/
ā”‚   ā”œā”€ā”€ unit/               # Layer 1: Unit tests
ā”‚   ā”œā”€ā”€ integration/        # Layer 2: Integration tests
ā”‚   ā”œā”€ā”€ e2e/                # Layer 3: End-to-end tests
ā”‚   ā”œā”€ā”€ load/               # Layer 4: Performance tests
ā”‚   ā””ā”€ā”€ protocol/           # Layer 5: Protocol compliance
ā”œā”€ā”€ scripts/                # Build and validation scripts
ā”œā”€ā”€ docker/                 # Docker configurations
ā””ā”€ā”€ docs/                   # Documentation

Core Modules

MCP Server

Implements the Model Context Protocol with:

  • JSON-RPC 2.0 message handling
  • HTTP Server-Sent Events transport
  • Tool registration and invocation
  • Session management
  • Resource lifecycle management

VOE (Visual Output Engine)

Intent detection and task planning:

  • Natural language understanding
  • Task decomposition
  • Execution plan generation
  • Output formatting
  • User interface generation

MOA (Multi-Agent Orchestrator)

Agent execution and coordination:

  • Agent registry and discovery
  • Parallel execution management
  • Task routing and scheduling
  • Result aggregation
  • Performance monitoring

CAE (Context Assembly Engine)

Dynamic context management:

  • Context collection from multiple sources
  • Token optimization and truncation
  • Relevance scoring
  • Context caching
  • Incremental updates

Configuration

Environment Variables

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/universe_ai
REDIS_URL=redis://localhost:6379

# Authentication
JWT_SECRET=your-secret-key
API_KEY=your-api-key

# Azure Services
AZURE_STORAGE_CONNECTION_STRING=your-connection-string
AZURE_SERVICE_BUS_CONNECTION_STRING=your-connection-string
AZURE_COSMOS_DB_CONNECTION_STRING=your-connection-string

# Service Configuration
MCP_PORT=8200
ADMIN_PORT=8201
METRICS_PORT=8202
NODE_ENV=production
LOG_LEVEL=info

Database Setup

-- Create database
CREATE DATABASE universe_ai;

-- Run migrations
npm run db:migrate

-- Seed test data (development only)
npm run db:seed

Testing

The project uses a 5.5 Layer Gauntlet testing framework:

  1. Unit Tests (80% coverage required)
  2. Integration Tests (Service interactions)
  3. E2E Tests (Complete user journeys)
  4. Load Tests (Performance validation)
  5. Protocol Tests (MCP compliance) 5.5. Chaos Tests (Failure recovery)

Run tests:

npm test                 # All tests
npm run test:gauntlet    # Full test suite in order
npm run test:coverage    # Generate coverage report

API Overview

MCP Protocol Endpoints

// Initialize connection
POST /mcp/initialize
{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "clientInfo": { "name": "client", "version": "1.0" }
  }
}

// List available tools
POST /mcp/tools/list
{
  "jsonrpc": "2.0",
  "method": "tools/list"
}

// Invoke tool
POST /mcp/tools/call
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "analyze_text",
    "arguments": { "text": "..." }
  }
}

REST API Endpoints

GET  /api/health           # Health check
GET  /api/agents           # List agents
POST /api/orchestrate      # Start orchestration
GET  /api/orchestrations   # List orchestrations
GET  /api/metrics          # System metrics

Performance

  • Response Time: < 100ms p95 for simple requests
  • Throughput: 1000+ requests/second
  • Concurrent Orchestrations: 100+ simultaneous
  • Context Processing: 100K+ tokens/second
  • Error Recovery: < 5 second MTTR

Security

  • JWT-based authentication
  • Role-based access control (RBAC)
  • API key management
  • Request rate limiting
  • Input validation and sanitization
  • Encrypted data at rest and in transit

Contributing

See for development workflow and guidelines.

Documentation

License

MIT License - See LICENSE file for details.

Support

Roadmap

Phase 1 (Current)

  • āœ… Core MCP implementation
  • āœ… Basic orchestration
  • āœ… Test framework
  • āœ… Docker deployment

Phase 2 (Q2 2025)

  • Advanced orchestration patterns
  • Plugin system
  • Kubernetes operators
  • Multi-region support

Phase 3 (Q3 2025)

  • Auto-scaling
  • Advanced monitoring
  • GraphQL API
  • WebSocket transport