@methodiq/mcp 1.0.0

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +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
+
+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
+
+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/connector.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+import readline from "node:readline";
+import { randomUUID } from "node:crypto";
+import { readFileSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+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 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 });
+});
+
+export class Connector {
+  constructor({ fetchImpl = fetch, serverUrl = process.env.METHODIQ_URL, pollMs = 1500 } = {}) {
+    this.fetch = fetchImpl; this.configuredOrigin = serverUrl ? new URL(serverUrl).origin : null; this.pollMs = pollMs;
+    this.credential = null; this.cursor = 0; this.questions = []; this.deliveries = new Map();
+    this.stopped = new AbortController(); this.mode = "text";
+  }
+  stop() {
+    this.credential = null; clearInterval(this.heartbeat); this.stopped.abort();
+    this.questions = []; this.deliveries.clear();
+    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));
+    while (true) {
+      if (signal?.aborted) return { ...DISCONNECTED };
+      if (Date.now() >= deadline) return this.stop();
+      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),
+        });
+        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);
+      }
+    }
+  }
+  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;
+    })();
+    try { return await this.polling; } finally { this.polling = null; }
+  }
+  async join({ invitation, provider }) {
+    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", { provider, 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?.();
+    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(() => {});
+    }
+    await this.leave(); throw new Error("Meeting connection did not become ready. Copy a fresh invitation and try again.");
+  }
+  async wait({ timeout_seconds = 180 } = {}) {
+    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 };
+      }
+      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 };
+  }
+  async speak({ message, replyId = randomUUID(), questionId = this.lastQuestionId }) {
+    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) {
+      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; }
+    }
+    return this.credential ? { status: "pending", replyId, instruction: "Reply is queued; do not submit it again with a different reply ID." } : { ...DISCONNECTED };
+  }
+  async transcript(args = {}) {
+    const result = await this.request("transcript", { limit: args.limit || 20 }, { signal: this.stopped.signal });
+    if (result.status === "disconnected") return result;
+    return { count: result.turns.length, transcript: result.turns.map(t => `[${t.speaker}]: ${t.content}`).join("\n") };
+  }
+  async leave() {
+    const credential = this.credential;
+    this.stop();
+    try { if (credential) await this.request("disconnect", {}, { credential }); }
+    catch { /* The server's connection lease removes an unreachable actor. */ }
+    return { ...DISCONNECTED };
+  }
+}
+
+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_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 } = {}) {
+  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 } } : {}),
+  } } };
+}
+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 input = readline.createInterface({ input: process.stdin });
+  input.on("line", async line => {
+    let msg;
+    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 = {};
+      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; }
+      send({ id: msg.id, result });
+    } 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")) {
+    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 or restart, 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

@@ -0,0 +1,25 @@
+{
+  "name": "@methodiq/mcp",
+  "version": "1.0.0",
+  "description": "Assistant-neutral Methodiq meeting connector",
+  "main": "connector.js",
+  "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"
+}