agent-bridge-mcp 1.0.0 → 1.2.0

package/README.md

@@ -1,8 +1,8 @@
 # agent-bridge-mcp
 
-MCP server that enables multiple Claude Code sessions to discover each other and exchange messages through a shared filesystem message bus.
+MCP server that enables multiple Claude Code sessions to discover each other, exchange messages, and share working context through a shared filesystem 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.
+Open multiple Claude Code tabs across different projects. Each tab can register a name, see other active tabs, send/receive messages, and share accumulated knowledge — no external services required. Context persists after sessions end.
 
 ## Install
 
@@ -36,30 +36,37 @@ Add to your Claude Code MCP config:
 }
 ```
 
-**Or local** (`.mcp.json` in project root) — available in one project:
+**Per-project** (`.mcp.json` in project root) — with auto-registration:
 
 ```json
 {
   "mcpServers": {
     "agent-bridge": {
       "command": "npx",
-      "args": ["agent-bridge-mcp"]
+      "args": ["agent-bridge-mcp"],
+      "env": {
+        "AGENT_BRIDGE_NAME": "my-agent-name"
+      }
     }
   }
 }
 ```
 
+Setting `AGENT_BRIDGE_NAME` automatically registers the agent on startup — no need to call `register_agent` manually.
+
 Then reload your editor window.
 
 ## Tools
 
 | Tool | Description |
 |------|-------------|
-| `register_agent` | Name yourself (e.g., "frontend-dev", "reviewer") |
+| `register_agent` | Name yourself (e.g., "frontend-dev", "reviewer"). Not needed if `AGENT_BRIDGE_NAME` is set. |
 | `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 |
+| `share_context` | Dump your accumulated working knowledge so other agents can read it. Persists after session ends. |
+| `get_context` | Read shared context from another agent by name, or get all shared contexts. Works even if that agent is dead. |
 
 ## How It Works
 
@@ -67,9 +74,11 @@ Each Claude Code tab spawns its own MCP server process. Since they can't share m
 
 - **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)
+- **Context** is stored per-agent in a `context/` directory, keyed by agent name (not session ID), so knowledge survives session restarts
 - **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)
+- **Context persists** indefinitely until overwritten by the same agent name
 
 ```
 Data directory:
@@ -77,10 +86,14 @@ Data directory:
     agent-a3f1c9.json    # { id, name, project, pid, lastHeartbeat }
   messages/
     1740524430000-x7k2f9.json  # { from, to, content, timestamp }
+  context/
+    nova-main.json       # { agentName, agentId, project, updatedAt, content }
 ```
 
 ## Example Usage
 
+### Messaging
+
 **Tab 1:**
 > Register as "frontend-dev"
 
@@ -92,16 +105,28 @@ Data directory:
 
 **Tab 2:**
 > Check messages
-
 > Got message from frontend-dev: "I changed the auth response type, update your endpoint handlers"
 
+### Context Sharing
+
+**Project A (nova-main):**
+> Share context: "Working on auth flow. Modified auth.ts and login.tsx. Using JWT with refresh tokens. API endpoint is /api/auth/login."
+
+**Project B (emergence-main):**
+> Get context from nova-main
+
+> Returns: "Working on auth flow. Modified auth.ts and login.tsx. Using JWT with refresh tokens. API endpoint is /api/auth/login."
+
+Context persists even after nova-main's session ends — emergence-main can read it anytime.
+
 ## 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_NAME` | *(none)* | Auto-register with this name on startup |
+| `AGENT_BRIDGE_DATA_DIR` | Platform-specific (see below) | Directory for agent, message, and context 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 |
@@ -121,6 +146,7 @@ Pass env vars through your MCP config:
       "command": "npx",
       "args": ["agent-bridge-mcp"],
       "env": {
+        "AGENT_BRIDGE_NAME": "my-agent",
         "AGENT_BRIDGE_MESSAGE_TTL_MS": "7200000"
       }
     }
@@ -128,6 +154,50 @@ Pass env vars through your MCP config:
 }
 ```
 
+## Automatic Context Sharing (Stop Hook)
+
+The `--ingest` flag lets you auto-capture every conversation exchange into the context directory — no manual `share_context` calls needed.
+
+**How it works:** Claude Code fires a [Stop hook](https://docs.anthropic.com/en/docs/claude-code/hooks) after every agent response. The hook pipes `session_id` and `last_assistant_message` via stdin. `agent-bridge-mcp --ingest` reads this, pairs it with the user prompt (saved by a `UserPromptSubmit` hook), strips system tags, and appends the exchange to the agent's context file.
+
+**Setup:**
+
+1. Add a `UserPromptSubmit` hook to save user prompts (required for `--ingest` to capture both sides):
+
+Add to `~/.claude/settings.json`:
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx agent-bridge-mcp --capture-prompt",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx agent-bridge-mcp --ingest",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Set `AGENT_BRIDGE_NAME` in your project's `.mcp.json` so the ingest knows which agent name to write as.
+
+Context is stored as the last 20 exchanges per agent, accessible via `get_context`.
+
 ## Requirements
 
 - Node.js >= 18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-bridge-mcp",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "MCP server enabling communication between multiple Claude Code sessions via shared filesystem message bus",
   "type": "module",
   "main": "server.mjs",

package/server.mjs

@@ -34,6 +34,7 @@ function getDefaultDataDir() {
 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 CONTEXT_DIR = resolve(BRIDGE_DIR, 'context');
 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);
@@ -44,7 +45,7 @@ const MESSAGE_TTL_MS = parseInt(process.env.AGENT_BRIDGE_MESSAGE_TTL_MS || '3600
 // ============================================================
 
 const agentId = `agent-${randomBytes(3).toString('hex')}`;
-let agentName = null;
+let agentName = process.env.AGENT_BRIDGE_NAME || null;
 const startedAt = new Date().toISOString();
 let lastReadTimestamp = Date.now();  // only read messages after we start
 let heartbeatTimer = null;
@@ -56,6 +57,7 @@ let heartbeatTimer = null;
 function ensureDirs() {
   mkdirSync(AGENTS_DIR, { recursive: true });
   mkdirSync(MESSAGES_DIR, { recursive: true });
+  mkdirSync(CONTEXT_DIR, { recursive: true });
 }
 
 // ============================================================
@@ -380,6 +382,87 @@ async function handleBroadcast(args) {
   };
 }
 
+// ============================================================
+// Context Operations
+// ============================================================
+
+function writeContextFile(name, content) {
+  const safeName = name.replace(/[^a-zA-Z0-9_-]/g, '_').toLowerCase();
+  const data = JSON.stringify({
+    agentName: name,
+    agentId,
+    project: process.cwd().split(/[\\/]/).pop(),
+    updatedAt: new Date().toISOString(),
+    content
+  }, null, 2);
+  const targetPath = resolve(CONTEXT_DIR, `${safeName}.json`);
+  const tmpPath = targetPath + '.tmp';
+  try {
+    writeFileSync(tmpPath, data);
+    renameSync(tmpPath, targetPath);
+  } catch (err) {
+    try { writeFileSync(targetPath, data); } catch {}
+  }
+}
+
+function readAllContextFiles() {
+  let files;
+  try {
+    files = readdirSync(CONTEXT_DIR).filter(f => f.endsWith('.json'));
+  } catch {
+    return [];
+  }
+  const contexts = [];
+  for (const file of files) {
+    try {
+      const ctx = JSON.parse(readFileSync(resolve(CONTEXT_DIR, file), 'utf8'));
+      contexts.push(ctx);
+    } catch {
+      continue;
+    }
+  }
+  return contexts;
+}
+
+async function handleShareContext(args) {
+  const { content } = args;
+  if (!content) return { error: 'Content is required — dump what you know' };
+  if (!agentName) return { error: 'Register with a name first (register_agent) before sharing context' };
+
+  writeContextFile(agentName, content);
+
+  return {
+    shared: true,
+    agentName,
+    project: process.cwd().split(/[\\/]/).pop(),
+    updatedAt: new Date().toISOString(),
+    contentLength: content.length
+  };
+}
+
+async function handleGetContext(args) {
+  const { from } = args;
+
+  if (from) {
+    // Get context from a specific agent
+    const safeName = from.replace(/[^a-zA-Z0-9_-]/g, '_').toLowerCase();
+    const filePath = resolve(CONTEXT_DIR, `${safeName}.json`);
+    try {
+      const ctx = JSON.parse(readFileSync(filePath, 'utf8'));
+      return { found: true, context: ctx };
+    } catch {
+      return { found: false, error: `No shared context found for "${from}"` };
+    }
+  }
+
+  // Get all shared contexts
+  const contexts = readAllContextFiles();
+  return {
+    contexts,
+    count: contexts.length
+  };
+}
+
 // ============================================================
 // Tool Definitions
 // ============================================================
@@ -451,6 +534,33 @@ const TOOLS = [
       },
       required: ['content']
     }
+  },
+  {
+    name: 'share_context',
+    description: 'Share your accumulated working knowledge so other agents (even in other projects) can read it. Write a comprehensive dump of everything you know — files read, decisions made, key facts, current state. Context persists after your session ends.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        content: {
+          type: 'string',
+          description: 'Freeform text dump of everything you know that would be useful to another agent picking up where you left off'
+        }
+      },
+      required: ['content']
+    }
+  },
+  {
+    name: 'get_context',
+    description: 'Read shared context from another agent. Works even if that agent is no longer active — context persists across sessions. Call with no arguments to see all available contexts.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        from: {
+          type: 'string',
+          description: 'Name of the agent whose context you want to read (e.g., "nova-main"). Omit to get all shared contexts.'
+        }
+      }
+    }
   }
 ];
 
@@ -465,6 +575,8 @@ async function handleToolCall(name, args) {
     case 'send_message': return handleSendMessage(args);
     case 'read_messages': return handleReadMessages(args);
     case 'broadcast': return handleBroadcast(args);
+    case 'share_context': return handleShareContext(args);
+    case 'get_context': return handleGetContext(args);
     default: return { error: `Unknown tool: ${name}` };
   }
 }
@@ -474,7 +586,7 @@ async function handleToolCall(name, args) {
 // ============================================================
 
 const server = new Server(
-  { name: 'agent-bridge', version: '1.0.0' },
+  { name: 'agent-bridge', version: '1.2.0' },
   { capabilities: { tools: {} } }
 );
 
@@ -509,34 +621,179 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 });
 
 // ============================================================
-// Main
+// CLI: --capture-prompt (UserPromptSubmit hook mode)
 // ============================================================
+// Saves user prompt to temp file for --ingest to pair with.
+// Usage: node server.mjs --capture-prompt
+
+async function runCapturePrompt() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const raw = Buffer.concat(chunks).toString('utf8');
+
+  let data;
+  try { data = JSON.parse(raw); } catch { process.exit(0); }
+
+  const sessionId = data.session_id || '';
+  const prompt = data.prompt || '';
+  if (!sessionId || !prompt) process.exit(0);
+
+  // Strip system tags
+  const tagPatterns = [
+    /<system-reminder>[\s\S]*?<\/system-reminder>/g,
+    /<ide_opened_file>[\s\S]*?<\/ide_opened_file>/g,
+    /<ide_selection>[\s\S]*?<\/ide_selection>/g,
+    /<task-notification>[\s\S]*?<\/task-notification>/g,
+  ];
+  let clean = prompt;
+  for (const pat of tagPatterns) clean = clean.replace(pat, '');
+  clean = clean.replace(/\n\s*\n/g, '\n').trim();
+
+  if (clean.length < 5) process.exit(0);
+
+  const tmp = tmpdir();
+  writeFileSync(resolve(tmp, `agent-bridge-prompt-${sessionId}`), clean, 'utf8');
+  process.exit(0);
+}
+
+// ============================================================
+// CLI: --ingest (Stop hook mode)
+// ============================================================
+// Called by Claude Code Stop hook. Reads stdin JSON with
+// session_id + last_assistant_message, writes to context dir.
+// Usage: node server.mjs --ingest
 
-async function main() {
+async function runIngest() {
   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); });
+  // Read stdin
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const raw = Buffer.concat(chunks).toString('utf8');
+
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+
+  const sessionId = data.session_id || '';
+  const assistantMsg = data.last_assistant_message || '';
+  if (!sessionId || !assistantMsg) process.exit(0);
+
+  // Read user prompt saved by --capture-prompt hook
+  const tmp = tmpdir();
+  const promptPath = resolve(tmp, `agent-bridge-prompt-${sessionId}`);
+  let userMsg = '';
+  try {
+    userMsg = readFileSync(promptPath, 'utf8');
+  } catch {}
+
+  // Strip system tags
+  const tagPatterns = [
+    /<system-reminder>[\s\S]*?<\/system-reminder>/g,
+    /<task-notification>[\s\S]*?<\/task-notification>/g,
+    /<ide_opened_file>[\s\S]*?<\/ide_opened_file>/g,
+    /<ide_selection>[\s\S]*?<\/ide_selection>/g,
+  ];
+  let cleanAssistant = assistantMsg;
+  for (const pat of tagPatterns) cleanAssistant = cleanAssistant.replace(pat, '');
+  cleanAssistant = cleanAssistant.replace(/\n\s*\n/g, '\n').trim();
+
+  if (!cleanAssistant || cleanAssistant.length < 50) process.exit(0);
+
+  // Determine agent name from env or from active agent files
+  const name = process.env.AGENT_BRIDGE_NAME || findAgentNameForSession(sessionId);
+  if (!name) process.exit(0);
+
+  // Read existing context and append new exchange
+  const safeName = name.replace(/[^a-zA-Z0-9_-]/g, '_').toLowerCase();
+  const ctxPath = resolve(CONTEXT_DIR, `${safeName}.json`);
+  let existing = { exchanges: [] };
+  try {
+    const prev = JSON.parse(readFileSync(ctxPath, 'utf8'));
+    if (prev.exchanges) existing = prev;
+    else if (prev.content) existing = { exchanges: [{ role: 'context', content: prev.content }] };
+  } catch {}
+
+  // Keep last 20 exchanges to avoid unbounded growth
+  existing.exchanges.push({
+    timestamp: new Date().toISOString(),
+    user: userMsg.slice(0, 2000),
+    assistant: cleanAssistant.slice(0, 5000)
+  });
+  if (existing.exchanges.length > 20) {
+    existing.exchanges = existing.exchanges.slice(-20);
+  }
+
+  const ctxData = JSON.stringify({
+    agentName: name,
+    project: process.cwd().split(/[\\/]/).pop(),
+    updatedAt: new Date().toISOString(),
+    sessionId,
+    exchanges: existing.exchanges
+  }, null, 2);
 
-  // Connect stdio transport
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
+  const tmpPath = ctxPath + '.tmp';
+  try {
+    writeFileSync(tmpPath, ctxData);
+    renameSync(tmpPath, ctxPath);
+  } catch {
+    try { writeFileSync(ctxPath, ctxData); } catch {}
+  }
 
-  console.error(`[AgentBridge] Server running`);
-  console.error(`[AgentBridge] Agent ID: ${agentId}`);
-  console.error(`[AgentBridge] Data dir: ${BRIDGE_DIR}`);
+  process.exit(0);
 }
 
-main().catch(err => {
-  console.error(`[AgentBridge] Fatal: ${err.message}`);
-  process.exit(1);
-});
+function findAgentNameForSession(sessionId) {
+  // Look through agent files to find one from this process's cwd
+  try {
+    const files = readdirSync(AGENTS_DIR).filter(f => f.endsWith('.json'));
+    const cwd = process.cwd();
+    for (const file of files) {
+      const agent = readAgentFile(resolve(AGENTS_DIR, file));
+      if (agent && agent.name && agent.cwd === cwd) return agent.name;
+    }
+  } catch {}
+  return null;
+}
+
+// ============================================================
+// Main
+// ============================================================
+
+if (process.argv.includes('--capture-prompt')) {
+  runCapturePrompt().catch(() => process.exit(0));
+} else if (process.argv.includes('--ingest')) {
+  runIngest().catch(() => process.exit(0));
+} else {
+  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);
+  });
+}