agentschat-mcp 0.29.1 → 0.31.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentschat-mcp",
   "mcpName": "io.github.swswordholy-tech/agentschat-mcp",
-  "version": "0.29.1",
+  "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": {
@@ -9,6 +9,7 @@
     "agentchat-mcp": "src/cli.mjs"
   },
   "engines": {
+    "node": ">=22",
     "bun": ">=1.0.0"
   },
   "scripts": {
@@ -47,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": [
@@ -63,7 +66,18 @@
     "src/reconnect.ts",
     "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");
 }

package/src/identity.ts

@@ -0,0 +1,114 @@
+/**
+ * Startup identity policy — pure decision logic, no I/O.
+ *
+ * Lives outside the side-effecting server entrypoint (which registers accounts and
+ * writes credential files on import) so it can be unit-tested.
+ *
+ * Why this exists: auto-registration creates a REAL account on the server under an
+ * identity nobody chose. It must never fire implicitly. Previously a host that
+ * simply forgot to declare an identity (no --name/--profile/AGENTSCHAT_PROFILE, no
+ * token) would mint an anonymous `Claude-xxxxxx` agent on every first start — and
+ * because the bare fallback path is SHARED (`~/.agentschat/profile.json`), every
+ * later identity-less session loads that same file and collapses onto that one
+ * agent. A second trigger did the same for any profile still carrying `dev-token`.
+ *
+ * Policy: registration requires explicit opt-in (`--name` or `--register`).
+ *  - Nothing declared at all  → ANONYMOUS: no registration, no profile written.
+ *    stdio still answers initialize/tools/list, so registry introspection (Glama
+ *    builds and runs the server with zero config) keeps working; anything needing
+ *    auth fails loudly at call time rather than silently creating an account.
+ *  - An identity WAS declared but its profile is missing → hard error. That is a
+ *    typo/misconfig, and inventing an identity for it is what corrupted attribution
+ *    before. Introspection never hits this branch (it passes no flags).
+ */
+
+/** Which resolution tier produced the profile path (see resolveProfile in server.ts). */
+export type ProfileSource = "env" | "legacy-env" | "flag-profile" | "flag-name" | "default";
+
+export type IdentityDecision =
+  /** Profile file exists — load it. */
+  | { mode: "profile" }
+  /** Explicit token supplied via --token/AGENTCHAT_TOKEN — authenticate, never register. */
+  | { mode: "env-creds" }
+  /** Explicit opt-in (--name / --register) — register a new account and persist it. */
+  | { mode: "register"; displayName: string }
+  /** Identity declared but profile missing — refuse to invent one. */
+  | { mode: "error"; message: string }
+  /** Nothing declared — run unauthenticated, register nothing, persist nothing. */
+  | { mode: "anonymous"; reason: string };
+
+export interface IdentityInputs {
+  /** Does the resolved profile file already exist on disk? */
+  profileExists: boolean;
+  /** Which tier resolved the path. "default" means nothing was declared. */
+  source: ProfileSource;
+  /** The resolved profile path (used in operator-facing messages). */
+  profileFile: string;
+  /** Value of --name, if given. */
+  cliName?: string;
+  /** Value of --profile, or the *_PROFILE env var — used only for the error message. */
+  declaredName?: string;
+  /** Explicit --register opt-in. */
+  registerFlag?: boolean;
+  /** A token was supplied out-of-band (--token / AGENTCHAT_TOKEN). */
+  hasToken: boolean;
+  /** Generated name to use when --register is passed without --name. */
+  fallbackName: string;
+}
+
+export function decideIdentity(i: IdentityInputs): IdentityDecision {
+  // An existing profile is authoritative — this is the overwhelmingly common path.
+  if (i.profileExists) return { mode: "profile" };
+
+  // Credentials handed to us directly: we can authenticate, so there is nothing to
+  // register. (Previously this still registered, because the branch keyed only on
+  // the profile file being absent.)
+  if (i.hasToken) return { mode: "env-creds" };
+
+  // Explicit opt-in to creating a new account.
+  if (i.cliName) return { mode: "register", displayName: i.cliName };
+  if (i.registerFlag) return { mode: "register", displayName: i.fallbackName };
+
+  // An identity was named but no profile backs it. Do NOT invent one.
+  if (i.source !== "default") {
+    const name = i.declaredName ?? i.cliName ?? "(unknown)";
+    return {
+      mode: "error",
+      message:
+        `no profile for "${name}" at ${i.profileFile}.\n` +
+        `  Refusing to auto-register — that creates a real account under a name you did not choose.\n` +
+        `  Use an existing profile:  --profile <name>   (or AGENTSCHAT_PROFILE=<name>)\n` +
+        `  Register a NEW agent:     --name <new-name>  (or --register)\n` +
+        `  Authenticate directly:    AGENTCHAT_TOKEN=<token>`,
+    };
+  }
+
+  // Nothing declared. Stay usable for introspection, but create nothing.
+  return {
+    mode: "anonymous",
+    reason:
+      `no agent identity configured — running ANONYMOUS (tools are listed; any call needing auth will fail).\n` +
+      `  Refusing to auto-register: it would create a real account and persist its\n` +
+      `  credentials to the shared default profile (${i.profileFile}), which every later\n` +
+      `  identity-less session would then load as its own.\n` +
+      `  To fix:  --name <your-agent>   register a new agent\n` +
+      `           --profile <name>      use an existing profile (or AGENTSCHAT_PROFILE=<name>)\n` +
+      `           AGENTCHAT_TOKEN=<t>   authenticate directly`,
+  };
+}
+
+/**
+ * Second auto-register trigger: a profile that loaded successfully but still carries
+ * the placeholder `dev-token`. Legacy behavior re-registered it to heal the key —
+ * fine for an explicitly declared identity, but on the bare shared default path it
+ * mints an anonymous account exactly like the first trigger. Same opt-in gate.
+ */
+export function shouldMigrateDevToken(i: {
+  source: ProfileSource;
+  hasToken: boolean;
+  registerFlag?: boolean;
+}): boolean {
+  if (i.hasToken) return false; // out-of-band creds win; nothing to heal
+  if (i.registerFlag) return true; // explicit opt-in
+  return i.source !== "default"; // an identity was declared → healing it is intended
+}

package/src/profile-store.ts

@@ -0,0 +1,55 @@
+/**
+ * Atomic, permission-safe write of the agent profile.
+ *
+ * Extracted from the side-effecting server entrypoint so it can be unit-tested: the
+ * property that matters here (the key is never world-readable, even mid-write) is only
+ * observable if you can call this directly and interrupt it.
+ *
+ * The profile holds a live agent key, so 0600 is a security control. Two traps:
+ *  - `writeFileSync`'s `mode` applies ONLY when the file is created. A .tmp left behind by
+ *    an earlier crash keeps its own permissions, and `renameSync` preserves the source's
+ *    mode — so a stale 0644 .tmp yields a 0644 profile. Unlinking it first makes 0600 true
+ *    *by construction*: the key is never on disk world-readable, not even in the window
+ *    between rename and chmod.
+ *  - `chmodSync` used to be the sole enforcement point, and its failure was swallowed by a
+ *    bare `catch {}` — the key could sit world-readable with nothing said. Never swallow
+ *    it, and verify the result instead of assuming it took.
+ */
+import { existsSync, writeFileSync, renameSync, chmodSync, unlinkSync, statSync } from "fs";
+
+/** Where diagnostics go. Injectable so tests can assert on them. */
+export type Warn = (message: string) => void;
+
+const defaultWarn: Warn = (m) => process.stderr.write(m);
+
+export function safeWriteProfile(path: string, data: unknown, warn: Warn = defaultWarn): void {
+  const tmp = path + ".tmp";
+
+  // Residue from an earlier crash would keep its own (possibly 0644) permissions.
+  try {
+    if (existsSync(tmp)) unlinkSync(tmp);
+  } catch (e) {
+    warn(`[agentchat] WARNING: stale ${tmp} could not be removed: ${e}\n`);
+  }
+
+  // Created fresh → `mode` actually applies, so the key is 0600 from the instant it exists.
+  writeFileSync(tmp, JSON.stringify(data, null, 2), { mode: 0o600 });
+  renameSync(tmp, path);
+
+  try {
+    chmodSync(path, 0o600);
+  } catch (e) {
+    warn(`[agentchat] WARNING: could not chmod ${path} to 0600: ${e}\n`);
+  }
+
+  try {
+    const mode = statSync(path).mode & 0o777;
+    if (mode !== 0o600) {
+      warn(
+        `[agentchat] WARNING: ${path} is mode ${mode.toString(8)}, expected 600 — it holds your agent key. Fix: chmod 600 ${path}\n`,
+      );
+    }
+  } catch (e) {
+    warn(`[agentchat] WARNING: could not verify permissions of ${path}: ${e}\n`);
+  }
+}

package/src/read-cursor.ts

@@ -0,0 +1,60 @@
+/**
+ * Persistence of the per-agent read cursor (`last-seen-msg-ts-<agent>.json`).
+ *
+ * This is a state change, not best-effort teardown — it just happens to be *called*
+ * from teardown. Losing it silently means the next start reads a stale last-seen value
+ * and either replays messages or, worse, SKIPS them (the cursor-gap class).
+ *
+ * Two defects this module exists to prevent:
+ *  - The old writer swallowed its write error in a bare `catch {}` and returned normally,
+ *    so callers could not tell a failed flush from a successful one.
+ *  - The old flush cleared the dirty flag BEFORE writing. A failed write therefore both
+ *    discarded the cursor and disabled its own retry: the shutdown fallback flush sees
+ *    `dirty === false` and returns immediately. One failure = permanent silent loss.
+ *
+ * So: the write reports success, and the dirty flag is cleared ONLY once it lands.
+ */
+import { readFileSync, writeFileSync } from "fs";
+
+export type Warn = (message: string) => void;
+
+/**
+ * Read a persisted channel→timestamp map.
+ *
+ * A missing file is the normal first-run case and stays quiet. Anything else — corrupt
+ * JSON, bad permissions — means we are silently resetting state we were supposed to
+ * remember, and this runs ONCE at startup: there is no second attempt to notice it.
+ */
+export function loadCursor(file: string, warn: Warn): Map<string, string> {
+  try {
+    return new Map(Object.entries(JSON.parse(readFileSync(file, "utf-8")) as Record<string, string>));
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException)?.code !== "ENOENT") {
+      warn(`[agentchat] WARNING: could not read ${file} — resetting that state: ${e}\n`);
+    }
+    return new Map();
+  }
+}
+
+/** Write the cursor to disk. Returns true iff it actually landed. Never throws. */
+export function persistCursor(file: string, cursor: Map<string, string>, warn: Warn): boolean {
+  try {
+    writeFileSync(file, JSON.stringify(Object.fromEntries(cursor)));
+    return true;
+  } catch (e) {
+    warn(`[agentchat] WARNING: failed to persist read cursor to ${file}: ${e}\n`);
+    return false;
+  }
+}
+
+/**
+ * Flush state machine. Clears `dirty` only after `persist()` reports success, so a
+ * failed write stays dirty and the next flush (including the shutdown fallback) retries.
+ * Returns true iff the cursor was persisted.
+ */
+export function flushCursor(state: { dirty: boolean }, persist: () => boolean): boolean {
+  if (!state.dirty) return false;
+  const ok = persist();
+  if (ok) state.dirty = false;
+  return ok;
+}