Orca – MCP Orchestrator Platform

A cross‑platform orchestration system for managing multiple MCP (Model Context Protocol) servers with supervised processes, health monitoring, dependency planning, an interactive TUI dashboard, and a REST Status API.

   ██████╗ ██████╗  ██████╗ █████╗
  ██╔═══██╗██╔══██╗██╔════╝██╔══██╗
  ██║   ██║██████╔╝██║     ███████║
  ██║   ██║██╔══██╗██║     ██╔══██║
  ╚██████╔╝██║  ██║╚██████╗██║  ██║
   ╚═════╝ ╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝   MCP Orchestrator

---

Table of Contents

• Features
• Project Structure
• Installation
• Quick Start
• Configuration
• Environment Variable Interpolation
• CLI Usage
• TUI Dashboard
• Status API
• Logging
• Health Monitoring
• Dependency Planning
• Restart Policies
• Lifecycle Hooks
• Integrations (Plugin System)
• Testing
• Roadmap
• Contributing
• License

---

Features

• Process supervision & restart backoff (ProcessManager)
• Structured + human log handling (ServerLogManager)
• HTTP / stdio / SSE transports with unmanaged server support
• Health checks (HTTP, TCP, stdio) (HealthChecker)
• Dependency DAG + cycle detection (DependencyPlanner.get_startup_order)
• Port allocation with preferred ports (PortAllocator)
• 🎨 Beautiful Interactive TUI with responsive design, ASCII logo, and enhanced styling (Dashboard)
• REST Status API (StatusAPI)
• 🔌 Integration System - Plugin-based architecture supporting VS Code Augment Code and extensible to other sources
• Configuration validation (OrchestratorConfig.validate)
• Lifecycle hooks & controlled shutdown (execute_lifecycle_hook in util)
• Windows-friendly execution with headless process management (no popup windows)

Planned / partial (scaffolding present):

• Real-time event streaming (SSE endpoints)
• Dynamic configuration hot‑reload
• Extended metrics & performance summaries
• Additional integration plugins (Docker Compose, Kubernetes, etc.)

---

Project Structure

orchestrator/
  cli.py                # CLI entrypoint
  config.py             # YAML loading + validation
  models.py             # Data models (ServerSpec, RestartSpec, etc.)
  planner.py            # Dependency graph + topological sort
  ports.py              # Port allocation
  process.py            # Process supervision & environment prep
  health.py             # Health checking strategies
  logs.py               # Rotating & structured logging
  state.py              # State registry & snapshots
  util.py               # Cross-platform helpers & hooks
  api/status.py         # FastAPI status endpoints
  ui/dashboard.py       # Textual dashboard + fallback monitor
  ui/styles.py          # Palette / formatting
  integrations/         # Plugin system (foundation)
tests/
  test_config.py
  test_planner.py
  test_ports.py

---

Installation

# Clone repository
git clone <your-repo-url> orca
cd orca

# (Optional) create virtual env
python -m venv .venv
. .venv/Scripts/activate  # Windows
# or
source .venv/bin/activate

# Install runtime dependencies
pip install -r requirements.txt

# (Optional) editable install for console script
pip install -e .

Run directly:

python -m orchestrator.cli up
# or (if console script installed)
orca start

---

Quick Start

1. Create orca.yaml:

version: 1
settings:
  status_port: 7555
  log_dir: ./.orchestrator/logs
  graceful_shutdown_seconds: 12
  ui: textual

servers:
  # Example HTTP microservice (Python)
  - name: api-service
    cwd: services/api
    cmd: ["python", "app.py"]
    transport: http
    prefer_port: 8001
    health:
      type: http
      path: /health
      timeout_ms: 4000
      initial_delay_ms: 500
    restart:
      enabled: true
      max_restarts: 5
      backoff_seconds: [1, 2, 4, 8]
    tags: [api, core]

  # Example long‑running scanner / worker (Go, Node, etc.)
  - name: worker-scanner
    cwd: services/worker
    cmd: ["go", "run", "./cmd/worker"]  # or ["node", "server.js"]
    transport: http
    prefer_port: 8002
    health:
      type: tcp
      path: /
      timeout_ms: 4000
      initial_delay_ms: 1000
    restart:
      enabled: true
      max_restarts: 3
      backoff_seconds: [2, 5, 10]
    tags: [worker, background]

1. Validate:

orca validate

1. Start:

orca start
# or headless
orca start --no-tui

1. Inspect status:

curl http://127.0.0.1:7555/status

---

Configuration

Loader: load_config
Validation: OrchestratorConfig.validate
Server model: ServerSpec
Restart spec: RestartSpec
Health spec: HealthSpec

Key fields (per server):

name: string
cwd: path
cmd: [executable, args...]
transport: http|stdio|sse
prefer_port: <int>
env: { KEY: VALUE }
health:
  type: http|tcp|stdio|none
  path: /health
  timeout_ms: 4000
  initial_delay_ms: 500
restart:
  enabled: true
  max_restarts: 5
  backoff_seconds: [1,2,4,8]
tags: [list, of, labels]
depends_on: [other-server-names]
hooks:
  pre_start: [...]
  post_start: [...]
  pre_stop: [...]
  post_stop: [...]
  pre_restart: [...]
  post_restart: [...]
  timeout_seconds: 30

---

Environment Variable Interpolation

Handled in interpolate_env_vars.
Forms:

• ${VAR} (required)
• ${VAR:-default} (optional default)

Example:

env:
  API_KEY: ${API_KEY}
  DEBUG: ${DEBUG:-false}
  PORT: ${API_PORT:-8080}

---

CLI Usage

Entrypoint: OrchestratorCLI

orca start                # Start all (alias: up)
orca start --no-tui       # Headless
orca start --servers a b  # Subset
orca stop                 # Stop all (alias: down)
orca restart worker-scanner
orca ps --watch           # Periodic refresh
orca ps --json
orca logs api-service --lines 200 --follow
orca validate --config custom.yaml

Options:

• --config <file>
• --log-level DEBUG|INFO|...
• --log-file path/to/file.log
• --grace <seconds> (on stop)

---

TUI Dashboard

Source: Dashboard
Styles / palette: OrchestratorStyles

Key (implemented subset; some placeholders):

q / Ctrl+C  Quit
h / ?       Help
(Planned: filtering, restart keys, log interactions)

Fallback: simple Rich table if Textual unavailable.

---

Status API

Implementation: StatusAPI
Default base: http://127.0.0.1:<status_port>

Endpoints (current core):

GET /status
GET /status/{server_name}
GET /logs/{server_name}/tail?lines=100&log_type=human|json
GET /health

(Planned: /events/stream, /logs/{server}/stream, integration endpoints)

Example:

curl http://127.0.0.1:7555/status
curl "http://127.0.0.1:7555/logs/api-service/tail?lines=50"

---

Logging

Core setup: setup_orchestrator_logging
Per-server manager: ServerLogManager

Features:

• Rotating file logs (10MB × 5)
• Human formatter + structured JSON formatter
• Console handler safely disabled during TUI (see set_console_logging_enabled in logs.py)

---

Health Monitoring

Logic: HealthChecker
Supports:

• HTTP probe
• TCP/port readiness
• stdio heartbeat (via process status) Config tuning via timeout_ms, initial_delay_ms, success/failure thresholds.

---

Dependency Planning

Graph build + cycle detection: DependencyPlanner
Order retrieval: DependencyPlanner.get_startup_order
Raises DependencyError on cycles.

---

Restart Policies

Defined in RestartSpec
Managed by supervisor / process controller (see ProcessManager & supervisor layer).
Exponential/backoff sequencing via configurable list.

---

Lifecycle Hooks

Executed with timeout via helper: execute_lifecycle_hook
Configure under hooks: in server spec. Failing pre-start hook aborts startup.

Example:

hooks:
  pre_start: ["echo 'Preparing'"]
  post_start: ["curl -fsS http://127.0.0.1:8080/health || exit 1"]
  pre_stop: ["echo 'Stopping'"]
  post_stop: ["echo 'Stopped'"]
  timeout_seconds: 30

---

Integrations (Plugin System)

Foundation in:

• IntegrationPlugin
• IntegrationManager (if present)
• Example: AugmentCodeIntegration

Capabilities (scaffold):

• Normalization (_normalize_name)
• External discovery sources
• Merge strategies (planned)

Status: early stage; REST + CLI surface for integrations not fully exposed yet.

---

Testing

Light tests:

• Config: tests/test_config.py
• Planner: tests/test_planner.py
• Ports: tests/test_ports.py Utility scripts:
• Manual functional script: test_orchestrator.py
• Enhanced API runner: test_runner.py

Run:

pytest
pytest --cov=orchestrator
python test_orchestrator.py
python test_runner.py

---

Roadmap (Condensed)

Near-term:

• SSE event / log streaming
• Integration sync CLI + API
• Live log viewer in TUI
• Advanced filtering (tags / capability)
• Hot config reload & diff validation
• Extended metrics (CPU / RSS / restart trend)

Mid-term:

• Plugin adapters (Docker Compose, Kubernetes, custom YAML/JSON)
• Job system + run artifact management (external platform tie‑ins)
• Web UI (orchestrator status proxy)

Longer-term:

• Predictive health scoring
• Cross-platform packaging
• Recipe / automation layer integration

---

Contributing

1. Fork
2. Create feature branch
3. Add/change code + tests
4. Run tests & lint
5. Open PR with concise summary

---

License

MIT – see LICENSE.

---

Acknowledgments

Inspiration from ecosystem tooling; emphasis on portability, clarity, and safe orchestration.

---

Appendix: Minimal Example

version: 1
settings:
  status_port: 7555
  log_dir: ./.orchestrator/logs

servers:
  - name: demo
    cwd: .
    cmd: ["python", "-c", "import time; print('demo up'); time.sleep(60)"]
    transport: stdio
    health:
      type: stdio
      timeout_ms: 3000
      initial_delay_ms: 500
    restart:
      enabled: true
      max_restarts: 2
      backoff_seconds: [1,2]
    tags: [demo, example]

Start:

orca start --config orca.yaml

---

Key References (Code Links)

• CLI: OrchestratorCLI
• Config: OrchestratorConfig
• Models: ServerSpec, RestartSpec, HealthSpec
• Logging: setup_orchestrator_logging
• Dependency Planning: DependencyPlanner
• Ports: PortAllocator
• Process Env Prep: ProcessManager._prepare_environment
• Health: HealthChecker
• Dashboard: Dashboard
• Styles: OrchestratorStyles
• API: StatusAPI
• Integrations Base: IntegrationPlugin
• Utilities: format_duration

---

Clear, modular, extensible orchestration for