@cohortapp/agent-sdk 2.3.0

package/lib/mcp/server.test.mjs

@@ -0,0 +1,400 @@
+/**
+ * server.test.mjs — the cohort-mcp stdio server.
+ *
+ * Two layers:
+ *   1. In-process: createMcpServer over PassThrough streams with an injected
+ *      fetchImpl/screenImpl — framing, version negotiation, tool listing,
+ *      dispatch, error mapping, stdout purity, truncation, audit rows, and
+ *      the §1.5 send-gate parity (incl. the org_rpc escape hatch).
+ *   2. End-to-end: boot the services/cohort reference server in-process on a
+ *      loopback port, spawn the REAL bin/cohort-mcp.mjs over stdio, and drive
+ *      initialize → tools/list → tools/call org_directory через the wire.
+ *
+ * Run: node --test lib/mcp/server.test.mjs
+ */
+
+"use strict";
+
+import { test, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { PassThrough } from "node:stream";
+import { spawn } from "node:child_process";
+import { mkdtempSync, rmSync, readFileSync, readdirSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { createMcpServer, toMcpTool, capResultText, MCP_PROTOCOL_VERSION, MAX_RESULT_BYTES } from "./server.mjs";
+import { getOrgTools, orgToolDef } from "../org/tool-surface.mjs";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+// Env hygiene — a developer's COHORT_* vars must not leak into the fixtures.
+const ENV_KEYS = ["COHORT_API_TOKEN", "COHORT_TOKEN", "COHORT_API_KEY", "COHORT_ORG_ID", "COHORT_BASE", "COHORT_API_URL", "COHORT_AGENT_ROOT", "AGENT_ROOT", "COHORT_AGENT_ID", "COHORT_AGENT_EMAIL"];
+const savedEnv = {};
+before(() => { for (const k of ENV_KEYS) { savedEnv[k] = process.env[k]; delete process.env[k]; } });
+after(() => { for (const k of ENV_KEYS) { if (savedEnv[k] === undefined) delete process.env[k]; else process.env[k] = savedEnv[k]; } });
+
+const CFG = { org: { cohort: { enabled: true, base: "https://org.example", orgId: "acme", token: "nlk_secret" } } };
+
+function fakeFetch(body = { ok: true, result: { fine: true } }) {
+  const calls = [];
+  const fn = async (url, init) => { calls.push({ url: String(url), init: init || {} }); return { ok: true, status: 200, json: async () => body, headers: { get: () => undefined } }; };
+  fn.calls = calls;
+  return fn;
+}
+
+/**
+ * Harness: a server over PassThrough streams. Returns helpers that send one
+ * JSON-RPC request and await its response frame (matched by id).
+ */
+function harness(opts = {}) {
+  const input = new PassThrough();
+  const output = new PassThrough();
+  const rawOut = [];
+  output.on("data", (c) => rawOut.push(c.toString("utf8")));
+  const logs = [];
+  const server = createMcpServer({
+    input,
+    output,
+    orgConfig: opts.orgConfig ?? CFG,
+    agentRoot: opts.agentRoot ?? mkdtempSync(join(tmpdir(), "mcp-root-")),
+    fetchImpl: opts.fetchImpl,
+    screenImpl: opts.screenImpl,
+    appendAudit: opts.appendAudit,
+    emailAvailable: opts.emailAvailable,
+    log: (lvl, m) => logs.push(`${lvl}:${m}`),
+  });
+  server.start();
+
+  let nextId = 1;
+  const pending = new Map();
+  let buffer = "";
+  output.on("data", (c) => {
+    buffer += c.toString("utf8");
+    let idx;
+    while ((idx = buffer.indexOf("\n")) >= 0) {
+      const line = buffer.slice(0, idx);
+      buffer = buffer.slice(idx + 1);
+      if (!line.trim()) continue;
+      const frame = JSON.parse(line);
+      const waiter = pending.get(frame.id);
+      if (waiter) { pending.delete(frame.id); waiter(frame); }
+    }
+  });
+
+  function request(method, params) {
+    const id = nextId++;
+    const p = new Promise((resolve) => pending.set(id, resolve));
+    input.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
+    return p;
+  }
+  function notify(method, params) {
+    input.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
+  }
+  function writeRaw(line) {
+    input.write(`${line}\n`);
+  }
+  return { server, request, notify, writeRaw, rawOut, logs, agentRoot: opts.agentRoot };
+}
+
+const tick = () => new Promise((r) => setTimeout(r, 25));
+
+// ── unit: shaping helpers ──────────────────────────────────────────────────
+
+test("toMcpTool: annotations — readOnlyHint on reads, idempotentHint from the protocol, destructiveHint on org_rpc", () => {
+  const dir = toMcpTool(orgToolDef("org_directory"));
+  assert.equal(dir.annotations.readOnlyHint, true);
+  assert.equal(dir.annotations.openWorldHint, false);
+  assert.deepEqual(dir.inputSchema, orgToolDef("org_directory").input_schema, "schema republished verbatim");
+  const send = toMcpTool(orgToolDef("messaging_send"));
+  assert.equal(send.annotations.readOnlyHint, undefined);
+  assert.equal(send.annotations.idempotentHint, true, "messaging.send is idempotent in the protocol");
+  const rpc = toMcpTool(orgToolDef("org_rpc"));
+  assert.equal(rpc.annotations.destructiveHint, true);
+});
+
+test("capResultText: 200 KB cap with explicit truncation marker", () => {
+  const small = capResultText("abc");
+  assert.equal(small, "abc");
+  const big = capResultText("x".repeat(MAX_RESULT_BYTES + 500));
+  assert.ok(Buffer.byteLength(big, "utf8") < MAX_RESULT_BYTES + 200);
+  assert.match(big, /…truncated/);
+});
+
+// ── in-process protocol ────────────────────────────────────────────────────
+
+test("initialize: prefers 2025-06-18, echoes older tools-only revisions", async () => {
+  const h1 = harness();
+  const r1 = await h1.request("initialize", { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "t" } });
+  assert.equal(r1.result.protocolVersion, "2024-11-05", "client's known older version echoed");
+  assert.deepEqual(r1.result.capabilities, { tools: {} });
+  assert.equal(r1.result.serverInfo.name, "cohort-mcp");
+  h1.server.stop();
+
+  const h2 = harness();
+  const r2 = await h2.request("initialize", { protocolVersion: "1999-01-01" });
+  assert.equal(r2.result.protocolVersion, MCP_PROTOCOL_VERSION, "unknown offer → our preferred version");
+  h2.server.stop();
+});
+
+test("tools/list: full active surface (email tools present — family is vendored), grouped + annotated", async () => {
+  const h = harness();
+  await h.request("initialize", { protocolVersion: MCP_PROTOCOL_VERSION });
+  h.notify("notifications/initialized");
+  const r = await h.request("tools/list", {});
+  const tools = r.result.tools;
+  assert.equal(tools.length, getOrgTools().length, "one MCP tool per active table entry");
+  assert.equal(tools.length, 107, "email + artifact + desk families vendored → 107 tools");
+  const names = tools.map((t) => t.name);
+  for (const expected of ["org_whoami", "org_describe", "org_rpc", "org_read", "messaging_send", "board_ready", "email_send", "email_inbox", "artifact_create", "artifact_act", "artifact_catalog", "email_mailboxes", "email_draft_send", "files_list", "calendar_find_a_time", "crm_list_deals", "books_reports", "meetings_recap_file"]) {
+    assert.ok(names.includes(expected), `${expected} listed`);
+  }
+  assert.ok(tools.every((t) => t.inputSchema && t.inputSchema.type === "object"));
+  h.server.stop();
+});
+
+test("tools/list honours the email gate (emailAvailable:false → 102 tools)", async () => {
+  const h = harness({ emailAvailable: false });
+  const r = await h.request("tools/list", {});
+  assert.equal(r.result.tools.length, 102, "the 5 own-mailbox email tools drop out");
+  const names = new Set(r.result.tools.map((t) => t.name));
+  // The five own-mailbox tools (email:true) are gated out …
+  for (const gated of ["email_send", "email_inbox", "email_message", "email_thread", "email_mark_read"]) {
+    assert.ok(!names.has(gated), `${gated} gated out`);
+  }
+  // … while the mail-DESK tools ride the independent desk gate (still vendored).
+  assert.ok(names.has("email_mailboxes"), "mail-desk tools ride the desk gate, not the email gate");
+  h.server.stop();
+});
+
+test("artifact tools flow through tools/list from ORG_TOOLS with correct annotations", async () => {
+  const h = harness();
+  const r = await h.request("tools/list", {});
+  const byName = new Map(r.result.tools.map((t) => [t.name, t]));
+  const cat = byName.get("artifact_catalog");
+  assert.ok(cat, "artifact_catalog listed");
+  assert.equal(cat.annotations.readOnlyHint, true, "catalog is a read");
+  const act = byName.get("artifact_act");
+  assert.ok(act, "artifact_act listed");
+  assert.equal(act.annotations.readOnlyHint, undefined, "act is a write");
+  // artifact.act is sideEffecting:false + not protocol-idempotent (the service
+  // dedupes on the BUSINESS idempotencyKey, auto-minted per call) → no hint.
+  assert.equal(act.annotations.idempotentHint, undefined);
+  assert.equal(act.inputSchema.required.includes("action"), true, "schema republished verbatim");
+  h.server.stop();
+});
+
+test("unknown method → -32601; parse error → -32700; notifications tolerated silently", async () => {
+  const h = harness();
+  const r = await h.request("resources/list", {});
+  assert.equal(r.error.code, -32601);
+  // parse error: raw junk line → error frame with id null
+  h.writeRaw("this is not json");
+  await tick();
+  const parseErr = h.rawOut.join("").split("\n").filter(Boolean).map((l) => JSON.parse(l)).find((f) => f.error && f.error.code === -32700);
+  assert.ok(parseErr, "parse error surfaced as -32700");
+  // notifications produce NO response frames
+  const framesBefore = h.rawOut.join("").split("\n").filter(Boolean).length;
+  h.notify("notifications/initialized");
+  h.notify("notifications/cancelled", { requestId: 1 });
+  await tick();
+  const framesAfter = h.rawOut.join("").split("\n").filter(Boolean).length;
+  assert.equal(framesAfter, framesBefore, "no response to notifications");
+  h.server.stop();
+});
+
+test("stdout purity: every byte on the output stream is a parseable JSON-RPC frame", async () => {
+  const h = harness({ fetchImpl: fakeFetch() });
+  await h.request("initialize", { protocolVersion: MCP_PROTOCOL_VERSION });
+  await h.request("tools/list", {});
+  await h.request("tools/call", { name: "org_describe", arguments: {} });
+  await h.request("ping", {});
+  h.writeRaw("{broken");
+  await tick();
+  const lines = h.rawOut.join("").split("\n").filter((l) => l.trim());
+  assert.ok(lines.length >= 5);
+  for (const line of lines) {
+    const frame = JSON.parse(line); // throws = test fails
+    assert.equal(frame.jsonrpc, "2.0", "every stdout line is a protocol frame");
+  }
+  assert.ok(h.logs.length > 0, "logs went to the logger (stderr lane), not stdout");
+  h.server.stop();
+});
+
+// ── in-process tools/call ──────────────────────────────────────────────────
+
+test("tools/call org_describe: works with zero network + zero credentials", async () => {
+  const h = harness({ orgConfig: {} });
+  const r = await h.request("tools/call", { name: "org_describe", arguments: { family: "email" } });
+  assert.equal(r.result.isError, false);
+  const payload = JSON.parse(r.result.content[0].text);
+  assert.ok(payload.methods.some((m) => m.name === "email.send"), "email family visible offline");
+  h.server.stop();
+});
+
+test("tools/call: UNAUTHORIZED error frame maps to isError + denied audit row", async () => {
+  const agentRoot = mkdtempSync(join(tmpdir(), "mcp-audit-"));
+  const h = harness({ orgConfig: {}, agentRoot });
+  const r = await h.request("tools/call", { name: "org_directory", arguments: {} });
+  assert.equal(r.result.isError, true);
+  assert.match(r.result.content[0].text, /UNAUTHORIZED/);
+  const rows = readAuditRows(agentRoot);
+  assert.equal(rows.length, 1);
+  assert.equal(rows[0].tool, "org_directory");
+  assert.equal(rows[0].denied, true, "UNAUTHORIZED audits as denied");
+  assert.match(rows[0].session_id, /^mcp:\d+$/);
+  rmSync(agentRoot, { recursive: true, force: true });
+  h.server.stop();
+});
+
+test("tools/call unknown tool: error result + denied audit row (never a protocol error)", async () => {
+  const agentRoot = mkdtempSync(join(tmpdir(), "mcp-audit-"));
+  const h = harness({ agentRoot });
+  const r = await h.request("tools/call", { name: "made_up_tool", arguments: {} });
+  assert.equal(r.result.isError, true);
+  assert.match(r.result.content[0].text, /unknown tool/);
+  const rows = readAuditRows(agentRoot);
+  assert.equal(rows.length, 1);
+  assert.equal(rows[0].denied, true);
+  rmSync(agentRoot, { recursive: true, force: true });
+  h.server.stop();
+});
+
+test("tools/call: one audit row per invocation, completed status, mcp session id", async () => {
+  const agentRoot = mkdtempSync(join(tmpdir(), "mcp-audit-"));
+  const h = harness({ agentRoot, fetchImpl: fakeFetch({ ok: true, result: { members: [] } }) });
+  await h.request("tools/call", { name: "org_directory", arguments: {} });
+  await h.request("tools/call", { name: "org_describe", arguments: {} });
+  const rows = readAuditRows(agentRoot);
+  assert.equal(rows.length, 2, "one row per tools/call");
+  assert.ok(rows.every((r) => r.session_id.startsWith("mcp:")));
+  assert.ok(rows.every((r) => r.status === "completed" && r.denied === false));
+  rmSync(agentRoot, { recursive: true, force: true });
+  h.server.stop();
+});
+
+test("org_rpc unknown method: rejected without network, isError result", async () => {
+  const fetchImpl = fakeFetch();
+  const h = harness({ fetchImpl });
+  const r = await h.request("tools/call", { name: "org_rpc", arguments: { method: "no.such" } });
+  assert.equal(r.result.isError, true);
+  assert.match(r.result.content[0].text, /unknown method/);
+  assert.equal(fetchImpl.calls.length, 0, "no network for an invalid method");
+  h.server.stop();
+});
+
+test("send-gate parity: messaging_send + email_send + org_rpc{messaging.send} all screened", async () => {
+  const screened = [];
+  const screenImpl = async (o) => { screened.push(`${o.channel}:${o.recipient}`); return { allow: true }; };
+  const h = harness({ fetchImpl: fakeFetch({ ok: true, result: { id: "x" } }), screenImpl });
+  await h.request("tools/call", { name: "messaging_send", arguments: { channelId: "C1", body: "a" } });
+  await h.request("tools/call", { name: "email_send", arguments: { to: ["e@x.com"], subject: "s", text: "b" } });
+  await h.request("tools/call", { name: "org_rpc", arguments: { method: "messaging.send", params: { channelId: "C2", body: "c" } } });
+  assert.equal(screened.length, 3, "all three outbound lanes screened");
+  h.server.stop();
+});
+
+test("200 KB truncation: an oversized chain read is capped with the marker", async () => {
+  const huge = { ok: true, result: { blob: "y".repeat(MAX_RESULT_BYTES + 10_000) } };
+  const h = harness({ fetchImpl: fakeFetch(huge) });
+  const r = await h.request("tools/call", { name: "messaging_channels", arguments: {} });
+  const text = r.result.content[0].text;
+  assert.ok(Buffer.byteLength(text, "utf8") < MAX_RESULT_BYTES + 200);
+  assert.match(text, /…truncated/);
+  h.server.stop();
+});
+
+test("escape-hatch redaction: a token-shaped value in an org_rpc result is masked", async () => {
+  const h = harness({ fetchImpl: fakeFetch({ ok: true, result: { token: "nlk_supersecret", note: "fine" } }) });
+  const r = await h.request("tools/call", { name: "org_rpc", arguments: { method: "member.get", params: { memberId: "m" } } });
+  const text = r.result.content[0].text;
+  assert.ok(!text.includes("nlk_supersecret"), "credential-shaped field redacted");
+  assert.match(text, /fine/);
+  h.server.stop();
+});
+
+function readAuditRows(agentRoot) {
+  const dir = join(agentRoot, "logs", "audit");
+  if (!existsSync(dir)) return [];
+  const rows = [];
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith("-actions.jsonl")) continue;
+    for (const line of readFileSync(join(dir, f), "utf8").split("\n")) {
+      if (line.trim()) rows.push(JSON.parse(line));
+    }
+  }
+  return rows;
+}
+
+// ── end-to-end: reference server + the real bin over spawned stdio ─────────
+
+test("e2e: real bin against the services/cohort reference server (initialize → tools/list → org_directory)", { timeout: 30_000 }, async () => {
+  const ADMIN_TOKEN = "cohort-mcp-e2e-admin";
+  const { openDb } = await import(`file://${join(REPO_ROOT, "services/cohort/src/storage.mjs")}`);
+  const { buildRegistry } = await import(`file://${join(REPO_ROOT, "services/cohort/src/method-registry.mjs")}`);
+  const { createServer } = await import(`file://${join(REPO_ROOT, "services/cohort/src/server.mjs")}`);
+
+  const dbDir = mkdtempSync(join(tmpdir(), "cohort-mcp-e2e-"));
+  const db = openDb(join(dbDir, "cohort.db"));
+  const registry = await buildRegistry();
+  const srv = await createServer({ db, registry, config: { adminToken: ADMIN_TOKEN, sweeper: false } });
+  const bound = await srv.listen(0);
+
+  const agentRoot = mkdtempSync(join(tmpdir(), "mcp-e2e-root-"));
+  const child = spawn(process.execPath, [join(REPO_ROOT, "bin", "cohort-mcp.mjs")], {
+    env: {
+      ...process.env,
+      COHORT_BASE: bound.url,
+      COHORT_API_TOKEN: ADMIN_TOKEN,
+      COHORT_AGENT_ROOT: agentRoot,
+      COHORT_ORG_ID: "",
+      COHORT_TOKEN: "",
+      COHORT_API_KEY: "",
+    },
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+
+  const frames = [];
+  let buf = "";
+  child.stdout.on("data", (c) => {
+    buf += c.toString("utf8");
+    let idx;
+    while ((idx = buf.indexOf("\n")) >= 0) {
+      const line = buf.slice(0, idx); buf = buf.slice(idx + 1);
+      if (line.trim()) frames.push(JSON.parse(line));
+    }
+  });
+  const waitFor = (id) => new Promise((resolve, reject) => {
+    const t = setInterval(() => {
+      const f = frames.find((x) => x.id === id);
+      if (f) { clearInterval(t); clearTimeout(dead); resolve(f); }
+    }, 10);
+    const dead = setTimeout(() => { clearInterval(t); reject(new Error(`no response for id ${id}`)); }, 15_000);
+  });
+  const send = (id, method, params) => child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
+
+  try {
+    send(1, "initialize", { protocolVersion: MCP_PROTOCOL_VERSION, capabilities: {}, clientInfo: { name: "e2e" } });
+    const init = await waitFor(1);
+    assert.equal(init.result.protocolVersion, MCP_PROTOCOL_VERSION);
+
+    send(2, "tools/list", {});
+    const list = await waitFor(2);
+    assert.ok(list.result.tools.length >= 28, "tool surface served through the real bin");
+
+    send(3, "tools/call", { name: "org_directory", arguments: {} });
+    const dir = await waitFor(3);
+    assert.equal(dir.result.isError, false, `org_directory ok: ${dir.result.content?.[0]?.text?.slice(0, 200)}`);
+
+    send(4, "tools/call", { name: "org_rpc", arguments: { method: "not.real" } });
+    const bad = await waitFor(4);
+    assert.equal(bad.result.isError, true, "escape hatch validates against the protocol over the wire");
+  } finally {
+    child.kill("SIGTERM");
+    await srv.close();
+    db.close();
+    rmSync(dbDir, { recursive: true, force: true });
+    rmSync(agentRoot, { recursive: true, force: true });
+  }
+});