agent-bridge-mcp 1.0.0

package/README.md

@@ -0,0 +1,138 @@
+# agent-bridge-mcp
+
+MCP server that enables multiple Claude Code sessions to discover each other and exchange messages through a shared filesystem message bus.
+
+Open multiple Claude Code tabs in the same project. Each tab can register a name, see other active tabs, and send/receive messages — no external services required.
+
+## Install
+
+```bash
+npm install -g agent-bridge-mcp
+```
+
+Or clone and install locally:
+
+```bash
+git clone https://github.com/Lloydm15/agent-bridge-mcp.git
+cd agent-bridge-mcp
+npm install
+```
+
+## Setup
+
+Add to your Claude Code MCP config:
+
+**Global** (`~/.claude/.mcp.json`) — available in all projects:
+
+```json
+{
+  "mcpServers": {
+    "agent-bridge": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["agent-bridge-mcp"]
+    }
+  }
+}
+```
+
+**Or local** (`.mcp.json` in project root) — available in one project:
+
+```json
+{
+  "mcpServers": {
+    "agent-bridge": {
+      "command": "npx",
+      "args": ["agent-bridge-mcp"]
+    }
+  }
+}
+```
+
+Then reload your editor window.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `register_agent` | Name yourself (e.g., "frontend-dev", "reviewer") |
+| `list_agents` | See all active agents across all tabs |
+| `send_message` | Message a specific agent by name or ID |
+| `read_messages` | Check for unread messages |
+| `broadcast` | Message all active agents |
+
+## How It Works
+
+Each Claude Code tab spawns its own MCP server process. Since they can't share memory, all communication goes through the filesystem:
+
+- **Agents** register by writing a JSON file to a shared `agents/` directory
+- **Messages** are individual JSON files in a `messages/` directory (atomic creation, no corruption)
+- **Heartbeat** every 15s keeps agent registrations fresh
+- **Dead agents** are auto-cleaned via PID liveness checks and heartbeat staleness
+- **Messages expire** after 1 hour (configurable)
+
+```
+Data directory:
+  agents/
+    agent-a3f1c9.json    # { id, name, project, pid, lastHeartbeat }
+  messages/
+    1740524430000-x7k2f9.json  # { from, to, content, timestamp }
+```
+
+## Example Usage
+
+**Tab 1:**
+> Register as "frontend-dev"
+
+**Tab 2:**
+> Register as "api-dev"
+
+**Tab 1:**
+> Send a message to api-dev: "I changed the auth response type, update your endpoint handlers"
+
+**Tab 2:**
+> Check messages
+
+> Got message from frontend-dev: "I changed the auth response type, update your endpoint handlers"
+
+## Configuration
+
+All settings are optional. Defaults work out of the box.
+
+| Environment Variable | Default | Description |
+|---------------------|---------|-------------|
+| `AGENT_BRIDGE_DATA_DIR` | Platform-specific (see below) | Directory for agent and message files |
+| `AGENT_BRIDGE_HEARTBEAT_MS` | `15000` | Heartbeat interval in milliseconds |
+| `AGENT_BRIDGE_DEAD_MS` | `300000` | Time before stale agents are removed |
+| `AGENT_BRIDGE_MESSAGE_TTL_MS` | `3600000` | Time before old messages are deleted |
+
+**Default data directories:**
+- **Windows:** `%LOCALAPPDATA%\agent-bridge`
+- **macOS:** `~/Library/Application Support/agent-bridge`
+- **Linux:** `$XDG_DATA_HOME/agent-bridge` (or `~/.local/share/agent-bridge`)
+
+Pass env vars through your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "agent-bridge": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["agent-bridge-mcp"],
+      "env": {
+        "AGENT_BRIDGE_MESSAGE_TTL_MS": "7200000"
+      }
+    }
+  }
+}
+```
+
+## Requirements
+
+- Node.js >= 18
+- Any MCP-compatible client (Claude Code, etc.)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "agent-bridge-mcp",
+  "version": "1.0.0",
+  "description": "MCP server enabling communication between multiple Claude Code sessions via shared filesystem message bus",
+  "type": "module",
+  "main": "server.mjs",
+  "bin": {
+    "agent-bridge-mcp": "server.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "claude-code",
+    "agent",
+    "multi-agent",
+    "communication",
+    "bridge"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Lloydm15/agent-bridge-mcp.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "server.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}

package/server.mjs

@@ -0,0 +1,542 @@
+#!/usr/bin/env node
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from '@modelcontextprotocol/sdk/types.js';
+import {
+  existsSync, mkdirSync, writeFileSync, readFileSync,
+  readdirSync, unlinkSync, renameSync
+} from 'fs';
+import { resolve, dirname } from 'path';
+import { randomBytes } from 'crypto';
+import { homedir, tmpdir, platform } from 'os';
+
+// ============================================================
+// Constants (configurable via environment variables)
+// ============================================================
+
+function getDefaultDataDir() {
+  // XDG_DATA_HOME on Linux, ~/Library/Application Support on macOS, LOCALAPPDATA on Windows
+  const p = platform();
+  if (p === 'win32') {
+    return resolve(process.env.LOCALAPPDATA || resolve(homedir(), 'AppData', 'Local'), 'agent-bridge');
+  }
+  if (p === 'darwin') {
+    return resolve(homedir(), 'Library', 'Application Support', 'agent-bridge');
+  }
+  // Linux / other — XDG spec
+  return resolve(process.env.XDG_DATA_HOME || resolve(homedir(), '.local', 'share'), 'agent-bridge');
+}
+
+const BRIDGE_DIR = process.env.AGENT_BRIDGE_DATA_DIR || getDefaultDataDir();
+const AGENTS_DIR = resolve(BRIDGE_DIR, 'agents');
+const MESSAGES_DIR = resolve(BRIDGE_DIR, 'messages');
+const HEARTBEAT_INTERVAL_MS = parseInt(process.env.AGENT_BRIDGE_HEARTBEAT_MS || '15000', 10);
+const STALE_THRESHOLD_MS = HEARTBEAT_INTERVAL_MS * 3;
+const DEAD_THRESHOLD_MS = parseInt(process.env.AGENT_BRIDGE_DEAD_MS || '300000', 10);
+const MESSAGE_TTL_MS = parseInt(process.env.AGENT_BRIDGE_MESSAGE_TTL_MS || '3600000', 10);
+
+// ============================================================
+// Agent State (in-memory, per-process)
+// ============================================================
+
+const agentId = `agent-${randomBytes(3).toString('hex')}`;
+let agentName = null;
+const startedAt = new Date().toISOString();
+let lastReadTimestamp = Date.now();  // only read messages after we start
+let heartbeatTimer = null;
+
+// ============================================================
+// Directory Setup
+// ============================================================
+
+function ensureDirs() {
+  mkdirSync(AGENTS_DIR, { recursive: true });
+  mkdirSync(MESSAGES_DIR, { recursive: true });
+}
+
+// ============================================================
+// Process Liveness Check
+// ============================================================
+
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ============================================================
+// Agent File Operations
+// ============================================================
+
+function getAgentData() {
+  return {
+    id: agentId,
+    name: agentName,
+    project: process.cwd().split(/[\\/]/).pop(),
+    cwd: process.cwd(),
+    pid: process.pid,
+    startedAt,
+    lastHeartbeat: new Date().toISOString()
+  };
+}
+
+function writeAgentFile() {
+  const data = JSON.stringify(getAgentData(), null, 2);
+  const targetPath = resolve(AGENTS_DIR, `${agentId}.json`);
+  const tmpPath = targetPath + '.tmp';
+  try {
+    writeFileSync(tmpPath, data);
+    renameSync(tmpPath, targetPath);
+  } catch (err) {
+    // Fallback: direct write if rename fails
+    try { writeFileSync(targetPath, data); } catch {}
+  }
+}
+
+function removeAgentFile() {
+  try { unlinkSync(resolve(AGENTS_DIR, `${agentId}.json`)); } catch {}
+  try { unlinkSync(resolve(AGENTS_DIR, `${agentId}.json.tmp`)); } catch {}
+}
+
+function readAgentFile(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// ============================================================
+// Get All Agents (with staleness detection + cleanup)
+// ============================================================
+
+function getAllAgents() {
+  const agents = [];
+  let files;
+  try {
+    files = readdirSync(AGENTS_DIR).filter(f => f.endsWith('.json'));
+  } catch {
+    return agents;
+  }
+
+  const now = Date.now();
+
+  for (const file of files) {
+    const filePath = resolve(AGENTS_DIR, file);
+    const agent = readAgentFile(filePath);
+    if (!agent) continue;
+
+    const heartbeatAge = now - new Date(agent.lastHeartbeat).getTime();
+    const pidAlive = isProcessAlive(agent.pid);
+
+    // Dead process — clean up immediately
+    if (!pidAlive && agent.id !== agentId) {
+      try { unlinkSync(filePath); } catch {}
+      continue;
+    }
+
+    // Very stale — clean up
+    if (heartbeatAge > DEAD_THRESHOLD_MS && agent.id !== agentId) {
+      try { unlinkSync(filePath); } catch {}
+      continue;
+    }
+
+    agents.push({
+      ...agent,
+      status: heartbeatAge > STALE_THRESHOLD_MS ? 'stale' : 'active',
+      isMe: agent.id === agentId
+    });
+  }
+
+  return agents;
+}
+
+// ============================================================
+// Cleanup
+// ============================================================
+
+function cleanOldMessages() {
+  let files;
+  try {
+    files = readdirSync(MESSAGES_DIR).filter(f => f.endsWith('.json'));
+  } catch {
+    return;
+  }
+
+  const cutoff = Date.now() - MESSAGE_TTL_MS;
+
+  for (const file of files) {
+    const timestamp = parseInt(file.split('-')[0], 10);
+    if (!isNaN(timestamp) && timestamp < cutoff) {
+      try { unlinkSync(resolve(MESSAGES_DIR, file)); } catch {}
+    }
+  }
+}
+
+// ============================================================
+// Heartbeat
+// ============================================================
+
+function startHeartbeat() {
+  heartbeatTimer = setInterval(() => {
+    writeAgentFile();
+    cleanOldMessages();
+  }, HEARTBEAT_INTERVAL_MS);
+  heartbeatTimer.unref();
+}
+
+// ============================================================
+// Message Operations
+// ============================================================
+
+function writeMessage(to, toName, content, isBroadcast) {
+  const now = Date.now();
+  const rand = randomBytes(3).toString('hex');
+  const msgId = `msg-${now}-${rand}`;
+  const filename = `${now}-${rand}.json`;
+
+  const message = {
+    id: msgId,
+    from: agentId,
+    fromName: agentName,
+    to: isBroadcast ? '*' : to,
+    toName: isBroadcast ? null : toName,
+    broadcast: isBroadcast,
+    content,
+    project: process.cwd().split(/[\\/]/).pop(),
+    timestamp: new Date(now).toISOString()
+  };
+
+  const filePath = resolve(MESSAGES_DIR, filename);
+  writeFileSync(filePath, JSON.stringify(message, null, 2), { flag: 'wx' });
+  return message;
+}
+
+function readNewMessages(includeBroadcasts = true) {
+  let files;
+  try {
+    files = readdirSync(MESSAGES_DIR).filter(f => f.endsWith('.json')).sort();
+  } catch {
+    return [];
+  }
+
+  const messages = [];
+
+  for (const file of files) {
+    const timestamp = parseInt(file.split('-')[0], 10);
+    if (isNaN(timestamp) || timestamp <= lastReadTimestamp) continue;
+
+    const filePath = resolve(MESSAGES_DIR, file);
+    let msg;
+    try {
+      msg = JSON.parse(readFileSync(filePath, 'utf8'));
+    } catch {
+      continue;
+    }
+
+    // Skip own messages
+    if (msg.from === agentId) continue;
+
+    // Check if addressed to us or broadcast
+    const isForMe = msg.to === agentId || msg.toName === agentName;
+    const isBroadcast = msg.broadcast && msg.to === '*';
+
+    if (isForMe || (isBroadcast && includeBroadcasts)) {
+      messages.push({
+        ...msg,
+        ageSeconds: Math.round((Date.now() - new Date(msg.timestamp).getTime()) / 1000)
+      });
+    }
+  }
+
+  // Update read cursor
+  if (files.length > 0) {
+    const lastFile = files[files.length - 1];
+    const lastTs = parseInt(lastFile.split('-')[0], 10);
+    if (!isNaN(lastTs) && lastTs > lastReadTimestamp) {
+      lastReadTimestamp = lastTs;
+    }
+  }
+
+  return messages;
+}
+
+// ============================================================
+// Resolve Agent Target (name or ID)
+// ============================================================
+
+function resolveAgent(nameOrId) {
+  const agents = getAllAgents().filter(a => !a.isMe && a.status === 'active');
+
+  // Exact ID match
+  const byId = agents.find(a => a.id === nameOrId);
+  if (byId) return byId;
+
+  // Exact name match (case-insensitive)
+  const byName = agents.find(a => a.name && a.name.toLowerCase() === nameOrId.toLowerCase());
+  if (byName) return byName;
+
+  // Partial name match
+  const partial = agents.filter(a => a.name && a.name.toLowerCase().includes(nameOrId.toLowerCase()));
+  if (partial.length === 1) return partial[0];
+
+  return null;
+}
+
+// ============================================================
+// Tool Handlers
+// ============================================================
+
+async function handleRegister(args) {
+  const name = args.name?.trim();
+  if (!name) return { error: 'Name is required' };
+
+  // Check uniqueness
+  const agents = getAllAgents().filter(a => !a.isMe && a.status === 'active');
+  const conflict = agents.find(a => a.name && a.name.toLowerCase() === name.toLowerCase());
+  if (conflict) {
+    return {
+      error: `Name "${name}" is already taken by ${conflict.id} (project: ${conflict.project})`,
+      suggestion: `Try "${name}-2" or a different name`
+    };
+  }
+
+  agentName = name;
+  writeAgentFile();
+
+  return {
+    registered: true,
+    id: agentId,
+    name: agentName,
+    project: process.cwd().split(/[\\/]/).pop(),
+    cwd: process.cwd(),
+    pid: process.pid
+  };
+}
+
+async function handleListAgents() {
+  const agents = getAllAgents();
+  return {
+    agents,
+    totalActive: agents.filter(a => a.status === 'active').length,
+    myId: agentId,
+    myName: agentName
+  };
+}
+
+async function handleSendMessage(args) {
+  const { to, content } = args;
+  if (!to) return { error: 'Target agent (to) is required' };
+  if (!content) return { error: 'Message content is required' };
+
+  const target = resolveAgent(to);
+  if (!target) {
+    const agents = getAllAgents().filter(a => !a.isMe && a.status === 'active');
+    return {
+      error: `No active agent found matching "${to}"`,
+      availableAgents: agents.map(a => ({ id: a.id, name: a.name, project: a.project }))
+    };
+  }
+
+  const msg = writeMessage(target.id, target.name, content, false);
+  return {
+    sent: true,
+    messageId: msg.id,
+    to: { id: target.id, name: target.name },
+    timestamp: msg.timestamp
+  };
+}
+
+async function handleReadMessages(args) {
+  const includeBroadcasts = args.include_broadcasts !== false;
+  const messages = readNewMessages(includeBroadcasts);
+  return {
+    messages,
+    count: messages.length,
+    myId: agentId,
+    myName: agentName
+  };
+}
+
+async function handleBroadcast(args) {
+  const { content } = args;
+  if (!content) return { error: 'Message content is required' };
+
+  const agents = getAllAgents().filter(a => !a.isMe && a.status === 'active');
+  const msg = writeMessage('*', null, content, true);
+
+  return {
+    broadcast: true,
+    messageId: msg.id,
+    activeRecipients: agents.length,
+    timestamp: msg.timestamp
+  };
+}
+
+// ============================================================
+// Tool Definitions
+// ============================================================
+
+const TOOLS = [
+  {
+    name: 'register_agent',
+    description: 'Register this agent with a human-readable name so other agents can find and message you. Call this at the start of a session.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          description: 'A short human-readable name for this agent (e.g., "frontend-dev", "reviewer", "planner")'
+        }
+      },
+      required: ['name']
+    }
+  },
+  {
+    name: 'list_agents',
+    description: 'List all active agents across all tabs. Shows agent ID, name, project, and status.',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    }
+  },
+  {
+    name: 'send_message',
+    description: 'Send a message to a specific agent by name or ID. Use list_agents first to see who is available.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        to: {
+          type: 'string',
+          description: 'The name or ID of the target agent'
+        },
+        content: {
+          type: 'string',
+          description: 'The message content to send'
+        }
+      },
+      required: ['to', 'content']
+    }
+  },
+  {
+    name: 'read_messages',
+    description: 'Check for new messages sent to you since your last read. Returns unread messages in chronological order.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        include_broadcasts: {
+          type: 'boolean',
+          description: 'Whether to include broadcast messages (default: true)'
+        }
+      }
+    }
+  },
+  {
+    name: 'broadcast',
+    description: 'Send a message to ALL active agents. Use sparingly — prefer direct messages when you know the recipient.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        content: {
+          type: 'string',
+          description: 'The message content to broadcast to all agents'
+        }
+      },
+      required: ['content']
+    }
+  }
+];
+
+// ============================================================
+// Tool Dispatcher
+// ============================================================
+
+async function handleToolCall(name, args) {
+  switch (name) {
+    case 'register_agent': return handleRegister(args);
+    case 'list_agents': return handleListAgents();
+    case 'send_message': return handleSendMessage(args);
+    case 'read_messages': return handleReadMessages(args);
+    case 'broadcast': return handleBroadcast(args);
+    default: return { error: `Unknown tool: ${name}` };
+  }
+}
+
+// ============================================================
+// MCP Server
+// ============================================================
+
+const server = new Server(
+  { name: 'agent-bridge', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    const result = await handleToolCall(name, args || {});
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify(result, null, 2)
+      }]
+    };
+  } catch (err) {
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: `Tool execution failed: ${err.message}`,
+          tool: name,
+          args
+        }, null, 2)
+      }],
+      isError: true
+    };
+  }
+});
+
+// ============================================================
+// Main
+// ============================================================
+
+async function main() {
+  ensureDirs();
+  cleanOldMessages();
+  writeAgentFile();
+  startHeartbeat();
+
+  // Cleanup on exit
+  const cleanup = () => {
+    if (heartbeatTimer) clearInterval(heartbeatTimer);
+    removeAgentFile();
+  };
+  process.on('exit', cleanup);
+  process.on('SIGTERM', () => { cleanup(); process.exit(0); });
+  process.on('SIGINT', () => { cleanup(); process.exit(0); });
+
+  // Connect stdio transport
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  console.error(`[AgentBridge] Server running`);
+  console.error(`[AgentBridge] Agent ID: ${agentId}`);
+  console.error(`[AgentBridge] Data dir: ${BRIDGE_DIR}`);
+}
+
+main().catch(err => {
+  console.error(`[AgentBridge] Fatal: ${err.message}`);
+  process.exit(1);
+});