@macula-io/mcp 0.4.1 → 0.5.0

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.1",
+  "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"