@markmnl/fmsg-mcp 0.1.0

package/dist/wait.js

@@ -0,0 +1,210 @@
+import { compareMessageIds, maxMessageId } from "./client/message-id.js";
+import { openFmsgWebSocket, parseWsEvent } from "./client/ws.js";
+/**
+ * Block until the next qualifying inbound message (plus any that arrive on the
+ * same thread within the settle window), or until the deadline.
+ */
+export async function waitForMessage(client, self, options, signal, deps = {}) {
+    const start = Date.now();
+    const deadline = start + options.timeoutMs;
+    const maxBatch = options.maxBatch ?? 20;
+    const pollIntervalMs = options.pollIntervalMs ?? 2000;
+    const me = self.toLowerCase();
+    const wantFrom = options.from?.toLowerCase();
+    // Floor: the newest inbox id at call time unless the caller supplied a cursor.
+    let floor = options.afterId;
+    if (floor === undefined) {
+        const [newest] = await client.listInbox(1, 0, signal);
+        floor = newest?.id ?? "0";
+    }
+    let skippedMax = floor;
+    const rootCache = new Map();
+    const rootOf = async (id) => {
+        if (rootCache.has(id))
+            return rootCache.get(id);
+        let root = null;
+        try {
+            root = (await client.getThreadMessages(id, signal)).root_id;
+        }
+        catch {
+            // Fall back to a bounded pid walk.
+            try {
+                let cur = id;
+                for (let i = 0; i < 100; i++) {
+                    const m = await client.getMessage(cur, signal);
+                    if (!m.pid) {
+                        root = m.id;
+                        break;
+                    }
+                    cur = m.pid;
+                }
+            }
+            catch {
+                root = null;
+            }
+        }
+        rootCache.set(id, root);
+        return root;
+    };
+    const targetRoot = options.threadOf ? await rootOf(options.threadOf) : undefined;
+    if (options.threadOf && targetRoot === null)
+        throw new Error(`could not determine the thread of message ${options.threadOf}`);
+    const seen = new Set();
+    const batch = [];
+    const pending = [];
+    let batchRoot = null;
+    let transport = "websocket";
+    let note = null;
+    let socket;
+    let pollTimer;
+    let settleTimer;
+    let finished = false;
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            finished = true;
+            clearTimeout(deadlineTimer);
+            clearTimeout(settleTimer);
+            clearInterval(pollTimer);
+            clearInterval(tickTimer);
+            signal?.removeEventListener("abort", onAbort);
+            if (socket) {
+                socket.removeAllListeners();
+                try {
+                    socket.close();
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        };
+        const finish = () => {
+            if (finished)
+                return;
+            cleanup();
+            const ids = batch.map((m) => m.id);
+            resolve({
+                status: batch.length ? "message" : "timeout",
+                after_id: batch.length ? maxMessageId(ids) : skippedMax,
+                thread_root_id: batchRoot,
+                messages: [...batch].sort((a, b) => compareMessageIds(a.id, b.id)),
+                pending_other_threads: pending,
+                transport,
+                note,
+            });
+        };
+        const fail = (error) => {
+            if (finished)
+                return;
+            cleanup();
+            reject(error);
+        };
+        const onAbort = () => {
+            note = "cancelled";
+            finish();
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted)
+            return onAbort();
+        const deadlineTimer = setTimeout(() => {
+            if (batch.length && settleTimer)
+                note = "the time limit cut the settle window short";
+            finish();
+        }, Math.max(0, deadline - Date.now()));
+        const tickTimer = setInterval(() => options.onTick?.(Date.now() - start), 20_000);
+        const consider = async (m) => {
+            if (finished || seen.has(m.id))
+                return;
+            seen.add(m.id);
+            if (compareMessageIds(m.id, floor) <= 0)
+                return;
+            const disqualified = m.from.toLowerCase() === me ||
+                (m.reaction !== null && m.reaction !== undefined) ||
+                m.no_reply === true ||
+                (wantFrom !== undefined && m.from.toLowerCase() !== wantFrom);
+            if (disqualified) {
+                if (compareMessageIds(m.id, skippedMax) > 0)
+                    skippedMax = m.id;
+                return;
+            }
+            const root = await rootOf(m.id);
+            if (finished)
+                return;
+            if (targetRoot !== undefined && root !== targetRoot) {
+                if (compareMessageIds(m.id, skippedMax) > 0)
+                    skippedMax = m.id;
+                return;
+            }
+            if (batch.length === 0) {
+                batchRoot = root;
+                batch.push(m);
+                const settle = Math.min(options.settleMs, Math.max(0, deadline - Date.now()));
+                settleTimer = setTimeout(finish, settle);
+                if (settle === 0)
+                    finish();
+                return;
+            }
+            if (root === batchRoot && batch.length < maxBatch) {
+                batch.push(m);
+                return;
+            }
+            pending.push({ id: m.id, from: m.from, root_id: root });
+        };
+        const catchUp = async () => {
+            try {
+                const page = await client.listInbox(100, 0, signal);
+                for (const m of [...page].reverse())
+                    await consider(m);
+            }
+            catch (error) {
+                if (!finished)
+                    fail(error);
+            }
+        };
+        const startPolling = (why) => {
+            if (finished || pollTimer)
+                return;
+            transport = "poll";
+            note = note ?? why;
+            pollTimer = setInterval(() => void catchUp(), pollIntervalMs);
+            void catchUp();
+        };
+        const open = deps.openSocket ?? openFmsgWebSocket;
+        open(client)
+            .then((ws) => {
+            if (finished) {
+                ws.close();
+                return;
+            }
+            socket = ws;
+            const openTimer = setTimeout(() => {
+                if (ws.readyState !== ws.OPEN) {
+                    ws.removeAllListeners();
+                    ws.terminate();
+                    socket = undefined;
+                    startPolling("WebSocket did not open; polling instead");
+                }
+            }, options.wsOpenTimeoutMs ?? 10_000);
+            ws.on("open", () => {
+                clearTimeout(openTimer);
+                void catchUp();
+            });
+            ws.on("message", (raw) => {
+                const event = parseWsEvent(raw);
+                if (event?.type === "new_msg" && event.data)
+                    void consider(event.data);
+            });
+            ws.on("error", () => {
+                clearTimeout(openTimer);
+                socket = undefined;
+                startPolling("WebSocket failed; polling instead");
+            });
+            ws.on("close", () => {
+                clearTimeout(openTimer);
+                socket = undefined;
+                if (!finished)
+                    startPolling("WebSocket closed; polling instead");
+            });
+        })
+            .catch(() => startPolling("WebSocket unavailable; polling instead"));
+    });
+}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@markmnl/fmsg-mcp",
+  "mcpName": "io.github.markmnl/fmsg-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for fmsg: send and receive federated messages from any AI agent via a deployed fmsg Web API",
+  "type": "module",
+  "license": "MIT",
+  "author": "Mark Mennell",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/markmnl/fmsg-mcp.git"
+  },
+  "homepage": "https://github.com/markmnl/fmsg-mcp#readme",
+  "bugs": "https://github.com/markmnl/fmsg-mcp/issues",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "fmsg",
+    "federated-messaging",
+    "agent"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "fmsg-mcp": "dist/index.js"
+  },
+  "main": "./dist/public.js",
+  "types": "./dist/public.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/public.d.ts",
+      "default": "./dist/public.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "LICENSE",
+    "server.json"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:e2e": "FMSG_E2E=1 vitest run test/fmsg-docker.e2e.test.ts",
+    "start": "node dist/index.js",
+    "start:http": "node dist/index.js --http",
+    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js",
+    "prepack": "npm run clean && npm run build && npm test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
+    "ws": "^8.21.3",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "^2.0.0",
+    "@types/node": "^24.13.3",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.7"
+  }
+}

package/server.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.markmnl/fmsg-mcp",
+  "description": "Send and receive fmsg federated messages from any AI agent via a deployed fmsg Web API",
+  "repository": {
+    "url": "https://github.com/markmnl/fmsg-mcp",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@markmnl/fmsg-mcp",
+      "version": "0.1.0",
+      "transport": { "type": "stdio" },
+      "environmentVariables": [
+        { "name": "FMSG_API_URL", "description": "Base URL of the fmsg Web API", "isRequired": true },
+        { "name": "FMSG_API_KEY", "description": "fmsg API key (fmsgk_...) for the address to send as", "isRequired": true, "isSecret": true },
+        { "name": "FMSG_DEFAULT_DOMAIN", "description": "Optional: lets short names resolve to @name@<domain>", "isRequired": false }
+      ]
+    }
+  ]
+}