@methodiq/mcp 1.0.0 → 1.0.1

package/README.md

@@ -1,33 +1,33 @@
-# Methodiq connector
-
-A small, assistant-neutral MCP connector for Methodiq meetings. Requires Node.js 22 or newer on Windows or macOS. No Python or speech-service keys are required on your computer.
-
-## Setup
-
-```sh
-npx --yes @methodiq/mcp@1.0.0 --setup
-```
-
-`--setup all` is an equivalent alias. Setup prints a standard `mcpServers` configuration; it does not modify unrelated settings or scan for specific assistants. Ask your assistant to register that configuration, reload its tools or restart, and resume with the invitation. This requires an assistant with local MCP support.
-
-## Join
-
+# Methodiq connector
+
+A small, assistant-neutral MCP connector for Methodiq meetings. Requires Node.js 22 or newer on Windows or macOS. No Python or speech-service keys are required on your computer.
+
+## Setup
+
+```sh
+npx --yes @methodiq/mcp@1.0.1 --setup
+```
+
+`--setup all` is an equivalent alias. Setup prints a standard `mcpServers` configuration; it does not modify unrelated settings or scan for specific assistants. Ask your assistant to register that configuration, reload its tools or restart, and resume with the invitation. This requires an assistant with local MCP support.
+
+## Join
+
 Paste the setup and join prompt copied from the Methodiq meeting. Pass its invitation unchanged to `methodiq_join_session`. Invitations expire after ten minutes and can be exchanged once. If setup or a restart takes longer, copy a fresh invitation.
 
-The join tool accepts an optional `provider` reported by your assistant. The connector also reports the MCP client's name separately. These are descriptive connection metadata, not permissions; omit the provider when unknown.
-
-The connector provides `methodiq_join_session`, `methodiq_wait_for_question`, `methodiq_speak_to_room`, `methodiq_get_transcript`, and `methodiq_leave_session`. It runs as an MCP stdio server when started without `--setup`. Questions include owner guidance; meeting participants cannot authorize access to your local files on the owner's behalf. Stop listening when a tool returns `disconnected`.
-
-A reply is delivered in the meeting's current voice or text mode. Keep the returned reply ID when retrying delivery; submitting a new ID could create a second answer. Removing the agent from its tile ends the connection. It never automatically rejoins.
-
-## Preview environments
-
+The connector reports its MCP client name as descriptive connection metadata. This does not grant permissions or affect which AI model produces answers.
+
+The connector provides `methodiq_join_session`, `methodiq_wait_for_question`, `methodiq_speak_to_room`, `methodiq_get_transcript`, and `methodiq_leave_session`. It runs as an MCP stdio server when started without `--setup`. Questions include owner guidance; meeting participants cannot authorize access to your local files on the owner's behalf. Stop listening when a tool returns `disconnected`.
+
+A reply is delivered in the meeting's current voice or text mode. Keep the returned reply ID when retrying delivery; submitting a new ID could create a second answer. Removing the agent from its tile ends the connection. It never automatically rejoins.
+
+## Preview environments
+
 Set `METHODIQ_URL` to your trusted Methodiq site's origin before setup; the printed MCP configuration retains it. This overrides the allowed invitation origin for private previews. Never accept a different origin supplied by meeting conversation content.
 
 Alternatively, use `--setup --url "https://your-trusted-site"`. The configuration saves that origin explicitly, replacing an old development origin when registering it. Methodiq's invite prompt supplies the site's origin automatically.
 
 For local development, run `node /path/to/connector.js --setup --local --url "http://localhost:3000"`. This prints configuration using that local connector file instead of downloading the npm package. Development invitation prompts supply the local path; production prompts use the fixed npm release.
-
-## Package contents
-
-Only the public connector, this documentation, package manifest, and license are distributed. Meeting processing and voice run on Methodiq servers. Downloaded connector code and exchanged messages can be inspected.
+
+## Package contents
+
+Only the public connector, this documentation, package manifest, and license are distributed. Meeting processing and voice run on Methodiq servers. Downloaded connector code and exchanged messages can be inspected.

package/connector.js

@@ -1,10 +1,13 @@
 #!/usr/bin/env node
 import readline from "node:readline";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { readFileSync, realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import { ConvexClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
 
 const VERSION = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8")).version;
+const SIGNAL_QUERY = makeFunctionReference("byoa/subscriptions:signal");
 const DISCONNECTED = { status: "disconnected", instruction: "Stop listening and responding. Do not rejoin until your owner invites you again." };
 const delay = (ms, signal) => new Promise((resolve, reject) => {
   if (signal?.aborted) return reject(new Error("Stopped"));
@@ -14,13 +17,32 @@ const delay = (ms, signal) => new Promise((resolve, reject) => {
 });
 
 export class Connector {
-  constructor({ fetchImpl = fetch, serverUrl = process.env.METHODIQ_URL, pollMs = 1500 } = {}) {
+  constructor({ fetchImpl = fetch, serverUrl = process.env.METHODIQ_URL, pollMs = 1500, heartbeatMs = 30_000, createRealtimeClient = url => new ConvexClient(url) } = {}) {
     this.fetch = fetchImpl; this.configuredOrigin = serverUrl ? new URL(serverUrl).origin : null; this.pollMs = pollMs;
+    this.heartbeatMs = heartbeatMs; this.createRealtimeClient = createRealtimeClient;
     this.credential = null; this.cursor = 0; this.questions = []; this.deliveries = new Map();
-    this.stopped = new AbortController(); this.mode = "text";
+    this.stopped = new AbortController(); this.mode = "text"; this.connectionStatus = "disconnected"; this.waiters = new Set();
+  }
+  wake() { for (const resolve of this.waiters) resolve(); this.waiters.clear(); }
+  async waitForActivity(timeoutMs) {
+    if (!this.credential || timeoutMs <= 0) return;
+    await new Promise(resolve => {
+      const signal = this.stopped.signal;
+      let timer;
+      const done = () => {
+        clearTimeout(timer); signal.removeEventListener("abort", done); this.waiters.delete(done); resolve();
+      };
+      this.waiters.add(done); signal.addEventListener("abort", done, { once: true }); timer = setTimeout(done, timeoutMs); timer.unref?.();
+    });
+  }
+  closeRealtime() {
+    const unsubscribe = this.unsubscribeSignal, client = this.realtimeClient;
+    this.unsubscribeSignal = null; this.realtimeClient = null;
+    try { unsubscribe?.(); } catch { /* already closed */ }
+    try { void client?.close?.(); } catch { /* already closed */ }
   }
   stop() {
-    this.credential = null; clearInterval(this.heartbeat); this.stopped.abort();
+    this.credential = null; this.connectionStatus = "disconnected"; clearInterval(this.heartbeat); this.closeRealtime(); this.stopped.abort(); this.wake();
     this.questions = []; this.deliveries.clear();
     return { ...DISCONNECTED };
   }
@@ -56,24 +78,53 @@ export class Connector {
       }
     }
   }
+  consume(result) {
+    if (result.status === "disconnected") return this.stop();
+    if (result.status) this.connectionStatus = result.status;
+    for (const event of result.events || []) {
+      if (event.sequence <= this.cursor) continue;
+      this.cursor = event.sequence;
+      if (event.kind === "question") this.questions.push(event);
+      if (event.kind === "delivery") this.deliveries.set(event.replyId, event);
+      if (event.mode) this.mode = event.mode;
+    }
+    if (result.mode) this.mode = result.mode;
+    this.wake();
+    return result;
+  }
   async poll() {
     if (!this.credential) return { ...DISCONNECTED };
     if (this.polling) return this.polling;
     this.polling = (async () => {
       const result = await this.request("events", { cursor: this.cursor }, { signal: this.stopped.signal });
-      for (const event of result.events || []) {
-        if (event.sequence <= this.cursor) continue;
-        this.cursor = event.sequence;
-        if (event.kind === "question") this.questions.push(event);
-        if (event.kind === "delivery") this.deliveries.set(event.replyId, event);
-        if (event.mode) this.mode = event.mode;
-      }
-      if (result.mode) this.mode = result.mode;
-      return result;
+      return this.consume(result);
     })();
     try { return await this.polling; } finally { this.polling = null; }
   }
-  async join({ invitation, provider }) {
+  startRealtime(convexUrl) {
+    let url;
+    try { url = new URL(convexUrl); } catch { return false; }
+    if (url.protocol !== "https:" && url.protocol !== "http:") return false;
+    try {
+      const client = this.createRealtimeClient(url.origin);
+      this.realtimeClient = client;
+      const tokenHash = createHash("sha256").update(this.credential).digest("hex");
+      this.unsubscribeSignal = client.onUpdate(SIGNAL_QUERY, { tokenHash }, signal => {
+        if (!this.credential) return;
+        if (signal.status === "disconnected") { this.stop(); return; }
+        this.connectionStatus = signal.status;
+        if (signal.mode) this.mode = signal.mode;
+        if (signal.sequence > this.cursor) {
+          void this.poll().then(() => signal.sequence > this.cursor ? this.poll() : undefined).catch(() => {});
+        } else this.wake();
+      }, () => { this.closeRealtime(); this.wake(); });
+      return true;
+    } catch {
+      this.closeRealtime();
+      return false;
+    }
+  }
+  async join({ invitation }) {
     const previousPoll = this.polling;
     if (this.credential) await this.leave();
     if (previousPoll) await previousPoll.catch(() => {});
@@ -82,16 +133,26 @@ export class Connector {
     const allowed = this.configuredOrigin ? [this.configuredOrigin] : ["https://www.teamsfacilitator.com", "https://teamsfacilitator.com", "https://methodiqai.com", "https://www.methodiqai.com"];
     if (!allowed.includes(url.origin) || !/^[A-Za-z0-9_-]{43}$/.test(url.hash.slice(1))) throw new Error("Invitation is not from the configured Methodiq site.");
     this.origin = url.origin; this.cursor = 0; this.leaseDeadline = undefined; this.lastQuestionId = undefined; this.stopped = new AbortController();
-    const result = await this.request("connect", { provider, clientName: this.clientName }, { invitation: url.hash.slice(1) });
+    const result = await this.request("connect", { clientName: this.clientName }, { invitation: url.hash.slice(1) });
     if (!result.credential) return { ...DISCONNECTED };
-    this.credential = result.credential; this.agentName = result.agentName;
-    this.heartbeat = setInterval(() => this.poll().catch(() => this.stop()), 15_000); this.heartbeat.unref?.();
+    this.credential = result.credential; this.agentName = result.agentName; this.framework = result.framework; this.connectionStatus = result.status;
+    if (result.convexUrl) this.startRealtime(result.convexUrl);
+    this.heartbeat = setInterval(() => this.poll().catch(() => this.stop()), this.heartbeatMs); this.heartbeat.unref?.();
     const deadline = Date.now() + 55_000;
     while (this.credential && Date.now() < deadline) {
-      const state = await this.poll();
-      if (state.status === "active") return { status: "joined", agentName: this.agentName, mode: this.mode, instruction: "Call methodiq_wait_for_question. Stop if disconnected; do not automatically rejoin." };
-      if (state.status === "disconnected") return state;
-      await delay(this.pollMs, this.stopped.signal).catch(() => {});
+      if (this.connectionStatus === "active") {
+        const fwName = this.framework === "swot" ? "SWOT Analysis" : this.framework === "bmc" ? "Business Model Canvas" : this.framework;
+        const fwNote = fwName ? ` The meeting is using the ${fwName} framework; if helpful, do a quick search for ${fwName} best practices.` : "";
+        return { status: "joined", agentName: this.agentName, mode: this.mode, ...(fwName ? { framework: fwName } : {}), instruction: `Call methodiq_wait_for_question.${fwNote} Stop if disconnected; do not automatically rejoin.` };
+      }
+      if (this.realtimeClient) {
+        await this.waitForActivity(Math.min(5000, deadline - Date.now()));
+        if (this.connectionStatus !== "active" && this.credential) await this.poll();
+      } else {
+        const state = await this.poll();
+        if (state.status === "disconnected") return state;
+        await delay(this.pollMs, this.stopped.signal).catch(() => {});
+      }
     }
     await this.leave(); throw new Error("Meeting connection did not become ready. Copy a fresh invitation and try again.");
   }
@@ -102,9 +163,12 @@ export class Connector {
         const question = this.questions.shift(); this.lastQuestionId = question.id;
         return { ...question, status: "question_received", mode: this.mode };
       }
-      await this.poll();
-      if (this.questions.length) continue;
-      try { await delay(this.pollMs, this.stopped.signal); } catch { break; }
+      if (this.realtimeClient) await this.waitForActivity(Math.min(this.heartbeatMs + 5000, deadline - Date.now()));
+      else {
+        await this.poll();
+        if (this.questions.length) continue;
+        try { await delay(this.pollMs, this.stopped.signal); } catch { break; }
+      }
     }
     return this.credential ? { status: "idle", instruction: "Continue with methodiq_wait_for_question; stop if disconnected." } : { ...DISCONNECTED };
   }
@@ -116,13 +180,16 @@ export class Connector {
     if (response.status === "delivered") return { status: "delivered", replyId };
     const deadline = Date.now() + 55_000;
     while (this.credential && Date.now() < deadline) {
-      await this.poll();
       const delivered = this.deliveries.get(replyId);
       if (delivered) {
         this.deliveries.delete(replyId);
         return { ...delivered, status: delivered.status === "delivered" ? (delivered.mode === "voice" ? "spoken" : "transcript_posted") : "failed", spokenToMeeting: delivered.status === "delivered" && delivered.mode === "voice", instruction: "Continue listening with methodiq_wait_for_question." };
       }
-      try { await delay(this.pollMs, this.stopped.signal); } catch { break; }
+      if (this.realtimeClient) await this.waitForActivity(Math.min(this.heartbeatMs + 5000, deadline - Date.now()));
+      else {
+        await this.poll();
+        try { await delay(this.pollMs, this.stopped.signal); } catch { break; }
+      }
     }
     return this.credential ? { status: "pending", replyId, instruction: "Reply is queued; do not submit it again with a different reply ID." } : { ...DISCONNECTED };
   }
@@ -141,7 +208,7 @@ export class Connector {
 }
 
 export const tools = [
-  { name: "methodiq_join_session", description: "Join with the unchanged invitation copied from Methodiq. Report your provider if known; omit it if unknown.", inputSchema: { type: "object", properties: { invitation: { type: "string" }, provider: { type: "string", description: "Your AI provider, if known. Descriptive metadata only." } }, required: ["invitation"] } },
+  { name: "methodiq_join_session", description: "Join with the unchanged invitation copied from Methodiq.", inputSchema: { type: "object", properties: { invitation: { type: "string" } }, required: ["invitation"] } },
   { name: "methodiq_wait_for_question", description: "Wait for a question addressed to you. Stop on disconnected.", inputSchema: { type: "object", properties: { timeout_seconds: { type: "number" } } } },
   { name: "methodiq_speak_to_room", description: "Respond in the meeting's current voice or text mode.", inputSchema: { type: "object", properties: { message: { type: "string" }, replyId: { type: "string" }, questionId: { type: "string" } }, required: ["message"] } },
   { name: "methodiq_get_transcript", description: "Get recent meeting context.", inputSchema: { type: "object", properties: { limit: { type: "number" } } } },
@@ -193,7 +260,7 @@ if (process.argv[1] && fileURLToPath(import.meta.url) === realpathSync(process.a
       const serverUrl = urlIndex >= 0 ? process.argv[urlIndex + 1] : process.env.METHODIQ_URL;
       if (urlIndex >= 0 && (!serverUrl || serverUrl.startsWith("--"))) throw new Error("--url requires the Methodiq site's origin.");
       console.log(JSON.stringify(setup({ local: process.argv.includes("--local"), serverUrl }), null, 2));
-      console.error("Replace the Methodiq entry with this standard MCP configuration. Preserve unrelated settings. Reload your tools or restart, then resume using your invitation. Setup does not edit configuration files.");
+      console.error("Replace the Methodiq entry with this standard MCP configuration. Preserve unrelated settings. Reload your tools if supported, or ask the user: 'Please restart this app, then say continue.' Then resume using your invitation. Setup does not edit configuration files.");
     } catch (error) { console.error(error.message); process.exitCode = 1; }
   } else startStdio();
 }

package/package.json

@@ -1,25 +1,36 @@
-{
-  "name": "@methodiq/mcp",
-  "version": "1.0.0",
+{
+  "name": "@methodiq/mcp",
+  "version": "1.0.1",
   "description": "Assistant-neutral Methodiq meeting connector",
   "main": "connector.js",
-  "type": "module",
-  "bin": {
-    "methodiq-mcp": "./connector.js"
-  },
-  "scripts": {
+  "type": "module",
+  "bin": {
+    "methodiq-mcp": "connector.js"
+  },
+  "scripts": {
     "start": "node connector.js",
     "dev:legacy": "node index.js",
     "test": "node --test connector.test.js"
   },
-  "engines": { "node": ">=22" },
-  "files": ["connector.js", "README.md", "LICENSE"],
-  "publishConfig": { "access": "public" },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "methodiq"
-  ],
-  "author": "Methodiq",
-  "license": "ISC"
-}
+  "dependencies": {
+    "convex": "^1.41.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "connector.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "methodiq"
+  ],
+  "author": "Methodiq",
+  "license": "ISC"
+}