feat(local-coord-mcp): wire into BoJ MCP bridge — end-to-end working

Integration of local-coord-mcp cartridge with the MCP bridge:

- mcp-bridge/lib/tools.js: add 6 coord_* tool definitions (register,
  list_peers, send, receive, claim_task, status) with JSON schemas
- mcp-bridge/main.js: dispatch coord_* directly to 127.0.0.1:7745
  with graceful unavailable fallback + hint
- mcp-bridge/lib/offline-menu.js: add local-coord-mcp to tier_ayo,
  total 23→24
- TOPOLOGY.md: port 7745 + cartridge listing, 96→97 total

Also fixes two pre-existing bugs blocking the integration:

1. mcp-bridge/main.js: restore import statements stripped by f1fd38e.
   The modularization commit split main.js into lib/ modules but a
   follow-up removed the imports without inlining the functions,
   leaving buildToolList/fetchHealth/etc. as undefined references.
   The bridge has been broken since then; this commit restores the
   imports matching the pre-f1fd38e state.

2. cartridges/local-coord-mcp/adapter/build.zig: update to Zig 0.15
   ExecutableOptions API (use root_module, not root_source_file).

3. cartridges/local-coord-mcp/adapter/local_coord_adapter.zig:
   discard the c_int return from boj_cartridge_init() — Zig 0.15
   rejects ignored return values.

End-to-end verified:
- Adapter binds to 127.0.0.1:7745, direct curl returns success
- MCP bridge tools/list includes all 6 coord_* tools
- MCP bridge tools/call for coord_register dispatches to adapter
  and returns success through the full JSON-RPC stack

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

TOPOLOGY.md

@@ -1,7 +1,7 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # TOPOLOGY.md — BoJ Server Component Matrix
 #
-# Auto-generated 2026-04-09. 96 cartridges across 6 tiers.
+# Auto-generated 2026-04-09. 97 cartridges across 6 tiers.
 
 ## Ports
 
@@ -11,8 +11,9 @@
 | 7701 | gRPC | Running |
 | 7702 | GraphQL | Running |
 | 7703 | SSE (Server-Sent Events) | Running |
+| 7745 | local-coord-mcp (loopback only) | Running |
 
-## Cartridge Matrix (96 total)
+## Cartridge Matrix (97 total)
 
 ### Tier 1 — High-Value APIs (11)
 | Cartridge | Domain |
@@ -94,10 +95,11 @@
 | laminar-mcp | Flow monitoring |
 | ums-mcp | Unified monitoring |
 
-### Hyperpolymath Ecosystem (26)
+### Hyperpolymath Ecosystem (27)
 | Cartridge | Domain |
 |-----------|--------|
 | agent-mcp | Agent orchestration |
+| local-coord-mcp | Localhost multi-instance coordination (loopback only, port 7745) |
 | affinescript-mcp | Language tooling |
 | aerie-mcp | Deployment |
 | bsp-mcp | Build Server Protocol |

cartridges/local-coord-mcp/adapter/build.zig

@@ -15,12 +15,16 @@ pub fn build(b: *std.Build) void {
         .optimize = optimize,
     });
 
-    const adapter = b.addExecutable(.{
-        .name = "local_coord_adapter",
+    const adapter_mod = b.createModule(.{
         .root_source_file = b.path("local_coord_adapter.zig"),
         .target = target,
         .optimize = optimize,
     });
-    adapter.root_module.addImport("local_coord_ffi", ffi_mod);
+    adapter_mod.addImport("local_coord_ffi", ffi_mod);
+
+    const adapter = b.addExecutable(.{
+        .name = "local_coord_adapter",
+        .root_module = adapter_mod,
+    });
     b.installArtifact(adapter);
 }

cartridges/local-coord-mcp/adapter/local_coord_adapter.zig

@@ -87,7 +87,7 @@ fn handleConnection(stream: std.net.Stream) void {
 }
 
 pub fn main() !void {
-    ffi.boj_cartridge_init();
+    _ = ffi.boj_cartridge_init();
 
     // CRITICAL: Bind to loopback ONLY.
     const addr = std.net.Address.initIp4(BIND_ADDR, REST_PORT);

mcp-bridge/lib/offline-menu.js

@@ -35,6 +35,8 @@ export const OFFLINE_MENU = {
     { name: "secrets-mcp", version: "0.1.0", domain: "Secrets", protocols: ["MCP","REST"], status: "Available", available: true },
     { name: "proof-mcp", version: "0.1.0", domain: "Proof", protocols: ["MCP","REST"], status: "Available", available: true },
   ],
-  tier_ayo: [],
-  summary: { total: 23, ready: 23, mounted: 0 },
+  tier_ayo: [
+    { name: "local-coord-mcp", version: "0.1.0", domain: "Agent", protocols: ["MCP","Agentic"], status: "Available", available: true, notes: "Localhost-only (127.0.0.1:7745) multi-instance AI coordination — peer discovery, message passing, task claiming" },
+  ],
+  summary: { total: 24, ready: 24, mounted: 0 },
 };

mcp-bridge/lib/tools.js

@@ -264,6 +264,83 @@ function buildToolList() {
     },
   });
 
+  // Local coordination (localhost multi-instance AI coordination — local-coord-mcp cartridge)
+  tools.push({
+    name: "coord_register",
+    description: "Register this AI instance as a coordination peer on localhost. Returns a hybrid peer ID (e.g. claude-7f3a) and a session token for all subsequent calls. Loopback-only, never exposed beyond 127.0.0.1.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        client_kind: { type: "string", enum: ["claude", "gemini", "copilot", "custom"], description: "Client type prefix for the peer ID" },
+      },
+      required: ["client_kind"],
+    },
+  });
+
+  tools.push({
+    name: "coord_list_peers",
+    description: "List all active AI instances registered on this machine — their peer IDs, client kinds, states, and current status.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        token: { type: "string", description: "Session token from coord_register" },
+      },
+      required: ["token"],
+    },
+  });
+
+  tools.push({
+    name: "coord_send",
+    description: "Send a message to a specific peer (by peer ID) or broadcast to all peers (target '*'). Messages are queued in recipient inboxes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        token: { type: "string", description: "Session token from coord_register" },
+        target: { type: "string", description: "Peer ID to send to, or '*' for broadcast" },
+        message: { type: "string", description: "Message content" },
+      },
+      required: ["token", "target", "message"],
+    },
+  });
+
+  tools.push({
+    name: "coord_receive",
+    description: "Receive the next message from this peer's inbox. Returns the message content and sender, or indicates empty inbox.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        token: { type: "string", description: "Session token from coord_register" },
+      },
+      required: ["token"],
+    },
+  });
+
+  tools.push({
+    name: "coord_claim_task",
+    description: "Attempt to claim a task (mutex-style). If the task is unclaimed, this peer becomes the holder. If another peer holds it, returns the holder's peer ID. Idempotent if already held by caller. Use this to prevent two AI instances from duplicating work.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        token: { type: "string", description: "Session token from coord_register" },
+        task: { type: "string", description: "Task identifier to claim (e.g. 'audit-boj-server')" },
+      },
+      required: ["token", "task"],
+    },
+  });
+
+  tools.push({
+    name: "coord_status",
+    description: "Set this peer's current work status, visible to other peers via coord_list_peers.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        token: { type: "string", description: "Session token from coord_register" },
+        status: { type: "string", description: "Current work status description" },
+      },
+      required: ["token", "status"],
+    },
+  });
+
   return tools;
 }
 

mcp-bridge/main.js

@@ -11,6 +11,27 @@
 // Usage: deno run --allow-net main.js
 //    or: node main.js
 
+import {
+  RATE_LIMIT,
+  isInputSizeOk,
+  isValidToolName,
+  rateLimitAllow,
+  sanitizeErrorMessage,
+  scanObjectForInjection,
+  validateRequiredStrings,
+} from "./lib/security.js";
+import {
+  fetchCartridgeInfo,
+  fetchCartridges,
+  fetchHealth,
+  fetchMenu,
+  handleGitHubTool,
+  handleGitLabTool,
+  invokeCartridge,
+} from "./lib/api-clients.js";
+import { buildToolList } from "./lib/tools.js";
+import { info, warn, error as logError } from "./lib/logger.js";
+
 const BOJ_BASE = process.env.BOJ_URL || "http://localhost:7700";
 const SERVER_NAME = "boj-server";
 const SERVER_VERSION = "0.3.1";
@@ -206,11 +227,47 @@ async function dispatchTool(toolName, args) {
     case "boj_research":
       return invokeCartridge("research-mcp", args);
 
+    // Local coordination — direct to loopback backend on port 7745
+    case "coord_register":
+    case "coord_list_peers":
+    case "coord_send":
+    case "coord_receive":
+    case "coord_claim_task":
+    case "coord_status":
+      return dispatchLocalCoord(toolName, args);
+
     default:
       return null; // unknown tool
   }
 }
 
+// ===================================================================
+// local-coord-mcp direct dispatch (loopback only, port 7745)
+// ===================================================================
+
+const LOCAL_COORD_URL = process.env.COORD_BACKEND_URL || "http://127.0.0.1:7745";
+
+async function dispatchLocalCoord(toolName, args) {
+  try {
+    const res = await fetch(`${LOCAL_COORD_URL}/tools/${toolName}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(args || {}),
+    });
+    try {
+      return await res.json();
+    } catch {
+      return { success: false, error: "local-coord-mcp backend returned non-JSON" };
+    }
+  } catch (e) {
+    return {
+      success: false,
+      error: `local-coord-mcp backend unavailable at ${LOCAL_COORD_URL}: ${e.message}`,
+      hint: "Start the adapter: cd cartridges/local-coord-mcp/adapter && zig build run",
+    };
+  }
+}
+
 // ===================================================================
 // MCP message handler
 // ===================================================================