agent-coordinator/README_old.md

AgentCoordinator

A distributed task coordination system for AI agents built with Elixir and NATS.

Overview

AgentCoordinator is a centralized task management system designed to enable multiple AI agents (Claude Code, GitHub Copilot, etc.) to work collaboratively on the same codebase without conflicts. It provides:

• Distributed Task Management: Centralized task queue with agent-specific inboxes
• Conflict Resolution: File-level locking prevents agents from working on the same files
• Real-time Communication: NATS messaging for instant coordination
• Persistent Storage: Event sourcing with configurable retention policies
• MCP Integration: Model Context Protocol server for agent communication
• Fault Tolerance: Elixir supervision trees ensure system resilience

Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Agent 1    │    │   AI Agent 2     │    │   AI Agent N    │
│  (Claude Code)  │    │   (Copilot)      │    │      ...        │
└─────────┬───────┘    └─────────┬────────┘    └─────────┬───────┘
          │                      │                       │
          └──────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────┴──────────────┐
                    │    MCP Server Interface    │
                    └─────────────┬──────────────┘
                                 │
                    ┌─────────────┴──────────────┐
                    │    AgentCoordinator        │
                    │                            │
                    │  ┌──────────────────────┐  │
                    │  │   Task Registry      │  │
                    │  │   ┌──────────────┐   │  │
                    │  │   │ Agent Inbox  │   │  │
                    │  │   │ Agent Inbox  │   │  │
                    │  │   │ Agent Inbox  │   │  │
                    │  │   └──────────────┘   │  │
                    │  └──────────────────────┘  │
                    │                            │
                    │  ┌──────────────────────┐  │
                    │  │   NATS Messaging     │  │
                    │  └──────────────────────┘  │
                    │                            │
                    │  ┌──────────────────────┐  │
                    │  │   Persistence        │  │
                    │  │   (JetStream)        │  │
                    │  └──────────────────────┘  │
                    └────────────────────────────┘

Installation

Prerequisites

• Elixir 1.16+ and Erlang/OTP 28+
• NATS server (with JetStream enabled)

Setup

1. Install Dependencies

   mix deps.get
   

2. Start NATS Server

   # Using Docker
   docker run -p 4222:4222 -p 8222:8222 nats:latest -js
   
   # Or install locally and run
   nats-server -js
   

3. Configure Environment

   export NATS_HOST=localhost
   export NATS_PORT=4222
   

4. Start the Application

   iex -S mix
   

Usage

Command Line Interface

# Register an agent
mix run -e "AgentCoordinator.CLI.main([\"register\", \"CodeBot\", \"coding\", \"testing\"])"

# Create a task
mix run -e "AgentCoordinator.CLI.main([\"create-task\", \"Fix login bug\", \"User login fails\", \"priority=high\"])"

# View task board
mix run -e "AgentCoordinator.CLI.main([\"board\"])"

MCP Integration

Available MCP tools for agents:

• register_agent - Register a new agent
• create_task - Create a new task
• get_next_task - Get next task for agent
• complete_task - Mark current task complete
• get_task_board - View all agent statuses
• heartbeat - Send agent heartbeat

Connecting to GitHub Copilot

Step 1: Start the MCP Server

The AgentCoordinator MCP server needs to be running and accessible via stdio. Here's how to set it up:

1. Create MCP Server Launcher Script

   # Create a launcher script for the MCP server
   cat > mcp_launcher.sh << 'EOF'
   #!/bin/bash
   cd /home/ra/agent_coordinator
   export MIX_ENV=prod
   mix run --no-halt -e "
   # Start the application
   Application.ensure_all_started(:agent_coordinator)
   
   # Start MCP stdio interface
   IO.puts(\"MCP server started...\")
   
   # Read JSON-RPC messages from stdin and send responses to stdout
   spawn(fn ->
     Stream.repeatedly(fn -> IO.read(:stdio, :line) end)
     |> Stream.take_while(&(&1 != :eof))
     |> Enum.each(fn line ->
       case String.trim(line) do
         \"\" -> :ok
         json_line ->
           try do
             request = Jason.decode!(json_line)
             response = AgentCoordinator.MCPServer.handle_mcp_request(request)
             IO.puts(Jason.encode!(response))
           rescue
             e ->
               error_response = %{
                 \"jsonrpc\" => \"2.0\",
                 \"id\" => Map.get(Jason.decode!(json_line), \"id\", null),
                 \"error\" => %{\"code\" => -32603, \"message\" => Exception.message(e)}
               }
               IO.puts(Jason.encode!(error_response))
           end
       end
     end)
   end)
   
   # Keep process alive
   Process.sleep(:infinity)
   "
   EOF
   chmod +x mcp_launcher.sh
   

Step 2: Configure VS Code for MCP

1. Install Required Extensions

   • Make sure you have the latest GitHub Copilot extension
   • Install any MCP-related VS Code extensions if available

2. Create MCP Configuration Create or update your VS Code settings to include the MCP server:

   // In your VS Code settings.json or workspace settings
   {
     "github.copilot.advanced": {
       "mcp": {
         "servers": {
           "agent-coordinator": {
             "command": "/home/ra/agent_coordinator/mcp_launcher.sh",
             "args": [],
             "env": {}
           }
         }
       }
     }
   }
   

Step 3: Alternative Direct Integration

If VS Code MCP integration isn't available yet, you can create a VS Code extension to bridge the gap:

1. Create Extension Scaffold

   mkdir agent-coordinator-extension
   cd agent-coordinator-extension
   npm init -y
   
   # Create package.json for VS Code extension
   cat > package.json << 'EOF'
   {
     "name": "agent-coordinator",
     "displayName": "Agent Coordinator",
     "description": "Integration with AgentCoordinator MCP server",
     "version": "0.1.0",
     "engines": { "vscode": "^1.74.0" },
     "categories": ["Other"],
     "activationEvents": ["*"],
     "main": "./out/extension.js",
     "contributes": {
       "commands": [
         {
           "command": "agentCoordinator.registerAgent",
           "title": "Register as Agent"
         },
         {
           "command": "agentCoordinator.getNextTask",
           "title": "Get Next Task"
         },
         {
           "command": "agentCoordinator.viewTaskBoard",
           "title": "View Task Board"
         }
       ]
     },
     "devDependencies": {
       "@types/vscode": "^1.74.0",
       "typescript": "^4.9.0"
     }
   }
   EOF
   

Step 4: Direct Command Line Usage

For immediate use, you can interact with the MCP server directly:

1. Start the Server

   cd /home/ra/agent_coordinator
   iex -S mix
   

2. In another terminal, use the MCP tools

   # Test MCP server directly
   cd /home/ra/agent_coordinator
   mix run demo_mcp_server.exs
   

Step 5: Production Deployment

1. Create Systemd Service for MCP Server

   sudo tee /etc/systemd/system/agent-coordinator-mcp.service > /dev/null << EOF
   [Unit]
   Description=Agent Coordinator MCP Server
   After=network.target nats.service
   Requires=nats.service
   
   [Service]
   Type=simple
   User=ra
   WorkingDirectory=/home/ra/agent_coordinator
   Environment=MIX_ENV=prod
   Environment=NATS_HOST=localhost
   Environment=NATS_PORT=4222
   ExecStart=/usr/bin/mix run --no-halt
   Restart=always
   RestartSec=5
   
   [Install]
   WantedBy=multi-user.target
   EOF
   
   sudo systemctl daemon-reload
   sudo systemctl enable agent-coordinator-mcp
   sudo systemctl start agent-coordinator-mcp
   

2. Check Status

   sudo systemctl status agent-coordinator-mcp
   sudo journalctl -fu agent-coordinator-mcp