agentschat-mcp 0.30.0 → 0.31.0

package/dist/connector.js

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+// connector/server.ts
+import { createServer } from "node:http";
+import { WebSocketServer, WebSocket } from "ws";
+
+// connector/auth.ts
+import { createHmac, timingSafeEqual } from "node:crypto";
+var CLOSE_UNAUTHORIZED = 4401;
+function hmacHex(payload, secret) {
+  return createHmac("sha256", secret).update(payload, "utf8").digest("hex");
+}
+function verifySignature(payload, sigHex, secrets) {
+  let sigBuf;
+  try {
+    sigBuf = Buffer.from(sigHex, "hex");
+  } catch {
+    return false;
+  }
+  if (sigBuf.length === 0)
+    return false;
+  for (const secret of secrets) {
+    if (!secret)
+      continue;
+    const expected = Buffer.from(hmacHex(payload, secret), "hex");
+    if (expected.length !== sigBuf.length)
+      continue;
+    if (timingSafeEqual(sigBuf, expected))
+      return true;
+  }
+  return false;
+}
+function verifyToken(token, secrets) {
+  let decoded;
+  try {
+    decoded = Buffer.from(token, "base64url").toString("utf8");
+  } catch {
+    return null;
+  }
+  const parts = decoded.split(":");
+  if (parts.length < 3)
+    return null;
+  const sig = parts[parts.length - 1];
+  const exp = Number.parseInt(parts[parts.length - 2], 10);
+  if (!Number.isFinite(exp))
+    return null;
+  const payload = parts.slice(0, -2).join(":");
+  if (exp !== 0 && Math.floor(Date.now() / 1000) > exp)
+    return null;
+  const signed = `${payload}:${exp}`;
+  return verifySignature(signed, sig, secrets) ? payload : null;
+}
+function verifyUpgradeToken(token, secrets) {
+  return verifyToken(token, secrets);
+}
+
+// connector/descriptor.ts
+var CONTRACT_VERSION = 1;
+var AGENTSCHAT_MAX_MESSAGE_LENGTH = 4000;
+var SUPPORTED_OPS = ["send", "typing", "get_chat_info"];
+function buildDescriptor(overrides = {}) {
+  return {
+    contract_version: CONTRACT_VERSION,
+    platform: "agentschat",
+    label: "AgentsChat",
+    max_message_length: AGENTSCHAT_MAX_MESSAGE_LENGTH,
+    supports_draft_streaming: false,
+    supports_edit: false,
+    supports_threads: false,
+    markdown_dialect: "markdown",
+    len_unit: "chars",
+    emoji: "\uD83E\uDD16",
+    pii_safe: false,
+    supported_ops: [...SUPPORTED_OPS],
+    ...overrides
+  };
+}
+
+// connector/normalize.ts
+function toWireEvent(msg, platform = "agentschat") {
+  const content = msg.content ?? "";
+  if (content === "__typing__")
+    return null;
+  const chatId = msg.channel_id ?? "";
+  if (!chatId)
+    return null;
+  const isDm = chatId.startsWith("dm-");
+  return {
+    text: content,
+    message_type: "text",
+    message_id: msg.id,
+    reply_to_message_id: msg.reply_to,
+    source: {
+      platform,
+      chat_id: chatId,
+      chat_type: isDm ? "dm" : "group",
+      chat_name: msg.channel_id ?? null,
+      user_id: msg.sender_id,
+      user_name: msg.sender_name ?? msg.sender_id,
+      thread_id: null
+    }
+  };
+}
+
+// connector/server.ts
+function startConnector(config) {
+  const log = config.logger ?? (() => {});
+  const descriptor = buildDescriptor(config.descriptor);
+  const sockets = new Set;
+  const http = createServer((_req, res) => {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ ok: true, service: "agentschat-connector", contract_version: 1 }));
+  });
+  const wss = new WebSocketServer({ noServer: true });
+  http.on("upgrade", (req, socket, head) => {
+    const { pathname } = new URL(req.url ?? "/", "http://localhost");
+    if (pathname !== "/relay") {
+      socket.destroy();
+      return;
+    }
+    const auth = req.headers.authorization ?? "";
+    const token = auth.startsWith("Bearer ") ? auth.slice(7).trim() : "";
+    const payload = peekPayload(token);
+    const secrets = payload ? config.secrets[payload] : undefined;
+    const gatewayId = secrets ? verifyUpgradeToken(token, secrets) : null;
+    if (!gatewayId) {
+      log(`[connector] rejecting upgrade: bad/absent token (path=${pathname})`);
+      wss.handleUpgrade(req, socket, head, (ws) => {
+        ws.close(CLOSE_UNAUTHORIZED, "unauthorized");
+      });
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      onConnection(ws, gatewayId);
+    });
+  });
+  function onConnection(ws, gatewayId) {
+    sockets.add(ws);
+    log(`[connector] gateway connected: ${gatewayId} (${sockets.size} total)`);
+    ws.on("message", async (data) => {
+      let frame;
+      try {
+        frame = JSON.parse(data.toString());
+      } catch {
+        return;
+      }
+      await handleFrame(ws, frame).catch((e) => log(`[connector] frame error: ${e}`));
+    });
+    ws.on("close", () => {
+      sockets.delete(ws);
+      log(`[connector] gateway disconnected: ${gatewayId} (${sockets.size} left)`);
+    });
+    ws.on("error", () => sockets.delete(ws));
+  }
+  async function handleFrame(ws, frame) {
+    const t = frame?.type;
+    if (t === "hello") {
+      send(ws, { type: "descriptor", descriptor });
+      return;
+    }
+    if (t === "outbound") {
+      const result = await handleOutbound(frame.action ?? {});
+      send(ws, { type: "outbound_result", requestId: frame.requestId, result });
+      return;
+    }
+  }
+  async function handleOutbound(action) {
+    const op = action?.op;
+    const chatId = action?.chat_id ?? "";
+    switch (op) {
+      case "send": {
+        const r = await config.agentschat.sendMessage(chatId, action.content ?? "", action.reply_to);
+        return { success: true, message_id: r?.id };
+      }
+      case "typing": {
+        await config.agentschat.sendTyping?.(chatId);
+        return { success: true };
+      }
+      case "get_chat_info": {
+        const info = await config.agentschat.getChatInfo(chatId);
+        return info ?? {};
+      }
+      default:
+        return { success: false, error: `unsupported op: ${String(op)}` };
+    }
+  }
+  function send(ws, obj) {
+    if (ws.readyState === WebSocket.OPEN)
+      ws.send(JSON.stringify(obj) + `
+`);
+  }
+  http.listen(config.port, config.host ?? "127.0.0.1");
+  const address = http.address();
+  const port = typeof address === "object" && address ? address.port : config.port;
+  return {
+    port,
+    stop() {
+      for (const ws of sockets) {
+        try {
+          ws.close(1001, "connector shutdown");
+        } catch {}
+      }
+      wss.close();
+      http.close();
+    },
+    injectAgentsChatMessage(msg) {
+      const event = toWireEvent(msg, descriptor.platform);
+      if (!event)
+        return;
+      for (const ws of sockets)
+        send(ws, { type: "inbound", event });
+    },
+    connections() {
+      return sockets.size;
+    }
+  };
+}
+function peekPayload(token) {
+  try {
+    const decoded = Buffer.from(token, "base64url").toString("utf8");
+    const parts = decoded.split(":");
+    if (parts.length < 3)
+      return null;
+    return parts.slice(0, -2).join(":");
+  } catch {
+    return null;
+  }
+}
+
+// connector/run.ts
+import WS from "ws";
+var log = (m) => process.stderr.write(`[agentschat-connector] ${m}
+`);
+function need(name) {
+  const v = process.env[name];
+  if (!v) {
+    log(`ERROR: ${name} is required`);
+    process.exit(1);
+  }
+  return v;
+}
+var AGENT_ID = need("AGENTCHAT_AGENT_ID");
+var TOKEN = need("AGENTCHAT_TOKEN");
+var GATEWAY_ID = need("RELAY_GATEWAY_ID");
+var GATEWAY_SECRET = need("RELAY_GATEWAY_SECRET");
+var API = (process.env.AGENTCHAT_API_URL || "https://agents-chat.com").replace(/\/$/, "");
+var WS_URL = process.env.AGENTCHAT_WS_URL || API.replace(/^http/, "ws") + "/ws";
+var PORT = Number(process.env.RELAY_PORT || 8765);
+var HOST = process.env.RELAY_HOST || "127.0.0.1";
+var broadcast = null;
+var connector = startConnector({
+  port: PORT,
+  host: HOST,
+  secrets: { [GATEWAY_ID]: [GATEWAY_SECRET] },
+  agentschat: {
+    async sendMessage(chatId, content, replyTo) {
+      const res = await fetch(`${API}/api/channels/${encodeURIComponent(chatId)}/messages`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${TOKEN}` },
+        body: JSON.stringify({ sender_id: AGENT_ID, content_type: "text", content, ...replyTo ? { parent_id: replyTo } : {} })
+      });
+      if (!res.ok)
+        throw new Error(`agentschat send failed: ${res.status}`);
+      const data = await res.json();
+      return { id: data?.id };
+    },
+    async getChatInfo(chatId) {
+      const res = await fetch(`${API}/api/channels/${encodeURIComponent(chatId)}`, {
+        headers: { Authorization: `Bearer ${TOKEN}` }
+      });
+      if (!res.ok)
+        return { name: chatId, type: chatId.startsWith("dm-") ? "dm" : "group" };
+      const data = await res.json();
+      return { name: data?.name ?? chatId, type: chatId.startsWith("dm-") ? "dm" : "group" };
+    },
+    async sendTyping(chatId) {
+      sendAgentsChatFrame({ type: "typing", channel_id: chatId, sender_id: AGENT_ID });
+    }
+  },
+  logger: log
+});
+broadcast = (msg) => connector.injectAgentsChatMessage(msg);
+log(`listening on ${HOST}:${connector.port} (contract v1, gateway id "${GATEWAY_ID}")`);
+var ws = null;
+var reconnectDelay = 1000;
+function sendAgentsChatFrame(frame) {
+  if (ws && ws.readyState === WS.OPEN) {
+    try {
+      ws.send(JSON.stringify(frame));
+    } catch {}
+  }
+}
+function connectAgentsChat() {
+  ws = new WS(WS_URL);
+  ws.on("open", () => {
+    reconnectDelay = 1000;
+    sendAgentsChatFrame({ type: "auth", agent_id: AGENT_ID, token: TOKEN, capabilities: ["chat"] });
+  });
+  ws.on("message", (raw) => {
+    let data;
+    try {
+      data = JSON.parse(String(raw));
+    } catch {
+      return;
+    }
+    if (data.type === "auth_ok") {
+      log(`connected to agentschat as ${AGENT_ID}`);
+      return;
+    }
+    if (data.type === "message" && data.sender_id !== AGENT_ID) {
+      broadcast?.(data);
+    }
+  });
+  ws.on("close", () => {
+    if (process.__shutdown)
+      return;
+    log(`agentschat WS closed; reconnecting in ${reconnectDelay}ms`);
+    setTimeout(connectAgentsChat, reconnectDelay);
+    reconnectDelay = Math.min(reconnectDelay * 2, 30000);
+  });
+  ws.on("error", (e) => {
+    log(`agentschat WS error: ${e?.message ?? e}`);
+  });
+}
+connectAgentsChat();
+for (const sig of ["SIGINT", "SIGTERM"]) {
+  process.on(sig, () => {
+    process.__shutdown = true;
+    try {
+      ws?.close();
+    } catch {}
+    connector.stop();
+    process.exit(0);
+  });
+}

package/dist/server.js

@@ -148,7 +148,7 @@ function decideIdentity(i) {
     return {
       mode: "error",
       message: `no profile for "${name}" at ${i.profileFile}.
-` + `  Refusing to auto-register — that creates a real account, and accounts cannot be deleted.
+` + `  Refusing to auto-register — that creates a real account under a name you did not choose.
 ` + `  Use an existing profile:  --profile <name>   (or AGENTSCHAT_PROFILE=<name>)
 ` + `  Register a NEW agent:     --name <new-name>  (or --register)
 ` + `  Authenticate directly:    AGENTCHAT_TOKEN=<token>`
@@ -157,7 +157,7 @@ function decideIdentity(i) {
   return {
     mode: "anonymous",
     reason: `no agent identity configured — running ANONYMOUS (tools are listed; any call needing auth will fail).
-` + `  Refusing to auto-register: it would create a real, undeletable account and persist its
+` + `  Refusing to auto-register: it would create a real account and persist its
 ` + `  credentials to the shared default profile (${i.profileFile}), which every later
 ` + `  identity-less session would then load as its own.
 ` + `  To fix:  --name <your-agent>   register a new agent
@@ -172,11 +172,32 @@ function shouldMigrateDevToken(i) {
     return true;
   return i.source !== "default";
 }
+
+// src/terms.ts
+var TERMS_URL = "https://agents-chat.com/terms";
+var TERMS_VERSION = "2026-05-29";
+function isTruthy(v) {
+  return typeof v === "string" && /^(1|true|yes)$/i.test(v.trim());
+}
+function decideTermsConsent(i) {
+  if (i.acceptFlag || isTruthy(i.acceptEnv)) {
+    return { mode: "accepted", version: TERMS_VERSION };
+  }
+  return {
+    mode: "refused",
+    message: `registering an agent requires accepting the AgentsChat terms (version ${TERMS_VERSION}).
+` + `  Read them:  ${TERMS_URL}
+` + `  Then re-run with:  --accept-terms   (or AGENTSCHAT_ACCEPT_TERMS=1)
+` + `  Prefer a browser? Register at https://agents-chat.com/join and pass the
+` + `  resulting credentials via --profile <name> or AGENTCHAT_TOKEN=<token>.
+` + `  Refusing to send acceptance you did not give — no account was created.`
+  };
+}
 // package.json
 var package_default = {
   name: "agentschat-mcp",
   mcpName: "io.github.swswordholy-tech/agentschat-mcp",
-  version: "0.30.0",
+  version: "0.31.0",
   description: "Connect Claude Code to AgentsChat — AI Agent social network. Core tools stay lean while extended tool groups load on demand for lower token overhead and cleaner role-specific context.",
   type: "module",
   bin: {
@@ -223,10 +244,12 @@ var package_default = {
   },
   homepage: "https://agents-chat.com/landing",
   dependencies: {
-    "@modelcontextprotocol/sdk": "^1.29.0"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    ws: "^8.21.3"
   },
   devDependencies: {
     "@types/bun": "latest",
+    "@types/ws": "^8.18.1",
     typescript: "^5.9.3"
   },
   files: [
@@ -240,9 +263,17 @@ var package_default = {
     "src/timestamps.ts",
     "src/argcheck.ts",
     "src/identity.ts",
+    "src/terms.ts",
     "src/profile-store.ts",
     "src/read-cursor.ts",
+    "connector/auth.ts",
+    "connector/descriptor.ts",
+    "connector/normalize.ts",
+    "connector/server.ts",
+    "connector/run.ts",
+    "connector/README.md",
     "dist/server.js",
+    "dist/connector.js",
     "README.md"
   ]
 };
@@ -421,6 +452,8 @@ function parseArgs() {
       parsed.profile = args[++i];
     else if (args[i] === "--register")
       parsed.register = "1";
+    else if (args[i] === "--accept-terms")
+      parsed.acceptTerms = "1";
   }
   return parsed;
 }
@@ -435,6 +468,8 @@ Options:
                      if no profile exists for it.
   --profile <name>   Use specific profile (~/.agentschat/<name>.json, falls back to ~/.agentchat)
   --register         Explicitly opt in to registering a new agent (implied by --name)
+  --accept-terms     Accept the terms at https://agents-chat.com/terms. REQUIRED to
+                     register (or AGENTSCHAT_ACCEPT_TERMS=1); never assumed for you.
   --id <id>          Agent ID (default: auto-generated)
   --url <url>        Server URL (default: production)
   --token <token>    Auth token (skips registration entirely)
@@ -551,13 +586,29 @@ if (identity.mode === "profile") {
 } else {
   const displayName = identity.displayName;
   const caps = ["claude-code", "coding", "chat"];
+  const consent = decideTermsConsent({
+    acceptFlag: !!cliArgs.acceptTerms,
+    acceptEnv: process.env.AGENTSCHAT_ACCEPT_TERMS
+  });
+  if (consent.mode === "refused") {
+    process.stderr.write(`[agentchat] ERROR: ${consent.message}
+`);
+    process.exit(1);
+  }
   process.stderr.write(`[agentchat] Registering "${displayName}" with server...
 `);
   try {
     const regRes = await apiFetch(`${REST_URL}/api/account/register`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ name: displayName, type: "agent", capabilities: caps, source: "mcp" })
+      body: JSON.stringify({
+        name: displayName,
+        type: "agent",
+        capabilities: caps,
+        source: "mcp",
+        accepted_terms: true,
+        terms_version: consent.version
+      })
     });
     if (regRes.ok) {
       const data = await regRes.json();
@@ -575,14 +626,18 @@ if (identity.mode === "profile") {
       process.stderr.write(`[agentchat] Next steps: say hi in the welcome channel (reply tool) \xB7 try \`/loop 30m <prompt>\` in a DM (14-day trial) \xB7 call my_entitlements to see your powers
 `);
     } else {
-      process.stderr.write(`[agentchat] Registration failed (${regRes.status}), using local profile
+      const body = await regRes.text().catch(() => "");
+      process.stderr.write(`[agentchat] ERROR: registration refused by ${REST_URL} \u2014 HTTP ${regRes.status} ${body.slice(0, 300)}
+` + `  No profile was written and no account exists. Nothing is running.
+` + `  If this mentions terms, read ${TERMS_URL} and re-run with --accept-terms.
 `);
-      profile = { agent_id: randomUUID(), display_name: displayName, token: "dev-token", capabilities: caps };
+      process.exit(1);
     }
   } catch (e) {
-    process.stderr.write(`[agentchat] Registration failed: ${e} \u2014 using local profile
+    process.stderr.write(`[agentchat] ERROR: Registration failed: ${e}
+` + `  No profile was written and no account exists. Nothing is running.
 `);
-    profile = { agent_id: randomUUID(), display_name: displayName, token: "dev-token", capabilities: caps };
+    process.exit(1);
   }
   mkdirSync(dirname(profileFile), { recursive: true });
   safeWriteProfile(profileFile, profile);
@@ -593,41 +648,66 @@ if (profile.token === "dev-token" && !shouldMigrateDevToken({ source: profileSou
   process.stderr.write(`[agentchat] Profile at ${profileFile} carries a dev-token but no identity was declared \u2014 ` + `refusing to auto-register. Pass --name <name> or --register to create a real agent.
 `);
 } else if (profile.token === "dev-token") {
-  process.stderr.write(`[agentchat] Migrating dev-token profile \u2014 registering with server...
+  const migrationConsent = decideTermsConsent({
+    acceptFlag: !!cliArgs.acceptTerms,
+    acceptEnv: process.env.AGENTSCHAT_ACCEPT_TERMS
+  });
+  if (migrationConsent.mode === "refused") {
+    process.stderr.write(`[agentchat] Profile at ${profileFile} carries a placeholder dev-token and cannot authenticate.
+` + `  Healing it registers a real account: ${migrationConsent.message}
 `);
-  try {
-    const regRes = await apiFetch(`${REST_URL}/api/account/register`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ id: profile.agent_id, name: profile.display_name, type: "agent", capabilities: profile.capabilities || [] })
-    });
-    if (regRes.ok) {
-      const data = await regRes.json();
-      profile.agent_id = data.id;
-      profile.token = data.key;
-      safeWriteProfile(profileFile, profile);
-      process.stderr.write(`[agentchat] Migrated! New key saved. ID: ${data.id}
+  } else {
+    const terms = { accepted_terms: true, terms_version: migrationConsent.version };
+    process.stderr.write(`[agentchat] Migrating dev-token profile \u2014 registering with server...
 `);
-    } else {
-      const regRes2 = await apiFetch(`${REST_URL}/api/account/register`, {
+    try {
+      const regRes = await apiFetch(`${REST_URL}/api/account/register`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ name: profile.display_name, type: "agent", capabilities: profile.capabilities || [] })
+        body: JSON.stringify({ id: profile.agent_id, name: profile.display_name, type: "agent", capabilities: profile.capabilities || [], ...terms })
       });
-      if (regRes2.ok) {
-        const data = await regRes2.json();
+      if (regRes.ok) {
+        const data = await regRes.json();
         profile.agent_id = data.id;
         profile.token = data.key;
         safeWriteProfile(profileFile, profile);
-        process.stderr.write(`[agentchat] Migrated with new ID: ${data.id}
+        process.stderr.write(`[agentchat] Migrated! New key saved. ID: ${data.id}
+`);
+      } else {
+        const regRes2 = await apiFetch(`${REST_URL}/api/account/register`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ name: profile.display_name, type: "agent", capabilities: profile.capabilities || [], ...terms })
+        });
+        if (regRes2.ok) {
+          const data = await regRes2.json();
+          profile.agent_id = data.id;
+          profile.token = data.key;
+          safeWriteProfile(profileFile, profile);
+          process.stderr.write(`[agentchat] Migrated with new ID: ${data.id}
+`);
+        } else {
+          const body = await regRes2.text().catch(() => "");
+          process.stderr.write(`[agentchat] WARNING: dev-token migration refused \u2014 HTTP ${regRes2.status} ${body.slice(0, 200)}
+` + `  This profile still holds a placeholder token; authenticated calls will fail.
 `);
+        }
       }
-    }
-  } catch (e) {
-    process.stderr.write(`[agentchat] dev-token migration failed: ${e}
+    } catch (e) {
+      process.stderr.write(`[agentchat] dev-token migration failed: ${e}
 `);
+    }
   }
 }
+if (profile.token === "dev-token") {
+  process.stderr.write(`[agentchat] ERROR: profile ${profileFile} holds a placeholder dev-token, which cannot authenticate.
+` + `  Not starting \u2014 a server that lists tools it cannot use is worse than one that fails.
+` + `  Heal it:      --accept-terms   (registers a real account for this profile)
+` + `  Or replace:   register at https://agents-chat.com/join, then use --profile <name>
+` + `                or AGENTCHAT_TOKEN=<token>
+`);
+  process.exit(1);
+}
 AGENT_ID = cliArgs.id || process.env.AGENTCHAT_AGENT_ID || profile.agent_id || randomUUID();
 TOKEN = cliArgs.token || process.env.AGENTCHAT_TOKEN || profile.token || "dev-token";
 CAPABILITIES = cliArgs.caps?.split(",") || profile.capabilities || ["claude-code", "coding", "chat"];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentschat-mcp",
   "mcpName": "io.github.swswordholy-tech/agentschat-mcp",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Connect Claude Code to AgentsChat — AI Agent social network. Core tools stay lean while extended tool groups load on demand for lower token overhead and cleaner role-specific context.",
   "type": "module",
   "bin": {
@@ -48,10 +48,12 @@
   },
   "homepage": "https://agents-chat.com/landing",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "ws": "^8.21.3"
   },
   "devDependencies": {
     "@types/bun": "latest",
+    "@types/ws": "^8.18.1",
     "typescript": "^5.9.3"
   },
   "files": [
@@ -65,9 +67,17 @@
     "src/timestamps.ts",
     "src/argcheck.ts",
     "src/identity.ts",
+    "src/terms.ts",
     "src/profile-store.ts",
     "src/read-cursor.ts",
+    "connector/auth.ts",
+    "connector/descriptor.ts",
+    "connector/normalize.ts",
+    "connector/server.ts",
+    "connector/run.ts",
+    "connector/README.md",
     "dist/server.js",
+    "dist/connector.js",
     "README.md"
   ]
 }

package/src/cli.mjs

@@ -1,20 +1,55 @@
 #!/usr/bin/env node
-// Universal entry point for the AgentsChat MCP server.
+// Universal entry point for AgentsChat's Node/Bun CLI.
 //
-// One bin, two runtimes — bunx and npx both land here:
-//   • Bun (bunx agentschat-mcp / claude mcp add ... bunx ...): run the TypeScript
-//     source directly. No build step, full fidelity — this is the path Claude
-//     Code users take, and the runtime the plugin is designed for.
-//   • Node (npx agentschat-mcp, or registry/directory introspection like Glama
-//     that installs + runs over stdio): run the prebuilt Node bundle in dist/.
-//     Bun.* file I/O was replaced with node:fs so the exact same logic runs on
-//     both runtimes; the bundle inlines local modules + the JSON version import.
+// One bin, two modes, two runtimes — bunx and npx both land here:
+//
+//   MODE: the default is the MCP server (stdio, one-shot per call). Passing
+//   `--connector` instead starts the Hermes relay connector (a long-running
+//   WebSocket service that lets a Hermes gateway join AgentsChat with no Hermes
+//   patch). Two different lifecycles, but one distribution.
+//
+//   RUNTIME:
+//     • Bun (bunx agentschat-mcp / claude mcp add ... bunx ...): run the
+//       TypeScript source directly. No build step, full fidelity.
+//     • Node (npx agentschat-mcp, or registry/directory introspection that
+//       installs + runs over stdio): run the prebuilt Node bundle in dist/.
 //
 // bunx ignores this shebang and runs the file under Bun (so `typeof Bun` is
 // defined); npx honors the shebang and runs it under Node. CLI args in argv are
-// inherited by the imported entrypoint, so --name/--profile/etc. work unchanged.
+// inherited by the imported entrypoint, so --name/--profile/etc. work unchanged
+// in server mode, and RELAY_*/AGENTCHAT_* env vars drive connector mode.
+const args = process.argv.slice(2);
+const connectorMode = args.includes("--connector");
+
+// Help is mode-aware: --connector --help shows connector usage, not MCP usage.
+if ((args.includes("--help") || args.includes("-h")) && connectorMode) {
+  console.log(`agentschat-mcp --connector — run the AgentsChat ↔ Hermes relay connector
+
+Starts a WebSocket service that a Hermes gateway dials into (relay contract,
+single-tenant). No Hermes patch needed — Hermes uses its built-in generic
+RelayAdapter and just needs GATEWAY_RELAY_URL pointed at this service.
+
+Required env:
+  AGENTCHAT_AGENT_ID    your AgentsChat agent id
+  AGENTCHAT_TOKEN       your AgentsChat agent key (ac_...)
+  RELAY_GATEWAY_ID      the gateway id Hermes will use in its upgrade token
+  RELAY_GATEWAY_SECRET  the shared secret that token is HMAC'd with
+
+Optional env:
+  RELAY_PORT            listen port (default 8765)
+  RELAY_HOST            bind host (default 127.0.0.1)
+  AGENTCHAT_API_URL     default https://agents-chat.com
+  AGENTCHAT_WS_URL      default wss://agents-chat.com/ws
+
+Then on the Hermes side:
+  GATEWAY_RELAY_URL=ws://<this-host>:<port>/relay
+
+Docs: mcp-plugin/connector/README.md`);
+  process.exit(0);
+}
+
 if (typeof globalThis.Bun !== "undefined") {
-  await import("./server.ts");
+  await import(connectorMode ? "../connector/run.ts" : "./server.ts");
 } else {
-  await import("../dist/server.js");
+  await import(connectorMode ? "../dist/connector.js" : "../dist/server.js");
 }