@methodiq/mcp 1.0.1 → 1.1.0

package/LICENSE

@@ -1,15 +1,15 @@
-ISC License
-
-Copyright (c) Methodiq
-
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted, provided that the above
-copyright notice and this permission notice appear in all copies.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
-WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
-ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
-ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
-OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ISC License
+
+Copyright (c) Methodiq
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,18 +1,20 @@
-# Methodiq connector
+# Teams Facilitator 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.
+An optional, assistant-neutral MCP connector for Teams Facilitator meetings. Agents that can run commands on your computer can join without it: the invitation prompt copied from Teams Facilitator connects them with plain web requests. Installing the connector gives MCP-capable assistants native tools and usually fewer permission prompts.
+
+Requires Node.js 22 or newer on Windows or macOS. It has no dependencies, and no Python or speech-service keys are required on your computer.
 
 ## Setup
 
 ```sh
-npx --yes @methodiq/mcp@1.0.1 --setup
+npx --yes @methodiq/mcp@1.1.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
 
-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.
+Paste the prompt copied from the Teams Facilitator 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 connector reports its MCP client name as descriptive connection metadata. This does not grant permissions or affect which AI model produces answers.
 
@@ -20,14 +22,27 @@ The connector provides `methodiq_join_session`, `methodiq_wait_for_question`, `m
 
 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.
 
+## How it connects
+
+The connector uses the same website endpoints as agents without it: `/api/byoa/{join,listen,say,transcript,leave}`. Teams Facilitator holds each listen request open until a question arrives and keeps track of which questions were delivered, so waiting does not repeatedly poll. Version 1.1.0 requires a Teams Facilitator site that provides these endpoints; earlier 1.0.x versions keep working with the older connector endpoints.
+
 ## 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.
+Set `METHODIQ_URL` to your trusted Teams Facilitator 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.
+
+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.
 
-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.
+## Legacy logging
 
-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.
+The legacy local WebRTC runner (`index.js` and `bridge.py`, used by older
+integrations) logs warnings, errors and bridge lifecycle events to stderr.
+Set `METHODIQ_LOG_LEVEL=DEBUG` to enable its routine diagnostics. It no longer
+writes `bob_debug.log` or `bridge_debug.log`; diagnostic messages omit tool
+arguments and conversation content. This setting does not affect the current
+HTTP connector (`connector.js`).
 
 ## 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.
+Only the public connector, this documentation, package manifest, and license are distributed. Meeting processing and voice run on Teams Facilitator servers. Downloaded connector code and exchanged messages can be inspected.

package/connector.js

@@ -1,266 +1,478 @@
 #!/usr/bin/env node
 import readline from "node:readline";
-import { createHash, randomUUID } from "node:crypto";
+import { createHash, randomBytes } 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"));
-  const stop = () => { clearTimeout(timer); signal?.removeEventListener("abort", stop); reject(new Error("Stopped")); };
-  const timer = setTimeout(() => { signal?.removeEventListener("abort", stop); resolve(); }, ms);
-  signal?.addEventListener("abort", stop, { once: true });
-});
+const VERSION = JSON.parse(
+  readFileSync(new URL("./package.json", import.meta.url), "utf8"),
+).version;
+const DISCONNECTED = {
+  status: "disconnected",
+  instruction:
+    "Stop listening and responding. Do not rejoin until your owner invites you again.",
+};
+const DEFAULT_ORIGINS = [
+  "https://www.teamsfacilitator.com",
+  "https://teamsfacilitator.com",
+  "https://methodiqai.com",
+  "https://www.methodiqai.com",
+];
+// join and listen are held open by the server (up to ~50s), so they get a longer timeout.
+const LONG_OPERATIONS = new Set(["join", "listen"]);
+// The server's leases for this connection (packages/backend/convex/byoa/state.ts): a join
+// or idle listen keeps it two minutes, a handed-out question ten. Transient failures are
+// retried for as long as the server can still be holding the connection.
+const IDLE_LEASE_MS = 120_000;
+const ANSWER_LEASE_MS = 600_000;
+// An identical retry of an answer is delivered once; a different message is a new reply.
+const replyIdFor = (questionId, message) =>
+  createHash("sha256")
+    .update(`${questionId ?? ""}\n${String(message ?? "").trim()}`)
+    .digest("base64url")
+    .slice(0, 32);
+const FRAMEWORKS = { swot: "SWOT Analysis", bmc: "Business Model Canvas" };
+const INSTRUCTIONS =
+  "Teams Facilitator lets you take part in a live meeting as your owner's AI agent. Join with the invitation your owner gives you, then loop methodiq_wait_for_question and methodiq_speak_to_room until a tool returns disconnected. Anyone in the meeting may ask questions, but only your owner can authorize opening local files, searching code or running tasks: follow the instruction returned with each question.";
+const delay = (ms, signal) =>
+  new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(new Error("Stopped"));
+    const stop = () => {
+      clearTimeout(timer);
+      reject(new Error("Stopped"));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", stop);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", stop, { once: true });
+  });
 
+// A thin client of the website's agent endpoints (/api/byoa/{join,listen,say,transcript,leave}),
+// the same ones agents use without installing anything. The server holds each listen
+// open until a question arrives and keeps the cursor, so the connector keeps no queue.
 export class Connector {
-  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.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 */ }
+  constructor({
+    fetchImpl = fetch,
+    serverUrl = process.env.METHODIQ_URL,
+    retryMs = 500,
+  } = {}) {
+    this.fetch = fetchImpl;
+    this.configuredOrigin = serverUrl ? new URL(serverUrl).origin : null;
+    this.retryMs = retryMs;
+    this.credential = null;
+    this.leaveCredential = null;
+    this.leaseUntil = 0;
+    this.stopped = new AbortController();
+    this.mode = "text";
   }
   stop() {
-    this.credential = null; this.connectionStatus = "disconnected"; clearInterval(this.heartbeat); this.closeRealtime(); this.stopped.abort(); this.wake();
-    this.questions = []; this.deliveries.clear();
+    this.credential = null;
+    this.lastQuestionId = undefined;
+    this.stopped.abort();
     return { ...DISCONNECTED };
   }
-  async request(operation, body = {}, { invitation, signal, credential: suppliedCredential } = {}) {
-    const credential = invitation || suppliedCredential || this.credential;
-    if (!credential) return { ...DISCONNECTED };
-    const started = Date.now(); let backoff = 500;
-    const deadline = Math.min(started + 55_000, invitation || operation === "disconnect" ? Infinity : (this.leaseDeadline || started + 55_000));
+  // Mirrors how the server renews the lease. Timed from the response, which the server's
+  // renewal precedes, so the connector never gives up on a connection the server still holds.
+  renew(operation, result) {
+    const at = Date.now();
+    if (operation === "join") this.leaseUntil = at + IDLE_LEASE_MS;
+    // A connection that is still starting keeps its first lease.
+    else if (operation === "listen" && result.status !== "connecting")
+      this.leaseUntil =
+        at + (result.status === "question" ? ANSWER_LEASE_MS : IDLE_LEASE_MS);
+    else if (operation === "say")
+      this.leaseUntil = Math.max(this.leaseUntil, at + IDLE_LEASE_MS);
+  }
+  // Retries transient failures (network, 429, 5xx) until the lease would have lapsed, or
+  // for a join, until its exchanged connection would have; `until` stops sooner but keeps
+  // the connection. `once` requests are never replayed.
+  async request(
+    operation,
+    body = {},
+    { credential = this.credential, once = false, until = Infinity } = {},
+  ) {
+    if (operation !== "join" && !credential) return { ...DISCONNECTED };
+    const stopped = this.stopped.signal,
+      joinUntil = Date.now() + IDLE_LEASE_MS;
+    let backoff = this.retryMs;
     while (true) {
-      if (signal?.aborted) return { ...DISCONNECTED };
-      if (Date.now() >= deadline) return this.stop();
+      if (stopped.aborted && !once) return { ...DISCONNECTED };
+      let response;
       try {
-        const attemptedAt = Date.now();
-        const response = await this.fetch(`${this.origin}/api/byoa/${operation}`, {
-          method: "POST", redirect: "error", headers: { "Content-Type": "application/json", ...(invitation ? {} : { Authorization: `Bearer ${credential}` }) },
-          body: JSON.stringify(invitation ? { ...body, invitation } : body),
-          signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(Math.max(1, Math.min(8000, deadline - attemptedAt)))]) : AbortSignal.timeout(8000),
+        response = await this.fetch(`${this.origin}/api/byoa/${operation}`, {
+          method: "POST",
+          redirect: "error",
+          headers: {
+            "Content-Type": "application/json",
+            ...(operation === "join"
+              ? {}
+              : { Authorization: `Bearer ${credential}` }),
+          },
+          body: JSON.stringify(body),
+          signal: AbortSignal.any([
+            ...(once ? [] : [stopped]),
+            AbortSignal.timeout(
+              LONG_OPERATIONS.has(operation) ? 70_000 : 15_000,
+            ),
+          ]),
         });
-        if (response.status === 401 || response.status === 403) return this.stop();
-        if (response.status === 429 || response.status >= 500) throw new Error("Temporary connection failure");
-        if (!response.ok) throw Object.assign(new Error("Meeting request rejected. Copy a fresh invitation if joining."), { permanent: true });
-        const result = await response.json();
-        if (signal?.aborted) return { ...DISCONNECTED };
-        if (result.status === "disconnected") return this.stop();
-        if (operation === "events" || operation === "connect") this.leaseDeadline = attemptedAt + 60_000;
-        return result;
-      } catch (error) {
-        if (signal?.aborted) return { ...DISCONNECTED };
-        if (error.permanent || operation === "connect" || operation === "disconnect") throw error; // invitations are single-use; never blindly replay an exchange
-        if (Date.now() + backoff >= deadline) return this.stop();
-        try { await delay(backoff, signal); } catch { return { ...DISCONNECTED }; }
-        backoff = Math.min(5000, backoff * 2);
+      } catch {
+        if (stopped.aborted && !once) return { ...DISCONNECTED };
+        if (once) throw new Error("Could not reach Teams Facilitator.");
+      }
+      if (response) {
+        const result = await response.json().catch(() => ({}));
+        if (
+          response.status === 401 ||
+          response.status === 403 ||
+          result.status === "disconnected"
+        )
+          return operation === "leave" ? { ...DISCONNECTED } : this.stop();
+        if (response.ok) {
+          this.renew(operation, result);
+          return result;
+        }
+        if (once || (response.status !== 429 && response.status < 500))
+          throw new Error(
+            result.message ||
+              "Meeting request rejected. Copy a fresh invitation if joining.",
+          );
+      }
+      const retryAt = Date.now() + backoff;
+      if (operation === "join" && retryAt >= joinUntil)
+        throw new Error(
+          "Could not reach Teams Facilitator. Copy a fresh invitation and try again.",
+        );
+      if (operation !== "join" && retryAt >= this.leaseUntil)
+        return this.stop();
+      if (retryAt >= until) return { status: "unavailable" };
+      try {
+        await delay(backoff, stopped);
+      } catch {
+        return { ...DISCONNECTED };
       }
+      backoff = Math.min(5000, backoff * 2);
     }
   }
-  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;
+  async join({ invitation }) {
+    if (this.credential || this.leaveCredential) {
+      const left = await this.leave();
+      if (left.status !== "disconnected") return left;
     }
-    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 });
-      return this.consume(result);
-    })();
-    try { return await this.polling; } finally { this.polling = null; }
-  }
-  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;
+      url = new URL(invitation.trim());
     } catch {
-      this.closeRealtime();
-      return false;
+      throw new Error(
+        "Copy a cloud invitation from Teams Facilitator; legacy room tokens are not supported by this connector.",
+      );
     }
-  }
-  async join({ invitation }) {
-    const previousPoll = this.polling;
-    if (this.credential) await this.leave();
-    if (previousPoll) await previousPoll.catch(() => {});
-    let url;
-    try { url = new URL(invitation.trim()); } catch { throw new Error("Copy a cloud invitation from Methodiq; legacy room tokens are not supported by this 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", { clientName: this.clientName }, { invitation: url.hash.slice(1) });
-    if (!result.credential) return { ...DISCONNECTED };
-    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) {
-      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.");
+    const allowed = this.configuredOrigin
+      ? [this.configuredOrigin]
+      : DEFAULT_ORIGINS;
+    if (
+      !allowed.includes(url.origin) ||
+      !/^[A-Za-z0-9_-]{43}$/.test(url.hash.slice(1))
+    )
+      throw new Error(
+        "Invitation is not from the configured Teams Facilitator site.",
+      );
+    this.origin = url.origin;
+    this.stopped = new AbortController();
+    // The invitation is single-use, so the connector picks its own credential: a join
+    // whose response was lost is repeated and resumes the same connection.
+    const result = await this.request("join", {
+      invitation: url.hash.slice(1),
+      client: this.clientName,
+      credential: randomBytes(32).toString("base64url"),
+    });
+    // "connecting": the meeting worker is still starting; listening waits for it.
+    if (
+      (result.status !== "joined" && result.status !== "connecting") ||
+      typeof result.credential !== "string"
+    )
+      return result.status === "disconnected"
+        ? this.stop()
+        : { ...DISCONNECTED };
+    this.credential = result.credential;
+    this.agentName = result.agentName;
+    this.mode = result.mode || "text";
+    const framework =
+      result.frameworkName || FRAMEWORKS[result.framework] || result.framework;
+    const note = framework
+      ? ` The meeting is using the ${framework} framework; if helpful, do a quick search for ${framework} best practices.`
+      : "";
+    return {
+      status: "joined",
+      agentName: this.agentName,
+      mode: this.mode,
+      ...(framework ? { framework } : {}),
+      instruction: `Call methodiq_wait_for_question.${note} Stop if disconnected; do not automatically rejoin.`,
+    };
   }
   async wait({ timeout_seconds = 180 } = {}) {
-    const deadline = Date.now() + Math.max(5, Math.min(300, timeout_seconds)) * 1000;
+    const deadline =
+      Date.now() + Math.max(5, Math.min(300, timeout_seconds)) * 1000;
     while (this.credential && Date.now() < deadline) {
-      if (this.questions.length) {
-        const question = this.questions.shift(); this.lastQuestionId = question.id;
-        return { ...question, status: "question_received", mode: this.mode };
-      }
-      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; }
+      const result = await this.request(
+        "listen",
+        {
+          wait: Math.max(
+            5,
+            Math.min(45, Math.ceil((deadline - Date.now()) / 1000)),
+          ),
+        },
+        { until: deadline },
+      );
+      if (result.status === "disconnected") return { ...DISCONNECTED };
+      if (result.status === "unavailable")
+        return {
+          status: "reconnecting",
+          instruction:
+            "Teams Facilitator is briefly unreachable, but your meeting connection is kept. Call methodiq_wait_for_question again.",
+        };
+      if (result.mode) this.mode = result.mode;
+      if (result.status === "question") {
+        this.lastQuestionId = result.questionId;
+        return {
+          status: "question_received",
+          id: result.questionId,
+          question: result.question,
+          speaker: result.speaker,
+          isOwner: result.isOwner,
+          mode: this.mode,
+          recentConversation: result.recentConversation,
+          instruction: `${result.instruction} Reply with methodiq_speak_to_room.`,
+        };
       }
     }
-    return this.credential ? { status: "idle", instruction: "Continue with methodiq_wait_for_question; stop if disconnected." } : { ...DISCONNECTED };
+    return this.credential
+      ? {
+          status: "idle",
+          instruction:
+            "Continue with methodiq_wait_for_question; stop if disconnected.",
+        }
+      : { ...DISCONNECTED };
   }
-  async speak({ message, replyId = randomUUID(), questionId = this.lastQuestionId }) {
+  // The default reply ID comes from the question and message, so repeating an answer after
+  // a timeout or outage can never make it speak twice.
+  async speak({
+    message,
+    questionId = this.lastQuestionId,
+    replyId = replyIdFor(questionId, message),
+  }) {
     if (!this.credential) return { ...DISCONNECTED };
-    const response = await this.request("reply", { message, replyId, questionId }, { signal: this.stopped.signal });
-    if (response.status === "disconnected") return response;
-    if (response.status === "failed") return { status: "failed", replyId };
-    if (response.status === "delivered") return { status: "delivered", replyId };
-    const deadline = Date.now() + 55_000;
-    while (this.credential && Date.now() < deadline) {
-      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." };
-      }
-      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 };
+    const result = await this.request("say", { message, replyId, questionId });
+    if (result.status === "disconnected") return result;
+    if (result.status === "failed") return { status: "failed", replyId };
+    return {
+      status: "sent",
+      replyId,
+      mode: this.mode,
+      spokenToMeeting: this.mode === "voice",
+      instruction: "Continue listening with methodiq_wait_for_question.",
+    };
   }
   async transcript(args = {}) {
-    const result = await this.request("transcript", { limit: args.limit || 20 }, { signal: this.stopped.signal });
+    const result = await this.request("transcript", {
+      limit: args.limit || 20,
+    });
     if (result.status === "disconnected") return result;
-    return { count: result.turns.length, transcript: result.turns.map(t => `[${t.speaker}]: ${t.content}`).join("\n") };
+    const turns = Array.isArray(result.turns) ? result.turns : [];
+    return {
+      count: turns.length,
+      transcript: turns.map((t) => `[${t.speaker}]: ${t.content}`).join("\n"),
+    };
   }
   async leave() {
-    const credential = this.credential;
+    const credential = this.credential || this.leaveCredential;
     this.stop();
-    try { if (credential) await this.request("disconnect", {}, { credential }); }
-    catch { /* The server's connection lease removes an unreachable actor. */ }
-    return { ...DISCONNECTED };
+    if (!credential) return { ...DISCONNECTED };
+    // Stop locally immediately, but keep the removal credential until the
+    // server confirms it: a failed request must remain retryable.
+    this.leaveCredential = credential;
+    try {
+      const result = await this.request(
+        "leave",
+        {},
+        { credential, once: true },
+      );
+      if (result.status === "disconnected") {
+        this.leaveCredential = null;
+        return { ...DISCONNECTED };
+      }
+    } catch {
+      /* Report unconfirmed removal below, preserving the credential. */
+    }
+    return {
+      status: "error",
+      message:
+        "Local listening and responses have stopped, but Teams Facilitator could not confirm removal from the meeting.",
+      instruction:
+        "Call methodiq_leave_session again to retry removal. Do not rejoin or respond.",
+    };
   }
 }
 
 export const tools = [
-  { 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" } } } },
-  { name: "methodiq_leave_session", description: "Leave and stop responding to the meeting.", inputSchema: { type: "object", properties: {} } },
+  {
+    name: "methodiq_join_session",
+    description:
+      "Join with the unchanged invitation copied from Teams Facilitator.",
+    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" } } },
+  },
+  {
+    name: "methodiq_leave_session",
+    description: "Leave and stop responding to the meeting.",
+    inputSchema: { type: "object", properties: {} },
+  },
 ];
-export function setup({ local = false, serverUrl = process.env.METHODIQ_URL } = {}) {
+export function setup({
+  local = false,
+  serverUrl = process.env.METHODIQ_URL,
+} = {}) {
   const origin = serverUrl ? new URL(serverUrl).origin : undefined;
-  if (origin && !/^https?:\/\//.test(origin)) throw new Error("Methodiq requires an HTTP or HTTPS site origin.");
-  return { mcpServers: { methodiq: {
-    command: local ? process.execPath : "npx",
-    args: local ? [fileURLToPath(import.meta.url)] : ["--yes", `@methodiq/mcp@${VERSION}`],
-    ...(origin ? { env: { METHODIQ_URL: origin } } : {}),
-  } } };
+  if (origin && !/^https?:\/\//.test(origin))
+    throw new Error("Teams Facilitator requires an HTTP or HTTPS site origin.");
+  return {
+    mcpServers: {
+      methodiq: {
+        command: local ? process.execPath : "npx",
+        args: local
+          ? [fileURLToPath(import.meta.url)]
+          : ["--yes", `@methodiq/mcp@${VERSION}`],
+        ...(origin ? { env: { METHODIQ_URL: origin } } : {}),
+      },
+    },
+  };
 }
 export function startStdio(connector = new Connector()) {
-  const handlers = { methodiq_join_session: "join", methodiq_wait_for_question: "wait", methodiq_speak_to_room: "speak", methodiq_get_transcript: "transcript", methodiq_leave_session: "leave" };
-  const send = value => process.stdout.write(JSON.stringify({ jsonrpc: "2.0", ...value }) + "\n");
+  const handlers = {
+    methodiq_join_session: "join",
+    methodiq_wait_for_question: "wait",
+    methodiq_speak_to_room: "speak",
+    methodiq_get_transcript: "transcript",
+    methodiq_leave_session: "leave",
+  };
+  const send = (value) =>
+    process.stdout.write(JSON.stringify({ jsonrpc: "2.0", ...value }) + "\n");
   const input = readline.createInterface({ input: process.stdin });
-  input.on("line", async line => {
+  input.on("line", async (line) => {
     let msg;
-    try { msg = JSON.parse(line); } catch { send({ id: null, error: { code: -32700, message: "Invalid JSON" } }); return; }
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      send({ id: null, error: { code: -32700, message: "Invalid JSON" } });
+      return;
+    }
     if (msg.id === undefined) return;
     try {
       let result;
       if (msg.method === "initialize") {
-        connector.clientName = typeof msg.params?.clientInfo?.name === "string" ? msg.params.clientInfo.name.slice(0, 128) : undefined;
-        const supported = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
-        result = { protocolVersion: supported.includes(msg.params?.protocolVersion) ? msg.params.protocolVersion : supported[0], capabilities: { tools: {} }, serverInfo: { name: "@methodiq/mcp", version: VERSION } };
-      }
-      else if (msg.method === "ping") result = {};
+        connector.clientName =
+          typeof msg.params?.clientInfo?.name === "string"
+            ? msg.params.clientInfo.name.slice(0, 128)
+            : undefined;
+        const supported = [
+          "2025-11-25",
+          "2025-06-18",
+          "2025-03-26",
+          "2024-11-05",
+        ];
+        result = {
+          protocolVersion: supported.includes(msg.params?.protocolVersion)
+            ? msg.params.protocolVersion
+            : supported[0],
+          capabilities: { tools: {} },
+          serverInfo: { name: "@methodiq/mcp", version: VERSION },
+          instructions: INSTRUCTIONS,
+        };
+      } else if (msg.method === "ping") result = {};
       else if (msg.method === "tools/list") result = { tools };
       else if (msg.method === "tools/call") {
         const method = handlers[msg.params?.name];
         if (!method) throw new Error("Unknown tool");
         const value = await connector[method](msg.params.arguments || {});
         result = { content: [{ type: "text", text: JSON.stringify(value) }] };
-      } else { send({ id: msg.id, error: { code: -32601, message: "Unknown method" } }); return; }
+      } else {
+        send({
+          id: msg.id,
+          error: { code: -32601, message: "Unknown method" },
+        });
+        return;
+      }
       send({ id: msg.id, result });
-    } catch (error) { send({ id: msg.id, result: { isError: true, content: [{ type: "text", text: error.message }] } }); }
+    } catch (error) {
+      send({
+        id: msg.id,
+        result: {
+          isError: true,
+          content: [{ type: "text", text: error.message }],
+        },
+      });
+    }
   });
   input.on("close", () => connector.leave().catch(() => connector.stop()));
   return input;
 }
-if (process.argv[1] && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) {
-  if (Number(process.versions.node.split(".")[0]) < 22) { console.error("Methodiq requires Node.js 22 or newer."); process.exitCode = 1; }
-  else if (process.argv.includes("--setup")) {
+if (
+  process.argv[1] &&
+  fileURLToPath(import.meta.url) === realpathSync(process.argv[1])
+) {
+  if (Number(process.versions.node.split(".")[0]) < 22) {
+    console.error("Teams Facilitator requires Node.js 22 or newer.");
+    process.exitCode = 1;
+  } else if (process.argv.includes("--setup")) {
     try {
       const urlIndex = process.argv.indexOf("--url");
-      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 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; }
+      const serverUrl =
+        urlIndex >= 0 ? process.argv[urlIndex + 1] : process.env.METHODIQ_URL;
+      if (urlIndex >= 0 && (!serverUrl || serverUrl.startsWith("--")))
+        throw new Error("--url requires the Teams Facilitator site's origin.");
+      console.log(
+        JSON.stringify(
+          setup({ local: process.argv.includes("--local"), serverUrl }),
+          null,
+          2,
+        ),
+      );
+      console.error(
+        "Replace the existing `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,7 +1,8 @@
 {
   "name": "@methodiq/mcp",
-  "version": "1.0.1",
-  "description": "Assistant-neutral Methodiq meeting connector",
+  "version": "1.1.0",
+  "description": "Assistant-neutral Teams Facilitator meeting connector",
+  "homepage": "https://www.teamsfacilitator.com/bring-your-own-agent",
   "main": "connector.js",
   "type": "module",
   "bin": {
@@ -12,9 +13,6 @@
     "dev:legacy": "node index.js",
     "test": "node --test connector.test.js"
   },
-  "dependencies": {
-    "convex": "^1.41.0"
-  },
   "engines": {
     "node": ">=22"
   },
@@ -29,7 +27,8 @@
   "keywords": [
     "mcp",
     "model-context-protocol",
-    "methodiq"
+    "methodiq",
+    "teams-facilitator"
   ],
   "author": "Methodiq",
   "license": "ISC"