@cohortapp/agent-sdk 2.3.0

package/lib/mcp/server.mjs

@@ -0,0 +1,328 @@
+/**
+ * lib/mcp/server.mjs — the Cohort org MCP server (stdio, hand-rolled).
+ *
+ * A deliberately tiny Model Context Protocol server: newline-delimited JSON-RPC
+ * 2.0 over injected readable/writable streams, tools-only (no resources /
+ * prompts / sampling). Hand-rolled with Node builtins per the SDK's
+ * two-runtime-dep discipline — @modelcontextprotocol/sdk would drag in zod +
+ * a release treadmill for capabilities we do not use. If we ever need
+ * resources/prompts or an HTTP transport, adopt the SDK then: the tool table
+ * (lib/org/tool-surface.mjs) is transport-agnostic, so only this file changes.
+ *
+ * Contract:
+ *   - Requests handled: initialize, tools/list, tools/call, ping.
+ *     notifications/initialized (and any other notification) is tolerated
+ *     silently. Unknown request method → JSON-RPC -32601. Parse error → -32700.
+ *   - Version negotiation: prefer "2025-06-18"; when the client offers
+ *     "2025-03-26" or "2024-11-05", echo the client's version (the tools-only
+ *     subset is identical across all three).
+ *   - STDOUT CARRIES PROTOCOL FRAMES ONLY. Every log line goes to stderr via
+ *     the injected `log` — a single stray stdout write corrupts the stream
+ *     (enforced by a stdout-purity test).
+ *   - Governance parity (spec §1.5b): one audit row per tools/call is appended
+ *     to logs/audit/<date>-actions.jsonl under the resolved agent root, via the
+ *     SAME appendActionAudit the native executor uses (session_id "mcp:<pid>",
+ *     denied:true on unknown-tool + UNAUTHORIZED frames). Fail-open: logging
+ *     can never break the call. The send-gate screen itself lives inside
+ *     executeOrgTool, shared with the native plane.
+ *   - Results: content [{type:"text", text: JSON}] with isError on !frame.ok,
+ *     serialized results capped at 200 KB with a truncation marker; escape-
+ *     hatch (org_rpc/org_read) results pass through lib/security/redact so a
+ *     token can never appear in a tool result.
+ *
+ * @module lib/mcp/server
+ */
+
+"use strict";
+
+import { createInterface } from "node:readline";
+import { readFileSync } from "node:fs";
+import {
+  getOrgTools,
+  isOrgTool,
+  executeOrgTool,
+  resolveOrgToolConfig,
+} from "../org/tool-surface.mjs";
+import { methodDef } from "../org/protocol.mjs";
+import { REDACTED, isSensitiveParamName, maskTextString } from "../security/redact.mjs";
+import { appendActionAudit } from "../action-executor.js";
+
+/**
+ * Deep, key-aware redaction for escape-hatch results (belt-and-braces §1.3):
+ * any value under a credential-named key (token/secret/apikey/…) is replaced
+ * with the redaction marker, and every string additionally passes maskText's
+ * secret-pattern scrubber. Cycles tolerated; never throws.
+ */
+export function redactDeep(value, seen = new WeakSet()) {
+  if (typeof value === "string") return maskTextString(value);
+  if (value === null || typeof value !== "object") return value;
+  if (seen.has(value)) return value;
+  seen.add(value);
+  if (Array.isArray(value)) return value.map((v) => redactDeep(v, seen));
+  const out = {};
+  for (const k of Object.keys(value)) {
+    out[k] = isSensitiveParamName(k) ? REDACTED : redactDeep(value[k], seen);
+  }
+  return out;
+}
+
+/** Preferred MCP protocol revision; older tools-only revisions are echoed. */
+export const MCP_PROTOCOL_VERSION = "2025-06-18";
+const ECHOED_VERSIONS = new Set(["2025-06-18", "2025-03-26", "2024-11-05"]);
+
+/** Serialized tool-result cap (chain reads can be large). */
+export const MAX_RESULT_BYTES = 200 * 1024;
+
+/** JSON-RPC error codes. */
+const PARSE_ERROR = -32700;
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+const INTERNAL_ERROR = -32603;
+
+/**
+ * Shape one tool-table entry as an MCP tools/list item: the Claude-shaped
+ * `input_schema` republishes verbatim as `inputSchema`; annotations derive
+ * from the table + the vendored protocol (readOnlyHint for reads,
+ * idempotentHint from methodDef().idempotent, destructiveHint on the org_rpc
+ * escape hatch, openWorldHint:false everywhere — the org surface is closed).
+ */
+export function toMcpTool(def) {
+  const annotations = { title: def.title, openWorldHint: false };
+  if (def.access === "read") annotations.readOnlyHint = true;
+  if (def.binding && def.binding.kind === "rpc") {
+    const m = methodDef(def.binding.method);
+    if (m && m.idempotent) annotations.idempotentHint = true;
+  }
+  if (def.name === "org_rpc") annotations.destructiveHint = true;
+  return {
+    name: def.name,
+    title: def.title,
+    description: def.description,
+    inputSchema: def.input_schema,
+    annotations,
+  };
+}
+
+/** Truncate a serialized result to MAX_RESULT_BYTES with an explicit marker. */
+export function capResultText(text) {
+  if (typeof text !== "string") text = String(text ?? "");
+  if (Buffer.byteLength(text, "utf8") <= MAX_RESULT_BYTES) return text;
+  const buf = Buffer.from(text, "utf8").subarray(0, MAX_RESULT_BYTES);
+  return `${buf.toString("utf8")}\n…truncated (result exceeded ${MAX_RESULT_BYTES} bytes)`;
+}
+
+/**
+ * Create the MCP server. Pure wiring — nothing global; attach by passing the
+ * process streams. Returns { start, stop, handleLine } (handleLine exported
+ * for in-process tests).
+ *
+ * @param {object} o
+ * @param {import("node:stream").Readable} o.input
+ * @param {import("node:stream").Writable} o.output
+ * @param {object} [o.orgConfig]   pre-loaded org config object (else disk/env)
+ * @param {string} [o.agentRoot]
+ * @param {Function} [o.fetchImpl]
+ * @param {(lvl:string,msg:string)=>void} [o.log]  stderr logger (NEVER stdout)
+ * @param {Function} [o.screenImpl]  injected send-gate (tests)
+ * @param {Function} [o.appendAudit] injected audit writer (tests)
+ * @param {boolean} [o.emailAvailable] override the email-family gate (tests)
+ */
+export function createMcpServer(o = {}) {
+  const log = typeof o.log === "function" ? o.log : (lvl, m) => process.stderr.write(`[cohort-mcp:${lvl}] ${m}\n`);
+  const appendAudit = typeof o.appendAudit === "function" ? o.appendAudit : appendActionAudit;
+  const cfg = resolveOrgToolConfig({ agentRoot: o.agentRoot, orgConfig: o.orgConfig });
+  const sessionId = `mcp:${process.pid}`;
+  let initializedVersion = null;
+  let rl = null;
+
+  if (!cfg.token) {
+    log(
+      "warn",
+      "no org credential resolved — org_describe works offline; network tools will return " +
+        "UNAUTHORIZED until COHORT_API_TOKEN is set (or run `cohort setup --only org`)",
+    );
+  }
+
+  function writeFrame(frame) {
+    try {
+      o.output.write(`${JSON.stringify(frame)}\n`);
+    } catch (err) {
+      log("error", `write failed: ${err && err.message}`);
+    }
+  }
+
+  function reply(id, result) {
+    writeFrame({ jsonrpc: "2.0", id, result });
+  }
+  function replyError(id, code, message) {
+    writeFrame({ jsonrpc: "2.0", id, error: { code, message } });
+  }
+
+  function activeTools() {
+    return getOrgTools(o.emailAvailable === undefined ? {} : { emailAvailable: o.emailAvailable });
+  }
+
+  async function handleToolsCall(id, params) {
+    const name = params && typeof params.name === "string" ? params.name : "";
+    const args = (params && params.arguments && typeof params.arguments === "object" ? params.arguments : {}) || {};
+
+    // Unknown / inactive tool → error result (audited as denied).
+    const active = activeTools().some((t) => t.name === name);
+    if (!name || !isOrgTool(name) || !active) {
+      audit({ tool: name || "(none)", status: "denied", denied: true, input: args });
+      reply(id, {
+        content: [{ type: "text", text: `unknown tool: ${name || "(none)"}` }],
+        isError: true,
+      });
+      return;
+    }
+
+    const frame = await executeOrgTool(name, args, {
+      agentRoot: cfg.agentRoot,
+      orgConfig: o.orgConfig,
+      fetchImpl: o.fetchImpl,
+      screenImpl: o.screenImpl,
+      emailAvailable: o.emailAvailable,
+    });
+
+    const unauthorized = !frame.ok && frame.error && frame.error.code === "UNAUTHORIZED";
+    audit({
+      tool: name,
+      status: frame.ok ? "completed" : "failed",
+      denied: unauthorized,
+      input: args,
+    });
+
+    // Belt-and-braces: escape-hatch output passes through the redactor so a
+    // credential-shaped value can never surface in a tool result.
+    let payload = frame.ok ? (frame.result === undefined ? frame : frame.result) : frame;
+    if (name === "org_rpc" || name === "org_read") {
+      try {
+        payload = redactDeep(payload);
+      } catch {
+        /* redaction is best-effort; the server-side never returns tokens */
+      }
+    }
+
+    let text;
+    try {
+      text = JSON.stringify(payload ?? null, null, 2);
+    } catch {
+      text = String(payload);
+    }
+    reply(id, {
+      content: [{ type: "text", text: capResultText(text) }],
+      isError: !frame.ok,
+    });
+  }
+
+  /** Append one governance audit row (fail-open; mirrors the native plane). */
+  function audit({ tool, status, denied, input }) {
+    try {
+      appendAudit(cfg.agentRoot, { tool, status, denied, input, sessionId });
+    } catch {
+      /* logging can never break the call */
+    }
+  }
+
+  async function dispatch(msg) {
+    const { id, method, params } = msg;
+    const isNotification = id === undefined || id === null;
+
+    if (method === "notifications/initialized" || (typeof method === "string" && method.startsWith("notifications/"))) {
+      return; // tolerated silently, no response
+    }
+    if (isNotification) return; // any other notification: ignore
+
+    switch (method) {
+      case "initialize": {
+        const offered = params && typeof params.protocolVersion === "string" ? params.protocolVersion : "";
+        initializedVersion = ECHOED_VERSIONS.has(offered) ? offered : MCP_PROTOCOL_VERSION;
+        reply(id, {
+          protocolVersion: initializedVersion,
+          capabilities: { tools: {} },
+          serverInfo: { name: "cohort-mcp", title: "Cohort org server", version: serverVersion() },
+        });
+        return;
+      }
+      case "ping":
+        reply(id, {});
+        return;
+      case "tools/list":
+        reply(id, { tools: activeTools().map(toMcpTool) });
+        return;
+      case "tools/call":
+        if (!params || typeof params !== "object") {
+          replyError(id, INVALID_PARAMS, "tools/call: params required");
+          return;
+        }
+        await handleToolsCall(id, params);
+        return;
+      default:
+        replyError(id, METHOD_NOT_FOUND, `method not found: ${method}`);
+    }
+  }
+
+  async function handleLine(line) {
+    const trimmed = String(line || "").trim();
+    if (!trimmed) return;
+    let msg;
+    try {
+      msg = JSON.parse(trimmed);
+    } catch {
+      replyError(null, PARSE_ERROR, "parse error");
+      return;
+    }
+    if (!msg || typeof msg !== "object" || typeof msg.method !== "string") {
+      // A response frame or malformed request: ignore responses, error requests.
+      if (msg && msg.id !== undefined && msg.method === undefined && msg.result === undefined && msg.error === undefined) {
+        replyError(msg.id, INVALID_PARAMS, "invalid request");
+      }
+      return;
+    }
+    try {
+      await dispatch(msg);
+    } catch (err) {
+      log("error", `dispatch failed: ${err && err.message}`);
+      if (msg.id !== undefined && msg.id !== null) {
+        replyError(msg.id, INTERNAL_ERROR, `internal error: ${err && err.message}`);
+      }
+    }
+  }
+
+  function start() {
+    rl = createInterface({ input: o.input, crlfDelay: Infinity });
+    // Serialise handling so responses keep request order (MCP clients pair by
+    // id, but ordered frames make transcripts deterministic + testable).
+    let chain = Promise.resolve();
+    rl.on("line", (line) => {
+      chain = chain.then(() => handleLine(line)).catch((err) => log("error", `line failed: ${err && err.message}`));
+    });
+    rl.on("close", () => log("info", "stdin closed — server idle"));
+    log("info", `cohort-mcp serving ${activeTools().length} tools (base ${cfg.base}, token ${cfg.token ? "present" : "ABSENT"})`);
+    return { rl };
+  }
+
+  function stop() {
+    try {
+      rl?.close();
+    } catch {
+      /* */
+    }
+  }
+
+  return { start, stop, handleLine, _config: cfg };
+}
+
+/** The SDK package version (best-effort; used in serverInfo). */
+function serverVersion() {
+  try {
+    // package.json sits two levels up from lib/mcp/.
+    const url = new URL("../../package.json", import.meta.url);
+    return JSON.parse(readFileSync(url, "utf8")).version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+export default { createMcpServer, toMcpTool, capResultText, MCP_PROTOCOL_VERSION, MAX_RESULT_BYTES };