Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

8.2 KB
Raw Blame
export interface JsonRpcRequest {
  jsonrpc: "2.0";
  id?: string | number;
  method: string;
  params?: Record<string, unknown>;
}

export interface JsonRpcResponse {
  jsonrpc: "2.0";
  id: string | number | null;
  result?: unknown;
  error?: { code: number; message: string; data?: unknown };
}

export type RequestHandler = (
  method: string,
  params: Record<string, unknown>,
) => Promise<unknown>;

let activeStdioTransports = 0;

export class JsonRpcError extends Error {
  constructor(public readonly code: number, message: string) {
    super(message);
    this.name = "JsonRpcError";
  }
}

export interface StdioMessageParser {
  push: (chunk: Buffer | string) => void;
  isFramed: () => boolean;
}

// JSON-RPC 2.0 notifications are messages without an `id` field. The spec
// (and the MCP transport contract) requires the server to NOT send a
// response for notifications. Some clients tolerate spurious responses;
// stricter clients (e.g. Codex CLI) treat them as protocol violations and
// close the transport. See agentmemory#129.
function isNotification(req: JsonRpcRequest): boolean {
  return req.id === undefined || req.id === null;
}

// Per JSON-RPC 2.0 §4, a valid request id must be a String, Number, or Null
// (Null is technically only allowed in responses; in requests, omitting id
// is the convention for notifications, which we treat the same as null).
// Any other runtime type (object, array, boolean) is an Invalid Request.
function isValidId(id: unknown): id is string | number | null | undefined {
  return (
    id === undefined ||
    id === null ||
    typeof id === "string" ||
    typeof id === "number"
  );
}

// Exported for unit tests so the line-handling logic is exercised
// independently of process.stdin / process.stdout.
export async function processLine(
  line: string,
  handler: RequestHandler,
  writeOut: (response: JsonRpcResponse) => void,
  writeErr: (msg: string) => void = (msg) => process.stderr.write(msg),
): Promise<void> {
  const trimmed = line.trim();
  if (!trimmed) return;

  let parsed: unknown;
  try {
    parsed = JSON.parse(trimmed);
  } catch {
    writeOut({
      jsonrpc: "2.0",
      id: null,
      error: { code: -32700, message: "Parse error" },
    });
    return;
  }

  const request = parsed as JsonRpcRequest;
  const rawId = (request as { id?: unknown } | null)?.id;

  // Invalid request shape (missing/wrong jsonrpc, non-string method).
  if (
    !request ||
    typeof request !== "object" ||
    request.jsonrpc !== "2.0" ||
    typeof request.method !== "string"
  ) {
    // Echo the id back only if it's a valid string/number. Notifications
    // (missing/null id) and malformed ids both drop silently — we don't
    // want to respond to something that could be a notification, and we
    // can't invent an id for a malformed one.
    if (typeof rawId === "string" || typeof rawId === "number") {
      writeOut({
        jsonrpc: "2.0",
        id: rawId,
        error: { code: -32600, message: "Invalid Request" },
      });
    }
    return;
  }

  // Request shape is valid but id may still be of the wrong type
  // (object, array, boolean). Per the spec, that's an Invalid Request.
  // Respond with id: null because we can't safely echo a non-JSON-RPC id.
  if (!isValidId(rawId)) {
    writeOut({
      jsonrpc: "2.0",
      id: null,
      error: { code: -32600, message: "Invalid Request: id must be string, number, or null" },
    });
    return;
  }

  const notification = isNotification(request);

  try {
    const result = await handler(request.method, request.params || {});
    if (notification) return;
    writeOut({
      jsonrpc: "2.0",
      id: request.id as string | number,
      result,
    });
  } catch (err) {
    if (notification) {
      writeErr(
        `[mcp-transport] notification handler error for ${request.method}: ${
          err instanceof Error ? err.message : String(err)
        }\n`,
      );
      return;
    }
    writeOut({
      jsonrpc: "2.0",
      id: request.id as string | number,
      error: {
        code: err instanceof JsonRpcError ? err.code : -32603,
        message: err instanceof Error ? err.message : String(err),
      },
    });
  }
}

function findHeaderEnd(buffer: Buffer): { headerEnd: number; bodyStart: number } | null {
  const crlf = buffer.indexOf("\r\n\r\n");
  const lf = buffer.indexOf("\n\n");
  if (crlf === -1 && lf === -1) return null;
  if (crlf !== -1 && (lf === -1 || crlf <= lf)) {
    return { headerEnd: crlf, bodyStart: crlf + 4 };
  }
  return { headerEnd: lf, bodyStart: lf + 2 };
}

function parseContentLength(header: string): number | null {
  for (const line of header.split(/\r?\n/)) {
    const match = line.match(/^content-length:\s*(\d+)\s*$/i);
    if (match) return Number(match[1]);
  }
  return null;
}

export function formatResponse(
  response: JsonRpcResponse,
  framed: boolean,
): string | Buffer[] {
  const body = JSON.stringify(response);
  if (!framed) return `${body}\n`;
  const bytes = Buffer.from(body, "utf8");
  return [Buffer.from(`Content-Length: ${bytes.length}\r\n\r\n`, "ascii"), bytes];
}

export function createMessageParser(
  onMessage: (message: string) => void,
  writeErr: (msg: string) => void = (msg) => process.stderr.write(msg),
): StdioMessageParser {
  let buffer = Buffer.alloc(0);
  let framed = false;

  function processBuffer(): void {
    while (buffer.length > 0) {
      if (buffer[0] === 10 || buffer[0] === 13) {
        buffer = buffer.subarray(1);
        continue;
      }

      const preview = buffer.toString("ascii", 0, Math.min(buffer.length, 32));
      if (/^content-length:/i.test(preview)) {
        const header = findHeaderEnd(buffer);
        if (!header) return;

        const headerText = buffer.subarray(0, header.headerEnd).toString("ascii");
        const contentLength = parseContentLength(headerText);
        if (contentLength === null) {
          writeErr("[mcp-transport] missing Content-Length header\n");
          buffer = buffer.subarray(header.bodyStart);
          continue;
        }

        const messageEnd = header.bodyStart + contentLength;
        if (buffer.length < messageEnd) return;

        framed = true;
        const message = buffer.subarray(header.bodyStart, messageEnd).toString("utf8");
        buffer = buffer.subarray(messageEnd);
        onMessage(message);
        continue;
      }

      const newline = buffer.indexOf(10);
      if (newline === -1) return;
      const line = buffer
        .subarray(0, newline)
        .toString("utf8")
        .replace(/\r$/, "");
      buffer = buffer.subarray(newline + 1);
      onMessage(line);
    }
  }

  return {
    push(chunk) {
      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, "utf8");
      buffer = Buffer.concat([buffer, bytes]);
      processBuffer();
    },
    isFramed() {
      return framed;
    },
  };
}

export function createStdioTransport(handler: RequestHandler): {
  start: () => void;
  stop: () => void;
} {
  let parser: StdioMessageParser | null = null;
  let queue = Promise.resolve();
  let active = false;

  const writeResponse = (response: JsonRpcResponse) => {
    const formatted = formatResponse(response, parser?.isFramed() ?? false);
    if (typeof formatted === "string") {
      process.stdout.write(formatted);
      return;
    }
    for (const chunk of formatted) {
      process.stdout.write(chunk);
    }
  };

  const onData = (chunk: Buffer) => parser?.push(chunk);

  return {
    start() {
      if (active) return;
      active = true;
      activeStdioTransports += 1;
      process.env["AGENTMEMORY_MCP_STDIO__"] = "1";
      parser = createMessageParser((message) => {
        queue = queue.then(() => processLine(message, handler, writeResponse));
        void queue.catch((err) => {
          process.stderr.write(
            `[mcp-transport] request processing failed: ${
              err instanceof Error ? err.message : String(err)
            }\n`,
          );
        });
      });
      process.stdin.on("data", onData);
    },
    stop() {
      process.stdin.off("data", onData);
      if (active) {
        active = false;
        activeStdioTransports -= 1;
        if (activeStdioTransports === 0) {
          delete process.env["AGENTMEMORY_MCP_STDIO__"];
        }
      }
      parser = null;
    },
  };
}