@eamonpluto/agentboard 2.2.0

package/bin/agentboard-mcp.js

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+/**
+ * agentboard-mcp — zero-dependency stdio MCP server for agent-board (DM-only).
+ *
+ * One artifact for every MCP-capable harness (Claude Code, Codex, Antigravity,
+ * opencode, grok-build): expose the DM bus as tools so sending/reading mail is
+ * "just a tool call" with no CLI wrapper needed.
+ *
+ *   Claude:  claude mcp add --scope project agentboard -- node ./bin/agentboard-mcp.js
+ *   Codex:   codex mcp add agentboard -- node ./bin/agentboard-mcp.js
+ *            (or [mcp_servers.agentboard] in config.toml)
+ *   Antigravity: .agents/mcp_config.json { mcpServers: { agentboard: { command: "node", args: [...] } } }
+ *   grok:    grok mcp add --scope project agentboard -- node ./bin/agentboard-mcp.js
+ *   opencode: { "mcp": { "agentboard": { "type": "local", "command": ["node", "./bin/agentboard-mcp.js"] } } }
+ *
+ * Board resolution: AGENTBOARD_DIR env wins, else <cwd>/.agentboard (harnesses
+ * launch stdio servers with cwd = project root, so this just works).
+ *
+ * Protocol: MCP over newline-delimited JSON-RPC on stdio. Methods handled:
+ * initialize, notifications/initialized, tools/list, tools/call, ping.
+ * Version negotiation: echo the client's protocolVersion when it is a known
+ * MCP revision, else fall back to 2024-11-05.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import readline from "node:readline";
+
+const MAX_BODY_CHARS = 8000;
+const SERVER_VERSION = "2.1.0";
+const KNOWN_PROTOCOL_VERSIONS = new Set(["2024-11-05", "2025-03-26", "2025-06-18"]);
+
+// ---------------------------------------------------------------------------
+// board (mirrors bin/agentboard.js layout v2; no import to stay dep-free)
+// ---------------------------------------------------------------------------
+
+function boardRoot() {
+  if (process.env.AGENTBOARD_DIR) return path.resolve(process.env.AGENTBOARD_DIR);
+  return path.join(process.cwd(), ".agentboard");
+}
+
+function dirs(root) {
+  return {
+    root,
+    agents: path.join(root, "agents"),
+    dm: path.join(root, "dm"),
+    delivered: path.join(root, "delivered"),
+  };
+}
+
+function ensureBoard(root) {
+  const d = dirs(root);
+  for (const p of [d.root, d.agents, d.dm, d.delivered]) fs.mkdirSync(p, { recursive: true });
+  const meta = path.join(d.root, "board.json");
+  if (!fs.existsSync(meta)) {
+    fs.writeFileSync(
+      meta,
+      JSON.stringify({ name: "board", version: 2, createdAt: new Date().toISOString() }, null, 2) + "\n"
+    );
+  }
+  return d;
+}
+
+function readJson(p) {
+  return JSON.parse(fs.readFileSync(p, "utf8"));
+}
+
+function writeJson(p, obj) {
+  const tmp = p + "." + crypto.randomBytes(4).toString("hex") + ".tmp";
+  fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\n");
+  fs.renameSync(tmp, p);
+}
+
+function cleanName(name, what) {
+  if (name === undefined || name === null || String(name).trim() === "")
+    throw new Error(`missing ${what}`);
+  const c = String(name).trim().replace(/[^A-Za-z0-9_.-]/g, "-").slice(0, 40);
+  if (!c) throw new Error(`invalid ${what}`);
+  return c;
+}
+
+function newId(prefix) {
+  const t = new Date();
+  const stamp =
+    t.getUTCFullYear().toString().slice(2) +
+    String(t.getUTCMonth() + 1).padStart(2, "0") +
+    String(t.getUTCDate()).padStart(2, "0") +
+    "-" +
+    String(t.getUTCHours()).padStart(2, "0") +
+    String(t.getUTCMinutes()).padStart(2, "0") +
+    String(t.getUTCSeconds()).padStart(2, "0");
+  return `${prefix}-${stamp}-${crypto.randomBytes(3).toString("hex")}`;
+}
+
+function listDMs(d, recipient) {
+  const dir = path.join(d.dm, recipient);
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith(".json"))
+    .sort()
+    .map((f) => {
+      try {
+        return readJson(path.join(dir, f));
+      } catch {
+        return null;
+      }
+    })
+    .filter((x) => x && x.id && x.from)
+    .sort((a, b) => String(a.at).localeCompare(String(b.at)) || String(a.id).localeCompare(String(b.id)));
+}
+
+function touchAgent(d, name, sessionId) {
+  const p = path.join(d.agents, `${name}.json`);
+  const now = new Date().toISOString();
+  let prev = null;
+  try {
+    prev = readJson(p);
+  } catch {}
+  writeJson(p, {
+    name,
+    firstSeen: (prev && prev.firstSeen) || now,
+    lastSeen: now,
+    sessionId: sessionId || (prev && prev.sessionId) || undefined,
+    lastDir: process.cwd(),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// tools
+// ---------------------------------------------------------------------------
+
+const TOOLS = [
+  {
+    name: "dm_send",
+    description:
+      "Send a direct message to another AI agent via agent-board. Fire-and-forget like Slack: the peer reads it via dm_inbox (or gets it pushed by their harness hook). Use whenever you want to coordinate, share a finding, or ask a peer.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        from: { type: "string", description: "Your stable agent name, e.g. alice. Keep it constant for the session." },
+        to: { type: "string", description: "Recipient agent name, e.g. bob." },
+        body: { type: "string", description: "Message text, 1..8000 chars." },
+      },
+      required: ["from", "to", "body"],
+    },
+  },
+  {
+    name: "dm_inbox",
+    description:
+      "Read your direct messages on agent-board. No mark-read side effects; page with after. Poll this often when your harness has no push hook.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        agent: { type: "string", description: "Your agent name." },
+        limit: { type: "number", description: "Max messages, newest last. Default 20." },
+        after: { type: "string", description: "Only messages after this message id." },
+      },
+      required: ["agent"],
+    },
+  },
+  {
+    name: "dm_agents",
+    description: "List agents known to this agent-board (registered names for addressing DMs).",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "dm_register",
+    description:
+      "Register your agent name on this agent-board (optionally binding a harness session id for push routing). Do this once per session.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        agent: { type: "string", description: "Your stable agent name." },
+        session: { type: "string", description: "Optional harness session/conversation id for push routing." },
+      },
+      required: ["agent"],
+    },
+  },
+];
+
+function toolResult(text) {
+  return { content: [{ type: "text", text }] };
+}
+
+function callTool(name, args) {
+  const d = ensureBoard(boardRoot());
+  const a = args && typeof args === "object" ? args : {};
+  switch (name) {
+    case "dm_send": {
+      const from = cleanName(a.from, "from");
+      const to = cleanName(a.to, "to");
+      const body = String(a.body ?? "").trim();
+      if (!body) throw new Error("empty body");
+      if (body.length > MAX_BODY_CHARS) throw new Error(`body too large (max ${MAX_BODY_CHARS} chars)`);
+      touchAgent(d, from);
+      const id = newId("msg");
+      const msg = { id, from, to, body, at: new Date().toISOString() };
+      fs.mkdirSync(path.join(d.dm, to), { recursive: true });
+      writeJson(path.join(d.dm, to, `${id}.json`), msg);
+      return toolResult(`sent ${id} -> ${to}`);
+    }
+    case "dm_inbox": {
+      const agent = cleanName(a.agent, "agent");
+      let items = listDMs(d, agent);
+      if (a.after !== undefined && a.after !== null && String(a.after) !== "") {
+        const idx = items.findIndex((m) => m.id === String(a.after));
+        if (idx !== -1) items = items.slice(idx + 1);
+      }
+      const limit = a.limit === undefined || a.limit === null ? 20 : Number(a.limit);
+      if (!(limit >= 0)) throw new Error("limit must be a non-negative number");
+      items = items.slice(-limit);
+      if (items.length === 0) return toolResult(`no messages for ${agent}`);
+      return toolResult(items.map((m) => `[${m.id}] from ${m.from} @ ${m.at}\n${m.body}`).join("\n\n"));
+    }
+    case "dm_agents": {
+      const dir = d.agents;
+      if (!fs.existsSync(dir)) return toolResult("no agents registered");
+      const names = fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith(".json"))
+        .map((f) => {
+          try {
+            return readJson(path.join(dir, f)).name;
+          } catch {
+            return null;
+          }
+        })
+        .filter(Boolean)
+        .sort();
+      if (names.length === 0) return toolResult("no agents registered (dm_register -- your name)");
+      return toolResult(names.join("\n"));
+    }
+    case "dm_register": {
+      const agent = cleanName(a.agent, "agent");
+      const session = a.session === undefined || a.session === null ? undefined : String(a.session);
+      touchAgent(d, agent, session || undefined);
+      return toolResult(`registered ${agent}${session ? ` (session ${session})` : ""}`);
+    }
+    default:
+      throw new Error(`unknown tool "${name}"`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// JSON-RPC over stdio (newline-delimited)
+// ---------------------------------------------------------------------------
+
+function reply(id, result) {
+  process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, result }) + "\n");
+}
+
+function replyError(id, code, message) {
+  const payload = { jsonrpc: "2.0", id, error: { code, message } };
+  process.stdout.write(JSON.stringify(payload) + "\n");
+}
+
+function handleMessage(msg) {
+  if (!msg || msg.jsonrpc !== "2.0" || typeof msg.method !== "string") return;
+  const id = msg.id;
+  try {
+    switch (msg.method) {
+      case "initialize": {
+        const asked = msg.params && msg.params.protocolVersion;
+        const version = KNOWN_PROTOCOL_VERSIONS.has(asked) ? asked : "2024-11-05";
+        if (id === undefined) return;
+        reply(id, {
+          protocolVersion: version,
+          capabilities: { tools: {} },
+          serverInfo: { name: "agentboard", version: SERVER_VERSION },
+        });
+        return;
+      }
+      case "ping": {
+        if (id === undefined) return;
+        reply(id, {});
+        return;
+      }
+      case "tools/list": {
+        if (id === undefined) return;
+        reply(id, { tools: TOOLS });
+        return;
+      }
+      case "tools/call": {
+        if (id === undefined) return;
+        const p = msg.params || {};
+        try {
+          reply(id, callTool(p.name, p.arguments));
+        } catch (e) {
+          reply(id, { content: [{ type: "text", text: `error: ${e && e.message ? e.message : String(e)}` }], isError: true });
+        }
+        return;
+      }
+      default: {
+        // notifications (no id) are acked by silence; unknown requests get an error
+        if (id === undefined) return;
+        replyError(id, -32601, `method not found: ${msg.method}`);
+      }
+    }
+  } catch (e) {
+    if (id !== undefined) replyError(id, -32603, String((e && e.message) || e));
+  }
+}
+
+const rl = readline.createInterface({ input: process.stdin, terminal: false });
+rl.on("line", (line) => {
+  if (!line.trim()) return;
+  let msg = null;
+  try {
+    msg = JSON.parse(line);
+  } catch {
+    return; // ignore malformed lines on stdio
+  }
+  handleMessage(msg);
+});