flowchart TD
    Client["Host MCP Client\n(Claude Desktop / Cursor / Antigravity / Zed)"]

    subgraph Server["MCP Agent Orchestrator Server"]
        subgraph Transport["MCP Protocol Layer (stdio)"]
            Tools["MCP Tools\n(start_swarm, run_pipeline, spawn_agent, etc.)"]
            Status["Inspection Tools\n(get_task_status, list_jobs, approve_checkpoint)"]
        end

        subgraph Kernel["Orchestration Kernel"]
            Dispatcher["Task Dispatcher & Scheduler"]
            PolicyEngine["Workspace & Safety Policy Gatekeeper"]
            Supervisor["Swarm Supervisor"]
            DAGRunner["Pipeline DAG Runner"]
            AgentPool["Interactive Agent Pool"]
        end

        subgraph Inference["Inference Layer"]
            Agy["Local agy CLI\n(Zero Keys)"]
            Ollama["Local Ollama\n(Zero Keys)"]
            Cloud["Cloud APIs\n(Gemini / Anthropic / OpenAI / DeepSeek)"]
        end

        subgraph Capabilities["Subagent Capabilities"]
            Builtins["Workspace Tools\n(fs, shell, web)"]
            Bridge["MCP Bridge\n(External MCP Servers)"]
        end

        subgraph Persistence["Storage & Dashboard"]
            DB[("SQLite Storage\n(data/orchestrator.db)")]
            UI["Web Dashboard\n(http://localhost:4000)"]
        end
    end

    Client <-->|"stdio"| Transport
    Transport --> Dispatcher
    Dispatcher --> PolicyEngine
    PolicyEngine --> Supervisor & DAGRunner & AgentPool
    Supervisor & DAGRunner & AgentPool --> Inference
    Supervisor & DAGRunner & AgentPool <--> Capabilities
    Dispatcher <--> DB
    DB <--> UI

# Run the built-in system diagnostics & health check
npx mcp-agent-orchestrator doctor

# Generate a starter orchestrator.yaml in your current directory
npx mcp-agent-orchestrator init

# Start the MCP server over stdio
npx mcp-agent-orchestrator

npm install -g mcp-agent-orchestrator

# Now available anywhere in your terminal
mcp-agent-orchestrator doctor
mcp-agent-orchestrator init
mcp-agent-orchestrator

git clone https://github.com/ShashankIIITN/mcp-agent-orchestrator.git
cd mcp-agent-orchestrator

# Install dependencies and compile TypeScript
npm install
npm run build

# Run all 14 unit and integration tests
npm test

version: "1.0"

server:
  port: 4000 # Web Dashboard port (http://localhost:4000)
  storage:
    type: "sqlite"
    connection_string: "./data/orchestrator.db"
  security:
    default_safety_mode: "semi-autonomous" # autonomous | semi-autonomous | safe
    allowed_workspaces:
      - "./"
      - "D:/"

# ─────────────────────────────────────────────────────────────────────────
# INFERENCE PROVIDERS
# Choose your setup: Local (Zero API Keys), Cloud API Keys, or Hybrid
# ─────────────────────────────────────────────────────────────────────────
inference:
  default_provider: "direct"
  providers:

    # ── Option A: Local Antigravity CLI (Zero API Keys) ──
    # Auto-detected on Windows, macOS, and Linux!
    agy:
      type: "agy"
      model: "gemini-3.8-flash-high" # Or "claude-sonnet-4-6", "gemini-3.1-pro-high"

    # ── Option B: Local Ollama (Zero API Keys) ──
    ollama:
      type: "ollama"
      base_url: "http://localhost:11434"
      model: "llama3.3"

    # ── Option C: Cloud API Providers (Require API Keys) ──
    gemini:
      type: "gemini"
      model: "gemini-2.5-flash"
      api_key_env: "GEMINI_API_KEY"

    anthropic:
      type: "anthropic"
      model: "claude-3-7-sonnet-20250219"
      api_key_env: "ANTHROPIC_API_KEY"

    openai:
      type: "openai"
      model: "gpt-4o"
      api_key_env: "OPENAI_API_KEY"

    # ── Option D: Custom OpenAI-Compatible (DeepSeek, Groq, Together) ──
    deepseek:
      type: "openai-compatible"
      base_url: "https://api.deepseek.com"
      model: "deepseek-coder"
      api_key_env: "DEEPSEEK_API_KEY"

# ─────────────────────────────────────────────────────────────────────────
# DECLARATIVE AGENT PERSONAS
# Assign each agent whichever provider you prefer (local or cloud)
# ─────────────────────────────────────────────────────────────────────────
agents:
  researcher:
    role: "Research & Documentation Specialist"
    provider: "agy" # Using zero-key local model
    tools: ["web_fetch", "fs_read", "fs_list"]
    system_prompt: "You are an expert researcher. Synthesize concise and factual summaries."

  coder:
    role: "Senior Software Engineer"
    provider: "agy"
    tools: ["fs_read", "fs_write", "fs_list", "shell_exec"]
    system_prompt: "You are a senior engineer. Write clean, robust code and verify changes."

  reviewer:
    role: "Staff Security & QA Auditor"
    provider: "agy"
    tools: ["fs_read", "fs_list", "shell_exec"]
    system_prompt: "You are a staff reviewer focused on correctness, edge cases, and security."

# ─────────────────────────────────────────────────────────────────────────
# PRESET PIPELINES
# ─────────────────────────────────────────────────────────────────────────
pipelines:
  feature_implementation:
    stages:
      - name: "research"
        agent: "researcher"
        output_artifact: "research_notes.md"
        checkpoint: false
      - name: "code"
        agent: "coder"
        input_artifacts: ["research_notes.md"]
        output_artifact: "implementation.md"
        checkpoint: true # Pauses for human approval
      - name: "review"
        agent: "reviewer"
        input_artifacts: ["implementation.md"]
        checkpoint: false

# ─────────────────────────────────────────────────────────────────────────
# EXTERNAL MCP GATEWAYS (Optional)
# Subagents can call tools from these external servers
# ─────────────────────────────────────────────────────────────────────────
mcp_gateways:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"

# Using npx (portable):
agy mcp add agent-orchestrator npx -y mcp-agent-orchestrator

# OR using local build:
agy mcp add agent-orchestrator node "D:\my project\mcp-agent-orchestrator\dist\index.js" "D:\my project\mcp-agent-orchestrator\orchestrator.yaml"

agy mcp list

{
  "mcpServers": {
    "agent-orchestrator": {
      "command": "npx",
      "args": ["-y", "mcp-agent-orchestrator"]
    }
  }
}