@seanhogg/builderforce-memory-mcp 2026.6.18

package/src/transports/mcp-server.ts

@@ -0,0 +1,40 @@
+/**
+ * Shared MCP server builder for the out-of-process transports (stdio + HTTP).
+ *
+ * Both use the standard @modelcontextprotocol/sdk `McpServer`; only the
+ * transport binding differs. The tools come from the same buildMemoryTools()
+ * the in-process Agent SDK transport uses, so all three stay in lockstep.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { MemoryBackend } from "../backend.js";
+import { buildMemoryTools, type MemoryToolsOptions } from "../tools.js";
+
+export interface McpServerOptions extends MemoryToolsOptions {
+    name?: string;
+    version?: string;
+}
+
+/** Constructs an McpServer with the memory tools registered. */
+export function buildMcpServer(backend: MemoryBackend, opts: McpServerOptions = {}): McpServer {
+    const server = new McpServer({
+        name: opts.name ?? "builderforce-memory",
+        version: opts.version ?? "2026.5.31",
+    });
+
+    // The generic registerTool() over a zod raw shape trips TS2589 (excessively
+    // deep instantiation); the tool surface is identical across our transports,
+    // so register through a loose signature. Runtime behaviour is unchanged —
+    // both frameworks consume (name, {description, inputSchema}, handler).
+    const register = server.registerTool.bind(server) as (
+        name: string,
+        config: { description: string; inputSchema: unknown },
+        handler: unknown,
+    ) => void;
+
+    for (const t of buildMemoryTools(backend, opts)) {
+        register(t.name, { description: t.description, inputSchema: t.inputSchema }, t.handler);
+    }
+
+    return server;
+}

package/src/transports/sdk.ts

@@ -0,0 +1,75 @@
+/**
+ * In-process transport for the Claude Agent SDK.
+ *
+ * Returns the `type: "sdk"` MCP server config you drop straight into
+ * `query({ options: { mcpServers: { builderforce_memory: <this> } } })`.
+ * No subprocess, no socket — the tools run in your product's process, calling
+ * the MemoryBackend directly. Lowest latency; the consuming product pulls in
+ * @anthropic-ai/claude-agent-sdk (and, for the local backend, @seanhogg/builderforce-memory).
+ *
+ * The Agent SDK is imported indirectly so this package builds and so the stdio
+ * and HTTP transports don't drag the SDK in.
+ */
+
+import type { MemoryBackend } from "../backend.js";
+import { buildMemoryTools, type MemoryToolsOptions } from "../tools.js";
+
+export interface SdkServerOptions extends MemoryToolsOptions {
+    /** MCP server name; becomes the middle segment of `mcp__<name>__<tool>`. Default 'builderforce_memory'. */
+    name?: string;
+    version?: string;
+}
+
+/** The shape of `createSdkMcpServer`'s return — re-declared to avoid a hard type dep on the SDK. */
+export interface SdkMcpServerConfig {
+    type: "sdk";
+    name: string;
+    instance: unknown;
+}
+
+/**
+ * Wraps the memory tools as an in-process Claude Agent SDK MCP server.
+ *
+ * @example
+ *   import { query } from "@anthropic-ai/claude-agent-sdk";
+ *   import { createMemoryMcpServer, createLocalMemoryStoreBackend } from "@seanhogg/builderforce-memory-mcp";
+ *
+ *   const backend = await createLocalMemoryStoreBackend();
+ *   const memory  = await createMemoryMcpServer(backend);
+ *
+ *   for await (const msg of query({
+ *     prompt: "...",
+ *     options: {
+ *       mcpServers: { builderforce_memory: memory },
+ *       allowedTools: ["mcp__builderforce_memory__*"],
+ *     },
+ *   })) { /* ... *\/ }
+ */
+export async function createMemoryMcpServer(
+    backend: MemoryBackend,
+    opts: SdkServerOptions = {},
+): Promise<SdkMcpServerConfig> {
+    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 sdk = (await _import("@anthropic-ai/claude-agent-sdk")) as {
+        tool: (
+            name: string,
+            description: string,
+            schema: unknown,
+            handler: (args: Record<string, unknown>) => Promise<unknown>,
+        ) => unknown;
+        createSdkMcpServer: (o: { name: string; version?: string; tools: unknown[] }) => SdkMcpServerConfig;
+    };
+
+    const tools = buildMemoryTools(backend, opts).map((t) =>
+        sdk.tool(t.name, t.description, t.inputSchema, t.handler as (a: Record<string, unknown>) => Promise<unknown>),
+    );
+
+    return sdk.createSdkMcpServer({
+        name: opts.name ?? "builderforce_memory",
+        version: opts.version ?? "2026.5.31",
+        tools,
+    });
+}

package/src/transports/stdio.ts

@@ -0,0 +1,19 @@
+/**
+ * stdio transport — the portable path. Any MCP client in any language launches
+ * this as a subprocess and speaks MCP over stdin/stdout. Consumed from the
+ * Claude Agent SDK as:
+ *   mcpServers: {
+ *     builderforce_memory: { type: "stdio", command: "npx",
+ *                            args: ["-y", "@seanhogg/builderforce-memory-mcp"] }
+ *   }
+ */
+
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import type { MemoryBackend } from "../backend.js";
+import { buildMcpServer, type McpServerOptions } from "./mcp-server.js";
+
+/** Serves `backend` over stdio. Resolves when the transport closes. */
+export async function runStdio(backend: MemoryBackend, opts: McpServerOptions = {}): Promise<void> {
+    const server = buildMcpServer(backend, opts);
+    await server.connect(new StdioServerTransport());
+}