@seanhogg/builderforce-memory-mcp 2026.6.18

package/src/backend.ts

@@ -0,0 +1,66 @@
+/**
+ * MemoryBackend — the storage seam every transport is written against.
+ *
+ * The MCP tools (src/tools.ts) and all three transports (SDK / stdio / HTTP)
+ * depend ONLY on this interface, never on a concrete store. Ship the local
+ * `MemoryStoreBackend` (IndexedDB via @seanhogg/builderforce-memory) today; drop in a
+ * networked builderforce.ai adapter later with zero changes to the tools or
+ * transports.
+ */
+
+/** A single recalled memory, normalised across backends. */
+export interface RecallHit {
+    /** Stable identifier for the memory. */
+    key: string;
+    /** The stored value. */
+    content: string;
+    /**
+     * Optional relevance score (higher = closer). Semantic backends that expose
+     * ranking can populate this; the local MemoryStore ranks but does not surface
+     * a score, so it is left undefined and recall order carries the signal.
+     */
+    score?: number;
+    /** Tags for grouping/filtering. */
+    tags?: string[];
+    /** Importance weight 0–1. */
+    importance?: number;
+    /** Unix-ms write time. */
+    timestamp?: number;
+}
+
+/** Arguments for writing a memory. */
+export interface RememberInput {
+    key: string;
+    content: string;
+    tags?: string[];
+    /** Importance weight 0–1. */
+    importance?: number;
+    /** Time-to-live in milliseconds. */
+    ttlMs?: number;
+}
+
+/**
+ * The minimal capability surface the MCP layer needs. Deliberately small —
+ * the token-saving design exposes recall-on-demand, not a "dump everything"
+ * call, so this interface has no `recallAll`.
+ */
+export interface MemoryBackend {
+    /**
+     * Semantic top-K recall. Backends with an embedding model (the SSM
+     * runtime) should use it; lexical fallback is acceptable. `topK` is already
+     * clamped by the caller — the backend may return fewer, never more.
+     */
+    recall(query: string, topK: number): Promise<RecallHit[]>;
+
+    /** Exact lookup by key. Returns undefined when absent or expired. */
+    get(key: string): Promise<RecallHit | undefined>;
+
+    /** All non-expired entries carrying `tag`, capped to `limit`. */
+    recallByTag(tag: string, limit: number): Promise<RecallHit[]>;
+
+    /** Store or overwrite a memory. Optional — read-only backends omit it. */
+    remember?(input: RememberInput): Promise<void>;
+
+    /** Delete a memory by key. Optional — read-only backends omit it. */
+    forget?(key: string): Promise<void>;
+}

package/src/backends/memory-store.ts

@@ -0,0 +1,217 @@
+/**
+ * MemoryStoreBackend — local adapter mapping @seanhogg/builderforce-memory's MemoryStore
+ * onto the MemoryBackend seam.
+ *
+ * Recall quality: when an SSM runtime is supplied it is forwarded to
+ * `recallSimilar`, so recall uses SSM-embedding cosine similarity and improves
+ * as the model is adapted/distilled. With no runtime it transparently falls
+ * back to Jaccard word-overlap (still useful, just lexical).
+ */
+
+import type { MemoryBackend, RecallHit, RememberInput } from "../backend.js";
+
+// Structural views of the @seanhogg/builderforce-memory surface we use, so this package
+// type-checks without a hard dependency on the runtime package.
+interface MemoryEntryLike {
+    key: string;
+    content: string;
+    timestamp?: number;
+    tags?: string[];
+    importance?: number;
+}
+
+interface MemoryStoreLike {
+    remember(key: string, content: string, opts?: { ttlMs?: number; tags?: string[]; importance?: number }): Promise<void>;
+    recall(key: string): Promise<MemoryEntryLike | undefined>;
+    recallAll(): Promise<MemoryEntryLike[]>;
+    recallByTag(tag: string): Promise<MemoryEntryLike[]>;
+    recallSimilar(query: string, topK: number, runtime?: unknown): Promise<MemoryEntryLike[]>;
+    forget(key: string): Promise<void>;
+}
+
+function toHit(e: MemoryEntryLike): RecallHit {
+    return {
+        key: e.key,
+        content: e.content,
+        tags: e.tags,
+        importance: e.importance,
+        timestamp: e.timestamp,
+    };
+}
+
+export class MemoryStoreBackend implements MemoryBackend {
+    constructor(
+        private readonly store: MemoryStoreLike,
+        /** Optional SSMRuntime; enables embedding-based recall when present. */
+        private readonly runtime?: unknown,
+    ) {}
+
+    async recall(query: string, topK: number): Promise<RecallHit[]> {
+        const entries = await this.store.recallSimilar(query, topK, this.runtime);
+        return entries.map(toHit);
+    }
+
+    async get(key: string): Promise<RecallHit | undefined> {
+        const e = await this.store.recall(key);
+        return e ? toHit(e) : undefined;
+    }
+
+    async recallByTag(tag: string, limit: number): Promise<RecallHit[]> {
+        const entries = await this.store.recallByTag(tag);
+        return entries.slice(0, limit).map(toHit);
+    }
+
+    async remember(input: RememberInput): Promise<void> {
+        await this.store.remember(input.key, input.content, {
+            ttlMs: input.ttlMs,
+            tags: input.tags,
+            importance: input.importance,
+        });
+    }
+
+    async forget(key: string): Promise<void> {
+        await this.store.forget(key);
+    }
+}
+
+/** Options for {@link createLocalMemoryStoreBackend}. */
+export interface LocalBackendOptions {
+    /** IndexedDB database name. Defaults to MemoryStore's own default ('ssmjs'). */
+    dbName?: string;
+    /**
+     * Optional SSMRuntime for embedding-based recall. Omit for lexical (Jaccard)
+     * recall. In the agent-runtime, pass `ssmMemoryService.runtime` here to reuse
+     * the already-loaded hippocampus instead of standing up a second model.
+     */
+    runtime?: unknown;
+    /**
+     * Absolute path to a JSON file that mirrors the store to disk. Without it the
+     * store is purely in-memory (fake-indexeddb) and evaporates when the process
+     * exits — fine for a long-lived server, fatal for a per-session subprocess
+     * (e.g. an MCP stdio client that respawns the server each launch).
+     *
+     * When set, the store is hydrated from the file on creation and re-snapshotted
+     * after every remember/forget, giving durable cross-process memory. TTLs are
+     * dropped on persist: the snapshot is the durable long-term tier.
+     */
+    persistFile?: string;
+}
+
+/** The on-disk snapshot shape — a flat array of durable entries. */
+interface SnapshotEntry {
+    key: string;
+    content: string;
+    tags?: string[];
+    importance?: number;
+}
+
+type FsLike = {
+    readFileSync(path: string, enc: "utf8"): string;
+    writeFileSync(path: string, data: string): void;
+    mkdirSync(path: string, opts: { recursive: boolean }): void;
+    existsSync(path: string): boolean;
+};
+type PathLike = { dirname(p: string): string };
+
+/**
+ * Wraps a MemoryStoreBackend so every write is mirrored to a JSON file, and
+ * hydrates that file back into the store on boot. This is what turns a respawned
+ * stdio subprocess into a persistent memory: the store itself is in-memory, the
+ * file is the source of truth across process lifetimes.
+ */
+class DiskPersistedBackend implements MemoryBackend {
+    constructor(
+        private readonly inner: MemoryStoreBackend,
+        private readonly store: MemoryStoreLike,
+        private readonly file: string,
+        private readonly fs: FsLike,
+    ) {}
+
+    recall(query: string, topK: number): Promise<RecallHit[]> {
+        return this.inner.recall(query, topK);
+    }
+    get(key: string): Promise<RecallHit | undefined> {
+        return this.inner.get(key);
+    }
+    recallByTag(tag: string, limit: number): Promise<RecallHit[]> {
+        return this.inner.recallByTag(tag, limit);
+    }
+
+    async remember(input: RememberInput): Promise<void> {
+        await this.inner.remember(input);
+        await this.snapshot();
+    }
+
+    async forget(key: string): Promise<void> {
+        await this.inner.forget(key);
+        await this.snapshot();
+    }
+
+    private async snapshot(): Promise<void> {
+        const entries = await this.store.recallAll();
+        const out: SnapshotEntry[] = entries.map((e) => ({
+            key: e.key,
+            content: e.content,
+            tags: e.tags,
+            importance: e.importance,
+        }));
+        this.fs.writeFileSync(this.file, JSON.stringify(out, null, 2));
+    }
+}
+
+/** Reads a snapshot file and replays it into the store as durable (no-TTL) entries. */
+async function hydrateFromDisk(store: MemoryStoreLike, file: string, fs: FsLike): Promise<void> {
+    if (!fs.existsSync(file)) return;
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    } catch {
+        // Corrupt/partial snapshot — start clean rather than crash the server.
+        return;
+    }
+    if (!Array.isArray(parsed)) return;
+    for (const raw of parsed as SnapshotEntry[]) {
+        if (!raw || typeof raw.key !== "string" || typeof raw.content !== "string") continue;
+        await store.remember(raw.key, raw.content, { tags: raw.tags, importance: raw.importance });
+    }
+}
+
+/**
+ * Builds a MemoryStoreBackend over a fresh MemoryStore, wiring fake-indexeddb in
+ * Node exactly as SsmMemoryService does. @seanhogg/builderforce-memory and fake-indexeddb
+ * are imported indirectly so they remain optional peers — a consumer that only
+ * wants a custom backend (or the HTTP thin-client) never has to install them.
+ */
+export async function createLocalMemoryStoreBackend(opts: LocalBackendOptions = {}): Promise<MemoryBackend> {
+    // Indirect import prevents the bundler/tsc from resolving optional peers.
+    const _import = (m: string): Promise<unknown> =>
+        // eslint-disable-next-line @typescript-eslint/no-implied-eval, no-new-func
+        new Function("m", "return import(m)")(m) as Promise<unknown>;
+
+    const memoryMod = (await _import("@seanhogg/builderforce-memory")) as { MemoryStore: new (o: unknown) => MemoryStoreLike };
+    const { MemoryStore } = memoryMod;
+
+    // IndexedDB shim for Node. In the browser the global is used automatically.
+    let idbFactory: unknown;
+    try {
+        const fake = (await _import("fake-indexeddb")) as { IDBFactory: new () => unknown };
+        idbFactory = new fake.IDBFactory();
+    } catch {
+        // Browser or a host that provides global indexedDB — MemoryStore handles it.
+    }
+
+    const store = new MemoryStore({ idbFactory, dbName: opts.dbName });
+    const backend = new MemoryStoreBackend(store, opts.runtime);
+
+    if (!opts.persistFile) return backend;
+
+    // Disk-mirror requested. node:fs/path are loaded indirectly so a browser
+    // bundle of this module never statically pulls in Node builtins.
+    const fs = (await _import("node:fs")) as FsLike;
+    const path = (await _import("node:path")) as PathLike;
+    const dir = path.dirname(opts.persistFile);
+    if (dir && !fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    await hydrateFromDisk(store, opts.persistFile, fs);
+    return new DiskPersistedBackend(backend, store, opts.persistFile, fs);
+}

package/src/bin/http.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * `builderforce-memory-mcp-http` — Streamable HTTP MCP server over the LOCAL
+ * MemoryStore. A reference host; in production builderforce.ai would mount
+ * createMemoryHttpHandler() against a shared/remote backend instead.
+ *
+ * Env:
+ *   PORT                          Listen port (default 8787).
+ *   BUILDERFORCE_MEMORY_TOKEN     Bearer token required on every request (recommended).
+ *   BUILDERFORCE_MEMORY_DB        IndexedDB database name.
+ *   BUILDERFORCE_MEMORY_READONLY  '1' to disable remember/forget tools.
+ */
+
+import http from "node:http";
+import { createLocalMemoryStoreBackend } from "../backends/memory-store.js";
+import { createMemoryHttpHandler } from "../transports/http.js";
+
+const backend = await createLocalMemoryStoreBackend({
+    dbName: process.env["BUILDERFORCE_MEMORY_DB"],
+});
+
+const handler = createMemoryHttpHandler(backend, {
+    authToken: process.env["BUILDERFORCE_MEMORY_TOKEN"],
+    writable: process.env["BUILDERFORCE_MEMORY_READONLY"] !== "1",
+});
+
+const port = Number(process.env["PORT"] ?? 8787);
+
+http.createServer((req, res) => {
+    void handler(req, res).catch((err) => {
+        if (!res.headersSent) res.writeHead(500, { "content-type": "application/json" });
+        res.end(JSON.stringify({ error: String(err) }));
+    });
+}).listen(port, () => {
+    process.stderr.write(`[builderforce-memory-mcp-http] listening on :${port}\n`);
+});

package/src/bin/stdio.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * `builderforce-memory-mcp` — stdio MCP server over the LOCAL MemoryStore.
+ *
+ * Env:
+ *   BUILDERFORCE_MEMORY_DB        IndexedDB database name (default: MemoryStore default).
+ *   BUILDERFORCE_MEMORY_READONLY  '1' to disable remember/forget tools.
+ *   BUILDERFORCE_MEMORY_FILE      Absolute path to a JSON snapshot. When set, memory
+ *                                 persists across process restarts — REQUIRED for an
+ *                                 MCP client that respawns this server each session
+ *                                 (otherwise fake-indexeddb loses everything on exit).
+ *
+ * Recall is lexical (Jaccard) here — this headless binary does not stand up the
+ * SSM runtime/GPU. For SSM-embedding recall, embed the package in-process and
+ * pass `runtime` to createLocalMemoryStoreBackend (see README).
+ */
+
+import { createLocalMemoryStoreBackend } from "../backends/memory-store.js";
+import { runStdio } from "../transports/stdio.js";
+
+const backend = await createLocalMemoryStoreBackend({
+    dbName: process.env["BUILDERFORCE_MEMORY_DB"],
+    persistFile: process.env["BUILDERFORCE_MEMORY_FILE"],
+});
+
+await runStdio(backend, { writable: process.env["BUILDERFORCE_MEMORY_READONLY"] !== "1" });

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * @seanhogg/builderforce-memory-mcp — expose @seanhogg/builderforce-memory to MCP clients.
+ *
+ * One token-saving tool core over a pluggable MemoryBackend, three transports:
+ *   - createMemoryMcpServer  → in-process Claude Agent SDK (type:"sdk")
+ *   - runStdio               → stdio subprocess (any language)
+ *   - createMemoryHttpHandler→ Streamable HTTP (multi-tenant / networked)
+ */
+
+// ── Seam ────────────────────────────────────────────────────────────────────
+export type { MemoryBackend, RecallHit, RememberInput } from "./backend.js";
+
+// ── Local backend (IndexedDB via @seanhogg/builderforce-memory) ────────────────────────
+export { MemoryStoreBackend, createLocalMemoryStoreBackend } from "./backends/memory-store.js";
+export type { LocalBackendOptions } from "./backends/memory-store.js";
+
+// ── Tool core ─────────────────────────────────────────────────────────────────
+export { buildMemoryTools } from "./tools.js";
+export type { MemoryTool, MemoryToolsOptions, ToolResult } from "./tools.js";
+
+// ── Transports ──────────────────────────────────────────────────────────────
+export { createMemoryMcpServer } from "./transports/sdk.js";
+export type { SdkServerOptions, SdkMcpServerConfig } from "./transports/sdk.js";
+
+export { buildMcpServer } from "./transports/mcp-server.js";
+export type { McpServerOptions } from "./transports/mcp-server.js";
+
+export { runStdio } from "./transports/stdio.js";
+
+export { createMemoryHttpHandler } from "./transports/http.js";
+export type { HttpHandlerOptions } from "./transports/http.js";

package/src/tools.ts

@@ -0,0 +1,214 @@
+/**
+ * Framework-agnostic MCP tool definitions over a MemoryBackend.
+ *
+ * Defined once here, then registered into whichever server framework a
+ * transport uses — the Claude Agent SDK's `tool()` (in-process) or the MCP
+ * SDK's `registerTool()` (stdio/HTTP). Both accept the same (name, description,
+ * zod raw shape, handler→CallToolResult) shape, so the handlers below are the
+ * single source of truth.
+ *
+ * Token-saving is enforced HERE, server-side, regardless of what the model
+ * asks for: recall is top-K (capped), each entry's content is truncated, and
+ * there is deliberately no "return everything" tool. Moving memory out of the
+ * prompt only saves tokens if recall is selective — a tool that dumps the whole
+ * store back into context is more expensive than inlining it.
+ */
+
+import { z } from "zod";
+import type { MemoryBackend, RecallHit } from "./backend.js";
+
+/** The MCP CallToolResult shape both server frameworks expect. */
+export interface ToolResult {
+    content: Array<{ type: "text"; text: string }>;
+    isError?: boolean;
+}
+
+/** A framework-neutral tool: maps 1:1 onto Agent-SDK `tool()` and MCP `registerTool()`. */
+export interface MemoryTool {
+    name: string;
+    description: string;
+    /** Zod *raw shape* (e.g. `{ query: z.string() }`), not a ZodObject. */
+    inputSchema: z.ZodRawShape;
+    handler: (args: Record<string, unknown>) => Promise<ToolResult>;
+}
+
+export interface MemoryToolsOptions {
+    /** Hard cap on entries any recall tool returns to the model. Default 5. */
+    maxResults?: number;
+    /** Max characters of each entry's content surfaced to the model. Default 500. */
+    maxContentChars?: number;
+    /** Expose write tools (remember/forget). Default true; forced false if the backend is read-only. */
+    writable?: boolean;
+}
+
+const DEFAULT_MAX_RESULTS = 5;
+const DEFAULT_MAX_CONTENT = 500;
+
+function clip(s: string, n: number): string {
+    return s.length <= n ? s : `${s.slice(0, n)}…`;
+}
+
+function ok(text: string): ToolResult {
+    return { content: [{ type: "text", text }] };
+}
+
+function fail(text: string): ToolResult {
+    return { content: [{ type: "text", text }], isError: true };
+}
+
+function renderHits(hits: RecallHit[], maxChars: number): string {
+    if (hits.length === 0) return "No matching memories.";
+    return hits
+        .map((h) => {
+            const tags = h.tags?.length ? ` tags=[${h.tags.join(", ")}]` : "";
+            const score = h.score != null ? ` score=${h.score.toFixed(3)}` : "";
+            return `• ${h.key}${score}${tags}\n  ${clip(h.content, maxChars)}`;
+        })
+        .join("\n");
+}
+
+/**
+ * Builds the memory tool set bound to `backend`. Write tools are included only
+ * when `writable` is not false AND the backend actually implements them.
+ */
+export function buildMemoryTools(backend: MemoryBackend, opts: MemoryToolsOptions = {}): MemoryTool[] {
+    const maxResults = Math.max(1, opts.maxResults ?? DEFAULT_MAX_RESULTS);
+    const maxContent = Math.max(80, opts.maxContentChars ?? DEFAULT_MAX_CONTENT);
+    const writable = opts.writable !== false;
+
+    const tools: MemoryTool[] = [
+        {
+            name: "memory_recall",
+            description:
+                "Semantically recall the most relevant stored memories for a query. " +
+                "Call this BEFORE answering whenever the task may depend on prior context, user " +
+                "preferences, project decisions, or facts learned in earlier sessions — instead of " +
+                "assuming that context is already in your prompt. Returns a small ranked set, not the " +
+                "whole store.",
+            inputSchema: {
+                query: z.string().describe("What to look for — a question, topic, or keywords."),
+                topK: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(maxResults)
+                    .optional()
+                    .describe(`How many memories to return (max ${maxResults}).`),
+            },
+            handler: async (args) => {
+                try {
+                    const query = String(args["query"] ?? "");
+                    if (!query.trim()) return fail("query is required.");
+                    const k = Math.min(maxResults, Number(args["topK"] ?? maxResults));
+                    const hits = await backend.recall(query, k);
+                    return ok(renderHits(hits.slice(0, maxResults), maxContent));
+                } catch (err) {
+                    return fail(`recall failed: ${String(err)}`);
+                }
+            },
+        },
+        {
+            name: "memory_get",
+            description:
+                "Fetch a single memory by its exact key. Use when you already know the key " +
+                "(e.g. one surfaced by memory_recall) and want its full, untruncated value.",
+            inputSchema: {
+                key: z.string().describe("The exact memory key."),
+            },
+            handler: async (args) => {
+                try {
+                    const key = String(args["key"] ?? "");
+                    if (!key) return fail("key is required.");
+                    const hit = await backend.get(key);
+                    return hit ? ok(`• ${hit.key}\n  ${hit.content}`) : ok(`No memory found for key "${key}".`);
+                } catch (err) {
+                    return fail(`get failed: ${String(err)}`);
+                }
+            },
+        },
+        {
+            name: "memory_recall_by_tag",
+            description:
+                "List memories carrying a given tag (e.g. 'user', 'project', 'decision'). " +
+                "Use to pull a known category of context rather than searching semantically.",
+            inputSchema: {
+                tag: z.string().describe("The tag to filter by."),
+                limit: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(maxResults)
+                    .optional()
+                    .describe(`Max entries to return (max ${maxResults}).`),
+            },
+            handler: async (args) => {
+                try {
+                    const tag = String(args["tag"] ?? "");
+                    if (!tag) return fail("tag is required.");
+                    const limit = Math.min(maxResults, Number(args["limit"] ?? maxResults));
+                    const hits = await backend.recallByTag(tag, limit);
+                    return ok(renderHits(hits, maxContent));
+                } catch (err) {
+                    return fail(`recall_by_tag failed: ${String(err)}`);
+                }
+            },
+        },
+    ];
+
+    if (writable && backend.remember) {
+        tools.push({
+            name: "memory_remember",
+            description:
+                "Persist a fact for future sessions. Call when you learn something durable and reusable: " +
+                "a user preference, a project constraint, a decision and its rationale. Keep keys stable " +
+                "and descriptive (e.g. 'user.preferred-language') so the same fact overwrites rather than " +
+                "duplicating.",
+            inputSchema: {
+                key: z.string().describe("Stable, descriptive identifier; reusing a key overwrites it."),
+                content: z.string().describe("The fact to store."),
+                tags: z.array(z.string()).optional().describe("Optional grouping tags."),
+                importance: z.number().min(0).max(1).optional().describe("Importance 0–1 (default 0.5)."),
+                ttlMs: z.number().int().positive().optional().describe("Optional time-to-live in ms."),
+            },
+            handler: async (args) => {
+                try {
+                    const key = String(args["key"] ?? "");
+                    const content = String(args["content"] ?? "");
+                    if (!key || !content) return fail("key and content are required.");
+                    await backend.remember!({
+                        key,
+                        content,
+                        tags: args["tags"] as string[] | undefined,
+                        importance: args["importance"] as number | undefined,
+                        ttlMs: args["ttlMs"] as number | undefined,
+                    });
+                    return ok(`Remembered "${key}".`);
+                } catch (err) {
+                    return fail(`remember failed: ${String(err)}`);
+                }
+            },
+        });
+    }
+
+    if (writable && backend.forget) {
+        tools.push({
+            name: "memory_forget",
+            description: "Delete a memory by key. Use to remove a fact that is now wrong or obsolete.",
+            inputSchema: {
+                key: z.string().describe("The exact memory key to delete."),
+            },
+            handler: async (args) => {
+                try {
+                    const key = String(args["key"] ?? "");
+                    if (!key) return fail("key is required.");
+                    await backend.forget!(key);
+                    return ok(`Forgot "${key}".`);
+                } catch (err) {
+                    return fail(`forget failed: ${String(err)}`);
+                }
+            },
+        });
+    }
+
+    return tools;
+}

package/src/transports/http.ts

@@ -0,0 +1,64 @@
+/**
+ * HTTP transport — the multi-tenant / networked path (builderforce.ai hosting,
+ * remote claws). Stateless Streamable HTTP: one short-lived McpServer +
+ * transport per request, so it scales horizontally with no sticky sessions.
+ * Bearer-token auth gates every request.
+ *
+ * Consumed from the Claude Agent SDK as:
+ *   mcpServers: {
+ *     builderforce_memory: { type: "http", url: "https://mcp.builderforce.ai/memory",
+ *                            headers: { Authorization: `Bearer ${KEY}` } }
+ *   }
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import type { MemoryBackend } from "../backend.js";
+import { buildMcpServer, type McpServerOptions } from "./mcp-server.js";
+
+export interface HttpHandlerOptions extends McpServerOptions {
+    /**
+     * Shared secret required in `Authorization: Bearer <token>`. When set, every
+     * request without a matching token is rejected 401. Omit only behind a trusted
+     * gateway that has already authenticated the caller.
+     */
+    authToken?: string;
+}
+
+function unauthorized(res: ServerResponse): void {
+    res.writeHead(401, { "content-type": "application/json" });
+    res.end(JSON.stringify({ error: "unauthorized" }));
+}
+
+/**
+ * Returns a `(req, res) => Promise<void>` handler you mount on any Node HTTP
+ * server (or Express). Per request it spins up a stateless MCP server bound to
+ * `backend`, handles the MCP exchange, and tears down on response close.
+ */
+export function createMemoryHttpHandler(
+    backend: MemoryBackend,
+    opts: HttpHandlerOptions = {},
+): (req: IncomingMessage, res: ServerResponse) => Promise<void> {
+    return async (req, res) => {
+        if (opts.authToken) {
+            const header = req.headers["authorization"];
+            if (header !== `Bearer ${opts.authToken}`) {
+                unauthorized(res);
+                return;
+            }
+        }
+
+        const server = buildMcpServer(backend, opts);
+        // Stateless: no session id generator → a fresh transport per request.
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+
+        res.on("close", () => {
+            void transport.close();
+            void server.close();
+        });
+
+        await server.connect(transport);
+        // Pass undefined body — the transport reads/parses the request stream itself.
+        await transport.handleRequest(req, res);
+    };
+}