ra/agent-coordinator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix docker startup so that it works properly with stdio mode. Probably worthwhile to toss majority of this readme, less confusing

Browse Source
This commit is contained in:
Ra
2025-09-08 19:34:32 -07:00
parent 5d3e04c5f8
commit 74a8574778
13 changed files with 386 additions and 564 deletions
Download Patch File Download Diff File Expand all files Collapse all files

413
README.md
View File

@@ -1,11 +1,9 @@
# Agent Coordinator
A **Model Context Protocol (MCP) server** that enables multiple AI agents to coordinate their work seamlessly across codebases without conflicts. Built with Elixir for reliability and fault tolerance.
Agent Coordinator is a MCP proxy server that enables multiple AI agents to collaborate seamlessly without conflicts. It acts as a single MCP interface that proxies ALL tool calls through itself, ensuring every agent maintains full project awareness while the coordinator tracks real-time agent presence.
## What is Agent Coordinator?
Agent Coordinator is a **MCP proxy server** that enables multiple AI agents to collaborate seamlessly without conflicts. As shown in the architecture diagram above, it acts as a **single MCP interface** that proxies ALL tool calls through itself, ensuring every agent maintains full project awareness while the coordinator tracks real-time agent presence.
**The coordinator operates as a transparent proxy layer:**
- **Single Interface**: All agents connect to one MCP server (the coordinator)
@@ -20,122 +18,23 @@ Agent Coordinator is a **MCP proxy server** that enables multiple AI agents to c
- **Codebase Registry**: Cross-repository coordination, dependency management, and workspace organization
- **Unified Tool Registry**: Seamlessly proxies external MCP tools while adding coordination capabilities
Instead of agents conflicting over files or duplicating work, they connect through a **single MCP proxy interface** that routes ALL tool calls through the coordinator. This ensures every tool usage updates agent presence, tracks coordinated tasks, and maintains real-time project awareness across all agents via shared task boards and agent inboxes.
**Key Features:**
- **MCP Proxy Architecture**: Single server that proxies ALL external MCP servers for unified agent access
- **Real-Time Activity Tracking**: Live visibility into agent activities: "Reading file.ex", "Editing main.py", "Sequential thinking"
- **Real-Time Presence Tracking**: Every tool call updates agent status and project awareness
- **File-Level Coordination**: Track exactly which files each agent is working on to prevent conflicts
- **Activity History**: Rolling log of recent agent actions with timestamps and file details
- **Multi-Agent Coordination**: Register multiple AI agents (GitHub Copilot, Claude, etc.) with different capabilities
- **Transparent Tool Routing**: Automatically routes tool calls to appropriate external servers while tracking usage
- **Automatic Task Creation**: Every tool usage becomes a tracked task with agent coordination context
- **Full Project Awareness**: All agents see unified project state through the proxy layer
- **External Server Management**: Automatically starts, monitors, and manages MCP servers defined in `mcp_servers.json`
- **Universal Tool Registry**: Proxies tools from all external servers while adding native coordination tools
- **Dynamic Tool Discovery**: Automatically discovers new tools when external servers start/restart
- **Cross-Codebase Support**: Coordinate work across multiple repositories and projects
- **MCP Standard Compliance**: Works with any MCP-compatible AI agent or tool
## Overview
![Agent Coordinator Architecture](docs/architecture-diagram.svg)
**The Agent Coordinator acts as a transparent MCP proxy server** that routes ALL tool calls through itself to maintain agent presence and provide full project awareness. Every external MCP server is proxied through the coordinator, ensuring unified agent coordination.
### Proxy Architecture Flow
1. **Agent Registration**: Multiple AI agents (Purple Zebra, Yellow Elephant, etc.) register with their capabilities
2. **External Server Discovery**: Coordinator automatically starts and discovers tools from external MCP servers
3. **Unified Proxy Interface**: All tools (native + external) are available through a single MCP interface
4. **Transparent Tool Routing**: ALL tool calls proxy through coordinator → external servers → coordinator → agents
5. **Presence Tracking**: Every proxied tool call updates agent heartbeat and task status
6. **Project Awareness**: All agents maintain unified project state through the proxy layer
## Real-Time Activity Tracking - FANTASTIC Feature!
**See exactly what every agent is doing in real-time!** The coordinator intelligently tracks and displays agent activities as they happen:
### Live Activity Examples
```json
{
"agent_id": "github-copilot-purple-elephant",
"name": "GitHub Copilot Purple Elephant",
"current_activity": "Reading mix.exs",
"current_files": ["/home/ra/agent_coordinator/mix.exs"],
"activity_history": [
{
"activity": "Reading mix.exs",
"files": ["/home/ra/agent_coordinator/mix.exs"],
"timestamp": "2025-09-06T16:41:09.193087Z"
},
{
"activity": "Sequential thinking: Analyzing the current codebase structure...",
"files": [],
"timestamp": "2025-09-06T16:41:05.123456Z"
},
{
"activity": "Editing agent.ex",
"files": ["/home/ra/agent_coordinator/lib/agent_coordinator/agent.ex"],
"timestamp": "2025-09-06T16:40:58.987654Z"
}
]
}
```
### 🚀 Activity Types Tracked
- **📂 File Operations**: "Reading config.ex", "Editing main.py", "Writing README.md", "Creating new_feature.js"
- **🧠 Thinking Activities**: "Sequential thinking: Analyzing the problem...", "Having a sequential thought..."
- **🔍 Search Operations**: "Searching for 'function'", "Semantic search for 'authentication'"
- **⚡ Terminal Commands**: "Running: mix test...", "Checking terminal output"
- **🛠️ VS Code Actions**: "VS Code: set editor content", "Viewing active editor in VS Code"
- **🧪 Testing**: "Running tests in user_test.exs", "Running all tests"
- **📊 Task Management**: "Creating task: Fix bug", "Getting next task", "Completing current task"
- **🌐 Web Operations**: "Fetching 3 webpages", "Getting library docs for React"
### 🎯 Benefits
- **🚫 Prevent File Conflicts**: See which files are being edited by which agents
- **👥 Coordinate Team Work**: Know when agents are working on related tasks
- **🐛 Debug Agent Behavior**: Track what agents did before encountering issues
- **📈 Monitor Progress**: Watch real-time progress across multiple agents
- **🔄 Optimize Workflows**: Identify bottlenecks and coordination opportunities
**Every tool call automatically updates the agent's activity - no configuration needed!** 🫡😸
<!-- ![Agent Coordinator Architecture](docs/architecture-diagram.svg) Let's not show this it's confusing -->
### 🏗️ Architecture Components
**Core Coordinator Components:**
- **Task Registry**: Intelligent task queuing, agent matching, and progress tracking
- **Agent Manager**: Registration, heartbeat monitoring, and capability-based assignment
- **Codebase Registry**: Cross-repository coordination and workspace management
- **Unified Tool Registry**: Combines native coordination tools with external MCP tools
- Task Registry: Intelligent task queuing, agent matching, and progress tracking
- Agent Manager: Registration, heartbeat monitoring, and capability-based assignment
Codebase Registry: Cross-repository coordination and workspace management
- Unified Tool Registry: Combines native coordination tools with external MCP tools
- Every tool call automatically updates the agent's activity for other agent's to see
**External Integration:**
- **MCP Servers**: Filesystem, Memory, Context7, Sequential Thinking, and more
- **VS Code Integration**: Direct editor commands and workspace management
- **Real-Time Dashboard**: Live task board showing agent status and progress
- VS Code Integration: Direct editor commands and workspace management
**Example Proxy Tool Call Flow:**
```text
Agent calls "read_file" → Coordinator proxies to filesystem server →
Updates agent presence + task tracking → Returns file content to agent
Result: All other agents now aware of the file access via task board
```
## 🔧 MCP Server Management & Unified Tool Registry
Agent Coordinator acts as a **unified MCP proxy server** that manages multiple external MCP servers while providing its own coordination capabilities. This creates a single, powerful interface for AI agents to access hundreds of tools seamlessly.
### 📡 External Server Management
### External Server Management
The coordinator automatically manages external MCP servers based on configuration in `mcp_servers.json`:
@@ -145,7 +44,7 @@ The coordinator automatically manages external MCP servers based on configuratio
"mcp_filesystem": {
"type": "stdio",
"command": "bunx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/ra"],
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
"auto_restart": true,
"description": "Filesystem operations server"
},
@@ -155,12 +54,6 @@ The coordinator automatically manages external MCP servers based on configuratio
"args": ["-y", "@modelcontextprotocol/server-memory"],
"auto_restart": true,
"description": "Memory and knowledge graph server"
},
"mcp_figma": {
"type": "http",
"url": "http://127.0.0.1:3845/mcp",
"auto_restart": true,
"description": "Figma design integration server"
}
},
"config": {
@@ -172,178 +65,202 @@ The coordinator automatically manages external MCP servers based on configuratio
}
```
**Server Lifecycle Management:**
1. **Startup**: Reads config and spawns each external server process
2. **Discovery**: Sends MCP `initialize` and `tools/list` requests to discover available tools
3. **Registration**: Adds discovered tools to the unified tool registry
4. **Monitoring**: Continuously monitors server health and heartbeat
5. **Auto-Restart**: Automatically restarts failed servers (if configured)
6. **Cleanup**: Properly terminates processes and cleans up resources on shutdown
### 🛠️ Unified Tool Registry
The coordinator combines tools from multiple sources into a single, coherent interface:
**Native Coordination Tools:**
- `register_agent` - Register agents with capabilities
- `create_task` - Create coordination tasks
- `get_next_task` - Get assigned tasks
- `complete_task` - Mark tasks complete
- `get_task_board` - View all agent status
- `heartbeat` - Maintain agent liveness
**External Server Tools (Auto-Discovered):**
- **Filesystem**: `read_file`, `write_file`, `list_directory`, `search_files`
- **Memory**: `search_nodes`, `store_memory`, `recall_information`
- **Context7**: `get-library-docs`, `search-docs`, `get-library-info`
- **Figma**: `get_code`, `get_designs`, `fetch_assets`
- **Sequential Thinking**: `sequentialthinking`, `analyze_problem`
- **VS Code**: `run_command`, `install_extension`, `open_file`, `create_task`
**Dynamic Discovery Process:**
1. **Startup**: Agent Coordinator starts external MCP server process
2. **Initialize**: Sends MCP `initialize` request → Server responds with capabilities
3. **Discovery**: Sends `tools/list` request → Server returns available tools
4. **Registration**: Adds discovered tools to unified tool registry
This process repeats automatically when servers restart or new servers are added.
### Intelligent Tool Routing
When an AI agent calls a tool, the coordinator intelligently routes the request:
**Routing Logic:**
1. **Native Tools**: Handled directly by Agent Coordinator modules
2. **External Tools**: Routed to the appropriate external MCP server
3. **VS Code Tools**: Routed to integrated VS Code Tool Provider
4. **Unknown Tools**: Return helpful error with available alternatives
**Automatic Task Tracking:**
- Every tool call automatically creates or updates agent tasks
- Maintains context of what agents are working on
- Provides visibility into cross-agent coordination
- Enables intelligent task distribution and conflict prevention
**Example Tool Call Flow:**
```bash
Agent calls "read_file" → Coordinator routes to filesystem server →
Updates agent task → Sends heartbeat → Returns file content
```
## Prerequisites
Choose one of these installation methods:
### Option 1: Docker (Recommended - No Elixir Installation Required)
[Docker](#1-start-nats-server)
- **Docker**: 20.10+ and Docker Compose
- **Node.js**: 18+ (for external MCP servers via bun)
### Option 2: Manual Installation
[Manual Installation](#manual-setup)
- **Elixir**: 1.16+ with OTP 26+
- **Mix**: Comes with Elixir installation
- **Node.js**: 18+ (for external MCP servers via bun)
- **Node.js**: 18+ (for some MCP servers)
- **uv**: If using python MCP servers
## ⚡ Quick Start
### Docker Setup
### Option A: Docker Setup (Easiest)
#### 1. Start NATS Server
#### 1. Get the Code
First, start a NATS server that the Agent Coordinator can connect to:
```bash
git clone https://github.com/your-username/agent_coordinator.git
cd agent_coordinator
# Start NATS server with persistent storage
docker run -d \
--name nats-server \
--network agent-coordinator-net \
-p 4222:4222 \
-p 8222:8222 \
-v nats_data:/data \
nats:2.10-alpine \
--jetstream \
--store_dir=/data \
--max_mem_store=1Gb \
--max_file_store=10Gb
# Create the network first if it doesn't exist
docker network create agent-coordinator-net
```
#### 2. Run with Docker Compose
#### 2. Configure Your AI Tools
**For STDIO Mode (Recommended - Direct MCP Integration):**
First, create a Docker network and start the NATS server:
```bash
# Start the full stack (MCP server + NATS + monitoring)
docker-compose up -d
# Create network for secure communication
docker network create agent-coordinator-net
# Or start just the MCP server
docker-compose up agent-coordinator
# Check logs
docker-compose logs -f agent-coordinator
# Start NATS server
docker run -d \
--name nats-server \
--network agent-coordinator-net \
-p 4222:4222 \
-v nats_data:/data \
nats:2.10-alpine \
--jetstream \
--store_dir=/data \
--max_mem_store=1Gb \
--max_file_store=10Gb
```
#### 3. Configuration
Then add this configuration to your VS Code `mcp.json` configuration file via `ctrl + shift + p` → `MCP: Open User Configuration` or `MCP: Open Remote User Configuration` if running on a remote server:
Edit `mcp_servers.json` to configure external MCP servers, then restart:
```bash
docker-compose restart agent-coordinator
```json
{
"servers": {
"agent-coordinator": {
"command": "docker",
"args": [
"run",
"--network=agent-coordinator-net",
"-v=./mcp_servers.json:/app/mcp_servers.json:ro",
"-v=/path/to/your/workspace:/workspace:rw",
"-e=NATS_HOST=nats-server",
"-e=NATS_PORT=4222",
"-i",
"--rm",
"ghcr.io/rooba/agentcoordinator:latest"
],
"type": "stdio"
}
}
}
```
### Option B: Manual Setup
**Important Notes for File System Access:**
#### 1. Clone the Repository
If you're using MCP filesystem servers, mount the directories they need access to:
```json
{
"args": [
"run",
"--network=agent-coordinator-net",
"-v=./mcp_servers.json:/app/mcp_servers.json:ro",
"-v=/home/user/projects:/home/user/projects:rw",
"-v=/path/to/workspace:/workspace:rw",
"-e=NATS_HOST=nats-server",
"-e=NATS_PORT=4222",
"-i",
"--rm",
"ghcr.io/rooba/agentcoordinator:latest"
]
}
```
**For HTTP/WebSocket Mode (Alternative - Web API Access):**
If you prefer to run as a web service instead of stdio:
```bash
git clone https://github.com/your-username/agent_coordinator.git
cd agent_coordinator
# Create network first
docker network create agent-coordinator-net
# Start NATS server
docker run -d \
--name nats-server \
--network agent-coordinator-net \
-p 4222:4222 \
-v nats_data:/data \
nats:2.10-alpine \
--jetstream \
--store_dir=/data \
--max_mem_store=1Gb \
--max_file_store=10Gb
# Run Agent Coordinator in HTTP mode
docker run -d \
--name agent-coordinator \
--network agent-coordinator-net \
-p 8080:4000 \
-v ./mcp_servers.json:/app/mcp_servers.json:ro \
-v /path/to/workspace:/workspace:rw \
-e NATS_HOST=nats-server \
-e NATS_PORT=4222 \
-e MCP_INTERFACE_MODE=http \
-e MCP_HTTP_PORT=4000 \
ghcr.io/rooba/agentcoordinator:latest
```
Then access via HTTP API at `http://localhost:8080/mcp` or configure your MCP client to use the HTTP endpoint.
Create or edit `mcp_servers.json` in your project directory to configure external MCP servers:
```json
{
"servers": {
"mcp_filesystem": {
"type": "stdio",
"command": "bunx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
"auto_restart": true
}
}
}
```
### Manual Setup
#### Clone the Repository
> It is suggested to install Elixir (and Erlang) via [asdf](https://asdf-vm.com/) for easy version management.
> NATS can be found at [nats.io](https://github.com/nats-io/nats-server/releases/latest), or via Docker
```bash
git clone https://github.com/rooba/agentcoordinator.git
cd agentcoordinator
mix deps.get
mix compile
```
#### 2. Start the MCP Server
#### Start the MCP Server directly
```bash
# Start the MCP server directly
export MCP_INTERFACE_MODE=stdio # or http / websocket
# export MCP_HTTP_PORT=4000 # if using http mode
./scripts/mcp_launcher.sh
# Or in development mode
mix run --no-halt
```
### 3. Configure Your AI Tools
### Run via VS Code or similar tools
#### For Docker Setup
If using Docker, the MCP server is available at the container's stdio interface. Add this to your VS Code `settings.json`:
Add this to your `mcp.json` or `mcp_servers.json` depending on your tool:
```json
{
"github.copilot.advanced": {
"mcp": {
"servers": {
"agent-coordinator": {
"command": "docker",
"args": ["exec", "-i", "agent-coordinator", "/app/scripts/mcp_launcher.sh"],
"env": {
"MIX_ENV": "prod"
}
}
}
}
}
}
```
#### For Manual Setup
Add this to your VS Code `settings.json`:
```json
{
"github.copilot.advanced": {
"mcp": {
"servers": {
"agent-coordinator": {
"command": "/path/to/agent_coordinator/scripts/mcp_launcher.sh",
"args": [],
"env": {
"MIX_ENV": "dev"
}
}
"servers": {
"agent-coordinator": {
"command": "/path/to/agent_coordinator/scripts/mcp_launcher.sh",
"args": [],
"env": {
"MIX_ENV": "prod",
"NATS_HOST": "localhost",
"NATS_PORT": "4222"
}
}
}