@macula-io/mcp 0.4.0 → 0.5.0

package/dist/presence.js

@@ -0,0 +1,217 @@
+// Presence: this macula-mcp process's own "being on the mesh" state --
+// a periodic agent.hello heartbeat, and durable subscriptions to
+// agent.hello/agent.goodbye from everyone else, feeding the local
+// roster (roster.ts). mesh_hello.ts/mesh_goodbye.ts/mesh_agents.ts are
+// thin tool wrappers around start()/stop()/roster reads; this module
+// owns the actual lifecycle.
+//
+// mesh_watch.ts's own doc comment explains why a standing subscription
+// was deliberately NOT built before: macula-cli had no daemon, so
+// "macula-mcp itself becoming a stateful daemon" was a real fork not
+// taken. macula-cli has a real daemon now (serve/call/pubsub over a
+// persistent connection, see its own README's Daemon mode section) --
+// this module is macula-mcp finally taking that fork, scoped narrowly
+// to what presence needs: one internally-managed macula-cli daemon,
+// used ONLY to hold two durable subscriptions alive. The periodic
+// PUBLISH side does NOT need it -- macula-cli's daemon protocol has no
+// publish-via-daemon method (only call/serve/subscribe), so each
+// heartbeat is an ordinary one-shot `pubsub publish`, exactly like
+// mesh_publish already does.
+import { randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { binPath, defaultStation, identity, onShutdown, parseWatchLine, presenceIdentityPath, publish, MaculaCliError, } from "./macula_cli.js";
+import { removeAgent, upsertAgent } from "./roster.js";
+export const HELLO_TOPIC = "agent.hello";
+export const GOODBYE_TOPIC = "agent.goodbye";
+const DEFAULT_INTERVAL_SECONDS = 60;
+/** Never let a misconfigured caller hammer a shared demo station. */
+const MIN_INTERVAL_SECONDS = 10;
+let state;
+export function isActive() {
+    return state !== undefined;
+}
+/** Idempotent: a second call just updates operatorName/message for future heartbeats. */
+export async function start(args) {
+    const host = args.host ?? defaultStation();
+    const intervalSeconds = Math.max(MIN_INTERVAL_SECONDS, args.intervalSeconds ?? DEFAULT_INTERVAL_SECONDS);
+    if (state) {
+        state.operatorName = args.operatorName ?? state.operatorName;
+        state.message = args.message ?? state.message;
+        return {
+            node_id: state.nodeId,
+            connected_to: state.host,
+            interval_seconds: intervalSeconds,
+            already_active: true,
+        };
+    }
+    const { node_id: nodeId } = await identity();
+    const socketName = `presence-${process.pid}-${randomBytes(4).toString("hex")}`;
+    const daemon = await startDaemon(host, socketName);
+    const watchers = [
+        watchTopic(socketName, HELLO_TOPIC, (evt) => {
+            const payload = evt;
+            const seenNodeId = typeof payload.node_id === "string" ? payload.node_id : undefined;
+            if (!seenNodeId)
+                return;
+            upsertAgent({
+                node_id: seenNodeId,
+                operator_name: typeof payload.operator_name === "string" ? payload.operator_name : undefined,
+                message: typeof payload.message === "string" ? payload.message : undefined,
+                at: new Date().toISOString(),
+            });
+        }),
+        watchTopic(socketName, GOODBYE_TOPIC, (evt) => {
+            const payload = evt;
+            if (typeof payload.node_id === "string")
+                removeAgent(payload.node_id);
+        }),
+    ];
+    const heartbeatTimer = setInterval(() => void beat(), intervalSeconds * 1000);
+    heartbeatTimer.unref(); // a pending heartbeat alone shouldn't keep the process alive
+    state = { nodeId, operatorName: args.operatorName, message: args.message, host, socketName, daemon, watchers, heartbeatTimer };
+    onShutdown(stopSync);
+    await beat(); // announce immediately rather than waiting a full interval
+    return { node_id: nodeId, connected_to: host, interval_seconds: intervalSeconds, already_active: false };
+}
+async function beat() {
+    if (!state)
+        return;
+    await publish({
+        host: state.host,
+        topic: HELLO_TOPIC,
+        fact: {
+            node_id: state.nodeId,
+            ...(state.operatorName ? { operator_name: state.operatorName } : {}),
+            ...(state.message ? { message: state.message } : {}),
+            at: new Date().toISOString(),
+        },
+    });
+}
+/** Publishes agent.goodbye, then tears everything down. No-op if not active. */
+export async function stop() {
+    if (!state)
+        return { said_goodbye: false };
+    const { nodeId, host } = state;
+    let saidGoodbye = false;
+    try {
+        await publish({ host, topic: GOODBYE_TOPIC, fact: { node_id: nodeId, at: new Date().toISOString() } });
+        saidGoodbye = true;
+    }
+    catch {
+        // best effort -- still tear down locally even if the mesh is unreachable
+    }
+    stopSync();
+    return { said_goodbye: saidGoodbye };
+}
+/**
+ * Synchronous teardown only (kill child processes, clear the timer) --
+ * this is what onShutdown registers, since a SIGINT/SIGTERM handler
+ * cannot reliably wait on the async goodbye-publish above. The
+ * explicit stop() (mesh_goodbye) is the reliable way to leave
+ * gracefully; an abrupt process kill just stops heartbeating, and
+ * everyone else's roster ages this node out on its own via
+ * last_seen_at once the ordinary heartbeat stops arriving.
+ */
+function stopSync() {
+    if (!state)
+        return;
+    clearInterval(state.heartbeatTimer);
+    state.daemon.kill();
+    for (const w of state.watchers)
+        w.kill();
+    state = undefined;
+}
+function startDaemon(host, socketName) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(binPath(), [
+            "daemon",
+            "start",
+            "--json",
+            "--identity",
+            presenceIdentityPath(),
+            "-socket-name",
+            socketName,
+            host,
+        ]);
+        // daemon start --json pretty-prints its readiness envelope across
+        // multiple lines (report.emit's indented encoder -- the SAME shape
+        // every other one-shot --json command uses, unlike pubsub watch's
+        // deliberately single-line-per-event NDJSON). So this can't look
+        // for a first newline the way watchTopic does; it has to keep
+        // accumulating and re-attempt a parse of the WHOLE buffer until one
+        // succeeds, since there's no framing signal cheaper than "is this
+        // valid JSON yet" for a pretty-printed value of unknown length.
+        let buf = "";
+        let settled = false;
+        const onData = (chunk) => {
+            buf += chunk.toString("utf8");
+            let parsed;
+            try {
+                parsed = JSON.parse(buf.trim());
+            }
+            catch {
+                return; // not a complete JSON value yet -- wait for more chunks
+            }
+            child.stdout.off("data", onData);
+            settled = true;
+            if (parsed.ok) {
+                child.unref(); // see watchTopic's own comment on why
+                resolve(child);
+            }
+            else {
+                reject(new MaculaCliError(parsed.error?.message ?? "daemon start failed"));
+            }
+        };
+        child.stdout.on("data", onData);
+        child.on("error", (e) => {
+            if (!settled) {
+                settled = true;
+                reject(e);
+            }
+        });
+        child.on("exit", (code) => {
+            if (!settled) {
+                settled = true;
+                reject(new MaculaCliError(`daemon start exited before announcing readiness (code ${code})`));
+            }
+        });
+    });
+}
+function watchTopic(socketName, topic, onEvent) {
+    const child = spawn(binPath(), [
+        "pubsub",
+        "watch",
+        "-daemon",
+        "--json",
+        "-socket-name",
+        socketName,
+        topic,
+    ]);
+    // A held-open child process is ref'd by default and would keep this
+    // MCP server's Node process alive on its own even after the MCP
+    // client disconnects and there's nothing else left to do -- unref so
+    // presence is background infrastructure, not a reason to stay up.
+    // onShutdown's stopSync() still explicitly kills it either way.
+    child.unref();
+    let buf = "";
+    child.stdout.on("data", (chunk) => {
+        buf += chunk.toString("utf8");
+        let nl;
+        while ((nl = buf.indexOf("\n")) !== -1) {
+            const line = buf.slice(0, nl);
+            buf = buf.slice(nl + 1);
+            try {
+                const evt = parseWatchLine(line);
+                if (evt)
+                    onEvent(evt.payload);
+            }
+            catch {
+                // a trailing failure envelope on this line -- the connection is
+                // presumably gone; nothing more will arrive on it, so just stop
+                // trying to parse further lines from this child.
+            }
+        }
+    });
+    return child;
+}
+//# sourceMappingURL=presence.js.map

package/dist/presence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presence.js","sourceRoot":"","sources":["../src/presence.ts"],"names":[],"mappings":"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"}

package/dist/roster.d.ts

@@ -0,0 +1,26 @@
+export interface AgentRecord {
+    node_id: string;
+    operator_name: string | null;
+    message: string | null;
+    first_seen_at: string;
+    last_seen_at: string;
+}
+/** Records (or refreshes) one agent.hello sighting. Idempotent per node_id. */
+export declare function upsertAgent(rec: {
+    node_id: string;
+    operator_name?: string;
+    message?: string;
+    at: string;
+}): void;
+/** Removes one agent immediately -- called on receiving its agent.goodbye. */
+export declare function removeAgent(nodeId: string): void;
+export interface RosterPage {
+    total: number;
+    agents: AgentRecord[];
+}
+/** Most-recently-seen first. page is 1-based. */
+export declare function listAgents(page: number, pageSize: number): RosterPage;
+/** Drops agents not seen in maxAgeSeconds -- lazy cleanup, not a background timer. Returns rows removed. */
+export declare function pruneStale(maxAgeSeconds: number): number;
+/** Test/shutdown hook -- releases the file handle. Re-opens lazily on next use. */
+export declare function closeRoster(): void;

package/dist/roster.js

@@ -0,0 +1,93 @@
+// A local, persistent cache of "who else is on the mesh" -- built
+// entirely from consuming agent.hello/agent.goodbye facts, the same
+// shape as a QRY-department read model built from events elsewhere in
+// this codebase family: not an event store, just a projection over
+// what's been observed, disposable and rebuildable from the mesh at
+// any time (a fresh macula-mcp process starts with an empty roster and
+// repopulates it from whoever's still heartbeating).
+//
+// SQLite over an in-memory Map deliberately: a Map dies with the
+// process, and "who's on the mesh" is more useful if a restart doesn't
+// forget everyone seen minutes ago. SQLite over PouchDB: PouchDB's
+// whole value is offline-first sync/replication with conflict
+// resolution across replicas -- nothing here replicates anywhere, it's
+// one process's own local cache, and pulling in PouchDB's dependency
+// weight for a single-writer key-value table would be solving a
+// problem this doesn't have.
+//
+// better-sqlite3 is pinned to the 12.x line, NOT latest (13.x)
+// deliberately: 13.0.3 requires Node >=22 and segfaults outright under
+// this project's own CI-tested Node 20 (confirmed live -- exit 139,
+// reproduced locally under Node 20 via asdf before landing the fix,
+// npm only warns on the engine mismatch rather than failing the
+// install, so this is silent until something actually touches the
+// native binding). 12.11.1 explicitly declares support for 20.x --
+// don't bump past the 12.x line without first confirming the new
+// version's own declared `engines` covers Node 20, not just running
+// `npm test` on whatever Node happens to be on the developer's PATH.
+import Database from "better-sqlite3";
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+function dbPath() {
+    return process.env.MACULA_MCP_ROSTER_DB ?? join(homedir(), ".macula-mcp", "roster.sqlite3");
+}
+let db;
+function open() {
+    if (db)
+        return db;
+    const path = dbPath();
+    mkdirSync(dirname(path), { recursive: true });
+    db = new Database(path);
+    db.pragma("journal_mode = WAL");
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS agents (
+      node_id TEXT PRIMARY KEY,
+      operator_name TEXT,
+      message TEXT,
+      first_seen_at TEXT NOT NULL,
+      last_seen_at TEXT NOT NULL
+    )
+  `);
+    return db;
+}
+/** Records (or refreshes) one agent.hello sighting. Idempotent per node_id. */
+export function upsertAgent(rec) {
+    open()
+        .prepare(`INSERT INTO agents (node_id, operator_name, message, first_seen_at, last_seen_at)
+       VALUES (@node_id, @operator_name, @message, @at, @at)
+       ON CONFLICT(node_id) DO UPDATE SET
+         operator_name = excluded.operator_name,
+         message = excluded.message,
+         last_seen_at = excluded.last_seen_at`)
+        .run({
+        node_id: rec.node_id,
+        operator_name: rec.operator_name ?? null,
+        message: rec.message ?? null,
+        at: rec.at,
+    });
+}
+/** Removes one agent immediately -- called on receiving its agent.goodbye. */
+export function removeAgent(nodeId) {
+    open().prepare("DELETE FROM agents WHERE node_id = ?").run(nodeId);
+}
+/** Most-recently-seen first. page is 1-based. */
+export function listAgents(page, pageSize) {
+    const d = open();
+    const total = d.prepare("SELECT COUNT(*) AS n FROM agents").get().n;
+    const agents = d
+        .prepare("SELECT * FROM agents ORDER BY last_seen_at DESC LIMIT ? OFFSET ?")
+        .all(pageSize, (Math.max(1, page) - 1) * pageSize);
+    return { total, agents };
+}
+/** Drops agents not seen in maxAgeSeconds -- lazy cleanup, not a background timer. Returns rows removed. */
+export function pruneStale(maxAgeSeconds) {
+    const cutoff = new Date(Date.now() - maxAgeSeconds * 1000).toISOString();
+    return open().prepare("DELETE FROM agents WHERE last_seen_at < ?").run(cutoff).changes;
+}
+/** Test/shutdown hook -- releases the file handle. Re-opens lazily on next use. */
+export function closeRoster() {
+    db?.close();
+    db = undefined;
+}
+//# sourceMappingURL=roster.js.map

package/dist/roster.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roster.js","sourceRoot":"","sources":["../src/roster.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@macula-io/mcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Model Context Protocol server that exposes the Macula mesh to any agent harness, via macula-cli",
   "license": "Apache-2.0",
   "type": "module",
@@ -43,9 +43,11 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "better-sqlite3": "^12.11.1",
     "zod": "^3.23.0"
   },
   "devDependencies": {
+    "@types/better-sqlite3": "^9.6.0",
     "@types/node": "^20.0.0",
     "typescript": "^5.4.0",
     "vitest": "^1.0.0"