@memofs/mcp-server API Reference

Comprehensive technical API reference for @memofs/mcp-server and @memofs/mcp-server/http: protocol servers, transports, runtime adapters, and SDK integration.

The @memofs/mcp-server package implements a transport-agnostic Model Context Protocol (MCP) server for MemoFS, exposing memory tools, resources, and prompts over stdio, HTTP (Cloudflare Workers, Hono, Node.js fetch), and @modelcontextprotocol/sdk adapters.

Package Subpaths

// 1. Primary Entrypoint (Stdio transport, protocol server, runtime adapter, SDK bridge)
import {
  createMemoFSMcpRuntimeFromConfig,
  createMemoFSMcpRuntimeFromMemoFS,
  createMemoFSMcpProtocolServer,
  runStdioServer,
  registerMemoFSMcpCapabilities,
  MemoFSMcpError,
} from "@memofs/mcp-server";

// 2. HTTP Entrypoint (Stateless Streamable HTTP for Cloudflare Workers & Hono)
import {
  handleMemoFSMcpRequest,
  createMemoFSMcpFetchHandler,
  createHonoMemoFSMcpHandler,
  createMemoFSCloudMcpRuntime,
} from "@memofs/mcp-server/http";

1. Composing a Stdio MCP Server

import { createNodeMemoFs } from "@memofs/core/node-fs";
import {
  createMemoFSMcpRuntimeFromMemoFS,
  createMemoFSMcpProtocolServer,
  runStdioServer,
} from "@memofs/mcp-server";

// 1. Create or configure a MemoFS instance
const memo = createNodeMemoFs({ rootDir: "." });

// 2. Wrap the MemoFS instance as an MCP runtime adapter
const runtime = createMemoFSMcpRuntimeFromMemoFS(memo);

// 3. Create the protocol server
const server = createMemoFSMcpProtocolServer({
  runtime,
  name: "memofs",
  version: "1.3.0",
});

// 4. Run the stdio transport loop (reads stdin, writes stdout)
await runStdioServer(server);

2. Core Functions (`@memofs/mcp-server`)

`createMemoFSMcpRuntimeFromConfig(options?: RuntimeFactoryOptions): MemoFSMcpRuntime`

Builds a MemoFS client from config options and wraps it as a MemoFSMcpRuntime.

import { createMemoFSMcpRuntimeFromConfig } from "@memofs/mcp-server";

const runtime = createMemoFSMcpRuntimeFromConfig({
  rootDir: "./my-project",
  mode: "hybrid",
  cloud: {
    baseUrl: "https://memofs.dev/api/v1",
    apiKey: process.env.MEMOFS_API_KEY,
  },
  recall: {
    localEmbeddings: true,
  },
});

`createMemoFSMcpRuntimeFromMemoFS(memo: MemoFS): MemoFSMcpRuntime`

Wraps an existing MemoFS instance as a MemoFSMcpRuntime.

import { MemoFS } from "@memofs/core";
import { createMemoFSMcpRuntimeFromMemoFS } from "@memofs/mcp-server";

const runtime = createMemoFSMcpRuntimeFromMemoFS(memo);

`createMemoFSMcpProtocolServer(options: MemoFSMcpOptions): MemoFSMcpProtocolServer`

Creates a transport-agnostic protocol handler that parses JSON-RPC 2.0 messages and routes tool, resource, and prompt requests to the runtime.

const server = createMemoFSMcpProtocolServer({
  runtime,
  readOnly: false,
  maxPageSize: 50,
  requestTimeoutMs: 30000,
});

`runStdioServer(server: MemoFSMcpProtocolServer): Promise<void>`

Runs a protocol server over stdio, reading newline-delimited JSON-RPC from standard input and writing responses to standard output. Resolves when standard input closes.

`registerMemoFSMcpCapabilities(server: StructuralMcpServer, options: MemoFSMcpOptions): void`

Registers MemoFS tools, resources, and prompts directly onto an instantiated @modelcontextprotocol/sdk (or FastMCP) server object.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { registerMemoFSMcpCapabilities, createMemoFSMcpRuntimeFromConfig } from "@memofs/mcp-server";

const mcpSdkServer = new McpServer({ name: "my-agent-server", version: "1.0.0" });
const runtime = createMemoFSMcpRuntimeFromConfig({ rootDir: "." });

registerMemoFSMcpCapabilities(mcpSdkServer, { runtime });

3. HTTP & Worker Functions (`@memofs/mcp-server/http`)

The @memofs/mcp-server/http subpath provides Web Fetch–compatible handlers designed for Cloudflare Workers, Hono, and hosted HTTP environments.

`handleMemoFSMcpRequest(request: Request, options?: MemoFSMcpHttpOptions): Promise<Response>`

Handles an incoming Streamable HTTP POST/OPTIONS request, enforcing origin checks, CORS, bearer token authentication, header validation, and JSON-RPC dispatching.

import { handleMemoFSMcpRequest } from "@memofs/mcp-server/http";

export default {
  async fetch(request: Request, env: Record<string, string>): Promise<Response> {
    return handleMemoFSMcpRequest(request, {
      env,
      auth: {
        bearerToken: env.MEMOFS_MCP_BEARER_TOKEN,
      },
    });
  },
};

`createMemoFSMcpFetchHandler<Env>(options?: MemoFSMcpHttpOptions): MemoFSMcpFetchHandler<Env>`

Constructs a standard Cloudflare Workers fetch handler function.

import { createMemoFSMcpFetchHandler } from "@memofs/mcp-server/http";

export default {
  fetch: createMemoFSMcpFetchHandler({
    cloud: {
      baseUrl: "https://memofs.dev/api/v1",
    },
  }),
};

`createHonoMemoFSMcpHandler(options?: MemoFSMcpHttpOptions)`

Creates an MCP route handler for Hono applications.

import { Hono } from "hono";
import { createHonoMemoFSMcpHandler } from "@memofs/mcp-server/http";

const app = new Hono();
app.post("/mcp", createHonoMemoFSMcpHandler());

`createMemoFSCloudMcpRuntime(options: MemoFSCloudMcpRuntimeOptions): MemoFSMcpRuntime`

Creates a lightweight cloud-only MemoFSMcpRuntime backed by a remote MemoFS Cloud API endpoint.

4. Interfaces & Types

`MemoFSMcpOptions`

interface MemoFSMcpOptions {
  runtime: MemoFSMcpRuntime;
  name?: string;
  version?: string;
  instructions?: string;
  readOnly?: boolean;
  defaultPageSize?: number; // default: 25
  maxPageSize?: number;     // default: 100
  requestTimeoutMs?: number;// default: 30000
  maxInputBytes?: number;   // default: 256000
  maxOutputBytes?: number;  // default: 512000
  authorize?: (context: AuthorizationContext) => Promise<boolean> | boolean;
  redact?: (args: unknown) => unknown;
}

`RuntimeFactoryOptions`

interface RuntimeFactoryOptions {
  mode?: "local" | "hybrid";
  rootDir?: string;
  projectId?: string;
  workspaceId?: string;
  store?: MemoryStore;
  cloudClient?: MemoFsCloudClient;
  cloud?: {
    baseUrl?: string;
    apiKey?: string;
    workspaceId?: string;
    projectId?: string;
    timeoutMs?: number;
    userAgent?: string;
    requireApiKey?: boolean;
    retry?: { maxRetries?: number; backoffMs?: number };
  };
  recall?: {
    engine?: "lexical" | "vector" | "hybrid" | "auto";
    localEmbeddings?: boolean;
    embeddingModel?: string;
  };
  onModelProgress?: (info: { progress: number; status: string; file?: string }) => void;
  prewarm?: boolean;
}

`MemoFSMcpHttpOptions`

interface MemoFSMcpHttpOptions extends Omit<MemoFSMcpOptions, "runtime"> {
  runtime?: MemoFSMcpRuntime;
  env?: MemoFSMcpHttpEnv;
  cloud?: Partial<MemoFSCloudMcpRuntimeOptions>;
  auth?: {
    requireAuth?: boolean;
    bearerToken?: string;
    authenticate?: (request: Request) => boolean | Promise<boolean>;
  };
  allowedOrigins?: readonly string[];
}

5. Error Hierarchy

All MCP errors extend MemoFSMcpError and carry .code (stable machine string), .status (HTTP status code), and .details.

Class	`.code`	`.status`	Thrown when
`McpValidationError`	`MCP_VALIDATION_ERROR`	400	A request fails schema or argument validation
`McpAuthorizationError`	`MCP_AUTHORIZATION_ERROR`	403	A write tool is invoked without authorization or read-only mode is active
`McpNotFoundError`	`MCP_NOT_FOUND`	404	An unknown tool, resource, or prompt is requested
`McpTimeoutError`	`MCP_TIMEOUT`	504	An operation exceeds `requestTimeoutMs`
`McpOutputLimitError`	`MCP_OUTPUT_LIMIT`	413	A response payload exceeds `maxOutputBytes`
`MemoFSMcpError`	`MEMOFS_MCP_ERROR`	500	Base error class

`toSafeError(error: unknown)`

Normalizes any caught error into a safe { name, message, code, status, details? } payload suitable for JSON-RPC error responses.