@quantic-impact/rvf-mcp-server 0.2.0

package/dist/cli.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+import { createServer } from "./transports.js";
+function parseArgs() {
+  const args = process.argv.slice(2);
+  let transport = "stdio";
+  let port = 3100;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--transport" || args[i] === "-t") {
+      const val = args[++i];
+      if (val === "sse" || val === "stdio") {
+        transport = val;
+      } else {
+        console.error(`Unknown transport: ${val}. Use 'stdio' or 'sse'.`);
+        process.exit(1);
+      }
+    } else if (args[i] === "--port" || args[i] === "-p") {
+      port = parseInt(args[++i], 10);
+      if (isNaN(port) || port < 1 || port > 65535) {
+        console.error("Port must be between 1 and 65535");
+        process.exit(1);
+      }
+    } else if (args[i] === "--help" || args[i] === "-h") {
+      console.log(`
+RVF MCP Server \u2014 Model Context Protocol server for RuVector Format
+
+Usage:
+  rvf-mcp-server [options]
+
+Options:
+  -t, --transport <stdio|sse>  Transport mode (default: stdio)
+  -p, --port <number>          SSE port (default: 3100)
+  -h, --help                   Show this help message
+
+MCP Tools:
+  rvf_create_store   Create a new vector store
+  rvf_open_store     Open an existing store
+  rvf_close_store    Close a store
+  rvf_ingest         Insert vectors
+  rvf_query          k-NN similarity search
+  rvf_delete         Delete vectors by ID
+  rvf_delete_filter  Delete by metadata filter
+  rvf_compact        Reclaim dead space
+  rvf_status         Store status
+  rvf_list_stores    List open stores
+
+stdio config (.mcp.json):
+  {
+    "mcpServers": {
+      "rvf": {
+        "command": "node",
+        "args": ["dist/cli.js"]
+      }
+    }
+  }
+`);
+      process.exit(0);
+    }
+  }
+  return { transport, port };
+}
+async function main() {
+  const { transport, port } = parseArgs();
+  if (transport === "stdio") {
+    console.error("RVF MCP Server starting (stdio transport)...");
+  }
+  const server = await createServer(transport, port);
+  async function shutdown(signal) {
+    console.error(`
+RVF MCP Server shutting down (${signal})...`);
+    try {
+      await server.close();
+    } catch (err) {
+      console.error("Error during shutdown:", err);
+    }
+    process.exit(0);
+  }
+  process.on("SIGINT", () => {
+    shutdown("SIGINT");
+  });
+  process.on("SIGTERM", () => {
+    shutdown("SIGTERM");
+  });
+}
+main().catch((err) => {
+  console.error("Fatal:", err);
+  process.exit(1);
+});

package/dist/index.js

@@ -0,0 +1,8 @@
+import { RvfMcpServer } from "./server.js";
+import { createStdioServer, createSseServer, createServer } from "./transports.js";
+export {
+  RvfMcpServer,
+  createServer,
+  createSseServer,
+  createStdioServer
+};

package/dist/server.js

@@ -0,0 +1,789 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { RvfDatabase, RvfError, RvfErrorCode } from "@quantic-impact/rvf";
+const MetadataFilter = z.record(z.string(), z.any()).optional().describe("Metadata filter (exact match on fields)");
+const MetadataFilterRequired = z.record(z.string(), z.any()).describe("Metadata filter \u2014 all matching vectors will be deleted");
+const IngestEntrySchema = z.object({
+  id: z.string().describe("Unique vector ID"),
+  vector: z.array(z.number()).describe("Embedding vector (must match store dimensions)"),
+  metadata: z.record(z.string(), z.any()).optional().describe("Optional metadata key-value pairs")
+});
+function fnv1aFieldId(name) {
+  let h = 2166136261;
+  for (let i = 0; i < name.length; i++) {
+    h ^= name.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+function buildFilterExpr(filter) {
+  const entries = Object.entries(filter);
+  if (entries.length === 1) {
+    const [key, val] = entries[0];
+    return { op: "eq", fieldId: fnv1aFieldId(key), value: val };
+  }
+  return {
+    op: "and",
+    exprs: entries.map(([key, val]) => ({
+      op: "eq",
+      fieldId: fnv1aFieldId(key),
+      value: val
+    }))
+  };
+}
+class RvfMcpServer {
+  mcp;
+  stores = /* @__PURE__ */ new Map();
+  nextId = 1;
+  opts;
+  constructor(options) {
+    this.opts = {
+      name: options?.name ?? "rvf-mcp-server",
+      version: options?.version ?? "0.1.0",
+      maxStores: options?.maxStores ?? 64
+    };
+    this.mcp = new McpServer(
+      { name: this.opts.name, version: this.opts.version },
+      {
+        capabilities: {
+          resources: {},
+          tools: {},
+          prompts: {}
+        }
+      }
+    );
+    this.registerTools();
+    this.registerResources();
+    this.registerPrompts();
+  }
+  // ─── Internal helpers ───────────────────────────────────────────────────
+  errorResponse(msg) {
+    return { content: [{ type: "text", text: `Error: ${msg}` }] };
+  }
+  async withStore(storeId, fn) {
+    const handle = this.stores.get(storeId);
+    if (!handle) {
+      return this.errorResponse(`store ${storeId} not found`);
+    }
+    try {
+      return await fn(handle);
+    } catch (err) {
+      if (err instanceof RvfError) {
+        return this.errorResponse(`[${RvfErrorCode[err.code]}] ${err.message}`);
+      }
+      return this.errorResponse(String(err));
+    }
+  }
+  // ─── Tool Registration ──────────────────────────────────────────────────
+  registerTools() {
+    this.mcp.tool(
+      "rvf_create_store",
+      "Create a new RVF vector store at the given path",
+      {
+        path: z.string().describe("File path for the new .rvf store"),
+        dimensions: z.number().int().positive().describe("Vector dimensionality"),
+        metric: z.enum(["l2", "cosine", "dotproduct"]).default("l2").describe("Distance metric")
+      },
+      async ({ path, dimensions, metric }) => {
+        if (this.stores.size >= this.opts.maxStores) {
+          return this.errorResponse(`max stores (${this.opts.maxStores}) reached`);
+        }
+        try {
+          const db = await RvfDatabase.create(path, {
+            dimensions,
+            metric
+          });
+          const id = `store_${this.nextId++}`;
+          this.stores.set(id, {
+            id,
+            path,
+            db,
+            readOnly: false,
+            openedAt: Date.now()
+          });
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                storeId: id,
+                path,
+                dimensions,
+                metric,
+                status: "created"
+              }, null, 2)
+            }]
+          };
+        } catch (err) {
+          if (err instanceof RvfError) {
+            return this.errorResponse(`[${RvfErrorCode[err.code]}] ${err.message}`);
+          }
+          return this.errorResponse(String(err));
+        }
+      }
+    );
+    this.mcp.tool(
+      "rvf_open_store",
+      "Open an existing RVF store for reading and writing",
+      {
+        path: z.string().describe("Path to existing .rvf file"),
+        readOnly: z.boolean().default(false).describe("Open in read-only mode")
+      },
+      async ({ path, readOnly }) => {
+        if (this.stores.size >= this.opts.maxStores) {
+          return this.errorResponse(`max stores (${this.opts.maxStores}) reached`);
+        }
+        try {
+          const db = readOnly ? await RvfDatabase.openReadonly(path) : await RvfDatabase.open(path);
+          const id = `store_${this.nextId++}`;
+          this.stores.set(id, {
+            id,
+            path,
+            db,
+            readOnly,
+            openedAt: Date.now()
+          });
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                storeId: id,
+                path,
+                readOnly,
+                status: "opened"
+              }, null, 2)
+            }]
+          };
+        } catch (err) {
+          if (err instanceof RvfError) {
+            return this.errorResponse(`[${RvfErrorCode[err.code]}] ${err.message}`);
+          }
+          return this.errorResponse(String(err));
+        }
+      }
+    );
+    this.mcp.tool(
+      "rvf_close_store",
+      "Close an open RVF store, releasing the writer lock",
+      {
+        storeId: z.string().describe("Store ID returned by create/open")
+      },
+      async ({ storeId }) => {
+        const result = await this.withStore(storeId, async (handle) => {
+          await handle.db.close();
+          this.stores.delete(storeId);
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({ storeId, status: "closed", path: handle.path }, null, 2)
+            }]
+          };
+        });
+        return result;
+      }
+    );
+    this.mcp.tool(
+      "rvf_ingest",
+      "Insert vectors into an RVF store",
+      {
+        storeId: z.string().describe("Target store ID"),
+        entries: z.array(IngestEntrySchema).describe("Vectors to insert")
+      },
+      // @ts-ignore — TS2589: deep inference from nested Zod schema
+      async ({ storeId, entries }) => {
+        const result = await this.withStore(storeId, async (handle) => {
+          if (handle.readOnly) {
+            return this.errorResponse("store is read-only");
+          }
+          const ingestResult = await handle.db.ingestBatch(
+            entries.map((e) => ({
+              id: e.id,
+              vector: e.vector,
+              metadata: e.metadata
+            }))
+          );
+          const status = await handle.db.status();
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                accepted: ingestResult.accepted,
+                rejected: ingestResult.rejected,
+                epoch: ingestResult.epoch,
+                totalVectors: status.totalVectors
+              }, null, 2)
+            }]
+          };
+        });
+        return result;
+      }
+    );
+    this.mcp.tool(
+      "rvf_query",
+      "k-NN vector similarity search",
+      {
+        storeId: z.string().describe("Store ID to query"),
+        vector: z.array(z.number()).describe("Query embedding vector"),
+        k: z.number().int().positive().default(10).describe("Number of nearest neighbors"),
+        filter: MetadataFilter
+      },
+      // @ts-ignore — TS2589: deep inference from optional filter schema
+      async ({ storeId, vector, k, filter }) => {
+        const result = await this.withStore(storeId, async (handle) => {
+          const queryOpts = filter ? { filter: buildFilterExpr(filter) } : void 0;
+          const results = await handle.db.query(vector, k, queryOpts);
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                results: results.map((r) => ({ id: r.id, distance: r.distance })),
+                count: results.length
+              }, null, 2)
+            }]
+          };
+        });
+        return result;
+      }
+    );
+    this.mcp.tool(
+      "rvf_delete",
+      "Delete vectors by their IDs",
+      {
+        storeId: z.string().describe("Store ID"),
+        ids: z.array(z.string()).describe("Vector IDs to delete")
+      },
+      async ({ storeId, ids }) => {
+        const result = await this.withStore(storeId, async (handle) => {
+          if (handle.readOnly) {
+            return this.errorResponse("store is read-only");
+          }
+          const delResult = await handle.db.delete(ids);
+          const status = await handle.db.status();
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                deleted: delResult.deleted,
+                epoch: delResult.epoch,
+                remaining: status.totalVectors
+              }, null, 2)
+            }]
+          };
+        });
+        return result;
+      }
+    );
+    this.mcp.tool(
+      "rvf_delete_filter",
+      "Delete vectors matching a metadata filter",
+      {
+        storeId: z.string().describe("Store ID"),
+        filter: MetadataFilterRequired
+      },
+      // @ts-ignore — TS2589: deep inference from filter schema
+      async ({ storeId, filter }) => {
+        const result = await this.withStore(storeId, async (handle) => {
+          if (handle.readOnly) {
+            return this.errorResponse("store is read-only");
+          }
+          const filterExpr = buildFilterExpr(filter);
+          const delResult = await handle.db.deleteByFilter(filterExpr);
+          const status = await handle.db.status();
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                deleted: delResult.deleted,
+                epoch: delResult.epoch,
+                remaining: status.totalVectors
+              }, null, 2)
+            }]
+          };
+        });
+        return result;
+      }
+    );
+    this.mcp.tool(
+      "rvf_compact",
+      "Compact store to reclaim dead space from deleted vectors",
+      {
+        storeId: z.string().describe("Store ID")
+      },
+      async ({ storeId }) => {
+        const result = await this.withStore(storeId, async (handle) => {
+          const compactResult = await handle.db.compact();
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                storeId,
+                segmentsCompacted: compactResult.segmentsCompacted,
+                bytesReclaimed: compactResult.bytesReclaimed,
+                epoch: compactResult.epoch
+              }, null, 2)
+            }]
+          };
+        });
+        return result;
+      }
+    );
+    this.mcp.tool(
+      "rvf_status",
+      "Get the current status of an RVF store",
+      {
+        storeId: z.string().describe("Store ID")
+      },
+      async ({ storeId }) => {
+        const result = await this.withStore(storeId, async (handle) => {
+          const [status, dimension] = await Promise.all([
+            handle.db.status(),
+            handle.db.dimension()
+          ]);
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                storeId: handle.id,
+                path: handle.path,
+                dimensions: dimension,
+                totalVectors: status.totalVectors,
+                totalSegments: status.totalSegments,
+                fileSizeBytes: status.fileSizeBytes,
+                epoch: status.epoch,
+                compactionState: status.compactionState,
+                deadSpaceRatio: status.deadSpaceRatio,
+                readOnly: status.readOnly,
+                openedAt: new Date(handle.openedAt).toISOString()
+              }, null, 2)
+            }]
+          };
+        });
+        return result;
+      }
+    );
+    this.mcp.tool(
+      "rvf_list_stores",
+      "List all open RVF stores",
+      {},
+      async () => {
+        const handles = Array.from(this.stores.values());
+        const list = await Promise.all(
+          handles.map(async (h) => {
+            try {
+              const [status, dimension] = await Promise.all([
+                h.db.status(),
+                h.db.dimension()
+              ]);
+              return {
+                storeId: h.id,
+                path: h.path,
+                dimensions: dimension,
+                totalVectors: status.totalVectors,
+                readOnly: status.readOnly
+              };
+            } catch {
+              return {
+                storeId: h.id,
+                path: h.path,
+                dimensions: null,
+                totalVectors: null,
+                readOnly: h.readOnly,
+                error: "failed to read status"
+              };
+            }
+          })
+        );
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({ stores: list, count: list.length }, null, 2)
+          }]
+        };
+      }
+    );
+    this.mcp.tool(
+      "rvf_put_meta",
+      "Store a key-value pair in store-level metadata (persisted in META_SEG)",
+      {
+        storeId: z.string().describe("Store ID from rvf_create_store or rvf_open_store"),
+        key: z.string().describe("Metadata key"),
+        value: z.string().describe("Metadata value (stored as UTF-8 bytes)")
+      },
+      async ({ storeId, key, value }) => {
+        const handle = this.stores.get(storeId);
+        if (!handle)
+          return { content: [{ type: "text", text: `Store '${storeId}' not found` }] };
+        try {
+          await handle.db.putMeta(key, new TextEncoder().encode(value));
+          return { content: [{ type: "text", text: JSON.stringify({ success: true, key }) }] };
+        } catch (e) {
+          return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+      }
+    );
+    this.mcp.tool(
+      "rvf_get_meta",
+      "Retrieve a value from store-level metadata by key",
+      {
+        storeId: z.string().describe("Store ID"),
+        key: z.string().describe("Metadata key to retrieve")
+      },
+      async ({ storeId, key }) => {
+        const handle = this.stores.get(storeId);
+        if (!handle)
+          return { content: [{ type: "text", text: `Store '${storeId}' not found` }] };
+        try {
+          const result = await handle.db.getMeta(key);
+          if (result === null) {
+            return { content: [{ type: "text", text: JSON.stringify({ found: false, key }) }] };
+          }
+          return { content: [{ type: "text", text: JSON.stringify({ found: true, key, value: new TextDecoder().decode(result) }) }] };
+        } catch (e) {
+          return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+      }
+    );
+    this.mcp.tool(
+      "rvf_list_meta_keys",
+      "List all keys in store-level metadata",
+      {
+        storeId: z.string().describe("Store ID")
+      },
+      async ({ storeId }) => {
+        const handle = this.stores.get(storeId);
+        if (!handle)
+          return { content: [{ type: "text", text: `Store '${storeId}' not found` }] };
+        try {
+          const keys = await handle.db.listMetaKeys();
+          return { content: [{ type: "text", text: JSON.stringify({ keys, count: keys.length }) }] };
+        } catch (e) {
+          return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+      }
+    );
+    this.mcp.tool(
+      "rvf_delete_meta",
+      "Delete a key from store-level metadata",
+      {
+        storeId: z.string().describe("Store ID"),
+        key: z.string().describe("Metadata key to delete")
+      },
+      async ({ storeId, key }) => {
+        const handle = this.stores.get(storeId);
+        if (!handle)
+          return { content: [{ type: "text", text: `Store '${storeId}' not found` }] };
+        if (handle.readOnly)
+          return { content: [{ type: "text", text: "Error: store is read-only" }] };
+        try {
+          const existed = await handle.db.deleteMeta(key);
+          return { content: [{ type: "text", text: JSON.stringify({ success: true, key, existed }) }] };
+        } catch (e) {
+          return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+      }
+    );
+    this.mcp.tool(
+      "rvf_flush_meta",
+      "Flush deferred metadata writes to disk (no-op if clean)",
+      {
+        storeId: z.string().describe("Store ID")
+      },
+      async ({ storeId }) => {
+        const handle = this.stores.get(storeId);
+        if (!handle)
+          return { content: [{ type: "text", text: `Store '${storeId}' not found` }] };
+        if (handle.readOnly)
+          return { content: [{ type: "text", text: "Error: store is read-only" }] };
+        try {
+          await handle.db.flushMeta();
+          return { content: [{ type: "text", text: JSON.stringify({ success: true, flushed: true }) }] };
+        } catch (e) {
+          return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+      }
+    );
+    this.mcp.tool(
+      "rvf_branch",
+      "Create a COW (copy-on-write) branch of a store",
+      {
+        storeId: z.string().describe("Parent store ID"),
+        childPath: z.string().describe("File path for the child branch")
+      },
+      async ({ storeId, childPath }) => {
+        const handle = this.stores.get(storeId);
+        if (!handle)
+          return { content: [{ type: "text", text: `Store '${storeId}' not found` }] };
+        try {
+          const childDb = await handle.db.branch(childPath);
+          const childId = `store_${this.nextId++}`;
+          this.stores.set(childId, { id: childId, path: childPath, db: childDb, readOnly: false, openedAt: Date.now() });
+          return { content: [{ type: "text", text: JSON.stringify({ success: true, childStoreId: childId, childPath }) }] };
+        } catch (e) {
+          return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+      }
+    );
+    this.mcp.tool(
+      "rvf_freeze",
+      "Freeze a COW branch (make it immutable)",
+      {
+        storeId: z.string().describe("Store ID to freeze")
+      },
+      async ({ storeId }) => {
+        const handle = this.stores.get(storeId);
+        if (!handle)
+          return { content: [{ type: "text", text: `Store '${storeId}' not found` }] };
+        try {
+          await handle.db.freeze();
+          return { content: [{ type: "text", text: JSON.stringify({ success: true, frozen: true }) }] };
+        } catch (e) {
+          return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+      }
+    );
+    this.mcp.tool(
+      "rvf_cow_stats",
+      "Get COW (copy-on-write) statistics for a store",
+      {
+        storeId: z.string().describe("Store ID")
+      },
+      async ({ storeId }) => {
+        const handle = this.stores.get(storeId);
+        if (!handle)
+          return { content: [{ type: "text", text: `Store '${storeId}' not found` }] };
+        try {
+          const stats = await handle.db.cowStats();
+          return { content: [{ type: "text", text: JSON.stringify(stats) }] };
+        } catch (e) {
+          return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+      }
+    );
+    this.mcp.tool(
+      "rvf_witness_hash",
+      "Get the last witness hash from the audit chain",
+      {
+        storeId: z.string().describe("Store ID")
+      },
+      async ({ storeId }) => {
+        const handle = this.stores.get(storeId);
+        if (!handle)
+          return { content: [{ type: "text", text: `Store '${storeId}' not found` }] };
+        try {
+          const hash = await handle.db.lastWitnessHash();
+          const hex = Array.from(hash).map((b) => b.toString(16).padStart(2, "0")).join("");
+          return { content: [{ type: "text", text: JSON.stringify({ witnessHash: hex }) }] };
+        } catch (e) {
+          return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+      }
+    );
+    this.mcp.tool(
+      "rvf_query_audited",
+      "k-NN search with tamper-evident audit trail (appends WITNESS_SEG)",
+      {
+        storeId: z.string().describe("Store ID to query"),
+        vector: z.array(z.number()).describe("Query embedding vector"),
+        k: z.number().int().positive().default(10).describe("Number of nearest neighbors"),
+        filter: MetadataFilter
+      },
+      // @ts-ignore — TS2589: deep inference from optional filter schema
+      async ({ storeId, vector, k, filter }) => {
+        const result = await this.withStore(storeId, async (handle) => {
+          const queryOpts = filter ? { filter: buildFilterExpr(filter) } : void 0;
+          const results = await handle.db.queryAudited(vector, k, queryOpts);
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                results: results.map((r) => ({ id: r.id, distance: r.distance })),
+                count: results.length,
+                audited: true
+              }, null, 2)
+            }]
+          };
+        });
+        return result;
+      }
+    );
+    this.mcp.tool(
+      "rvf_membership_contains",
+      "Check if a vector ID is in the membership filter (COW branches)",
+      {
+        storeId: z.string().describe("Store ID"),
+        id: z.number().int().describe("Vector ID to check")
+      },
+      async ({ storeId, id }) => {
+        const handle = this.stores.get(storeId);
+        if (!handle)
+          return { content: [{ type: "text", text: `Store '${storeId}' not found` }] };
+        try {
+          const contains = await handle.db.membershipContains(id);
+          return { content: [{ type: "text", text: JSON.stringify({ id, contains }) }] };
+        } catch (e) {
+          return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+      }
+    );
+    this.mcp.tool(
+      "rvf_membership_add",
+      "Add a vector ID to the membership filter (COW branches only)",
+      {
+        storeId: z.string().describe("Store ID"),
+        id: z.number().int().describe("Vector ID to add")
+      },
+      async ({ storeId, id }) => {
+        const handle = this.stores.get(storeId);
+        if (!handle)
+          return { content: [{ type: "text", text: `Store '${storeId}' not found` }] };
+        if (handle.readOnly)
+          return { content: [{ type: "text", text: "Error: store is read-only" }] };
+        try {
+          await handle.db.membershipAdd(id);
+          return { content: [{ type: "text", text: JSON.stringify({ success: true, id, action: "added" }) }] };
+        } catch (e) {
+          return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+      }
+    );
+    this.mcp.tool(
+      "rvf_membership_remove",
+      "Remove a vector ID from the membership filter (COW branches only)",
+      {
+        storeId: z.string().describe("Store ID"),
+        id: z.number().int().describe("Vector ID to remove")
+      },
+      async ({ storeId, id }) => {
+        const handle = this.stores.get(storeId);
+        if (!handle)
+          return { content: [{ type: "text", text: `Store '${storeId}' not found` }] };
+        if (handle.readOnly)
+          return { content: [{ type: "text", text: "Error: store is read-only" }] };
+        try {
+          await handle.db.membershipRemove(id);
+          return { content: [{ type: "text", text: JSON.stringify({ success: true, id, action: "removed" }) }] };
+        } catch (e) {
+          return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+      }
+    );
+    this.mcp.tool(
+      "rvf_membership_count",
+      "Get the number of entries in the membership filter",
+      {
+        storeId: z.string().describe("Store ID")
+      },
+      async ({ storeId }) => {
+        const handle = this.stores.get(storeId);
+        if (!handle)
+          return { content: [{ type: "text", text: `Store '${storeId}' not found` }] };
+        try {
+          const count = await handle.db.membershipCount();
+          return { content: [{ type: "text", text: JSON.stringify({ count }) }] };
+        } catch (e) {
+          return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+      }
+    );
+  }
+  // ─── Resource Registration ──────────────────────────────────────────────
+  registerResources() {
+    this.mcp.resource(
+      "stores-list",
+      "rvf://stores",
+      { description: "List all open RVF stores and their status" },
+      async () => {
+        const handles = Array.from(this.stores.values());
+        const list = await Promise.all(
+          handles.map(async (h) => {
+            try {
+              const [status, dimension] = await Promise.all([
+                h.db.status(),
+                h.db.dimension()
+              ]);
+              return {
+                storeId: h.id,
+                path: h.path,
+                dimensions: dimension,
+                totalVectors: status.totalVectors
+              };
+            } catch {
+              return {
+                storeId: h.id,
+                path: h.path,
+                dimensions: null,
+                totalVectors: null
+              };
+            }
+          })
+        );
+        return {
+          contents: [{
+            uri: "rvf://stores",
+            mimeType: "application/json",
+            text: JSON.stringify({ stores: list }, null, 2)
+          }]
+        };
+      }
+    );
+  }
+  // ─── Prompt Registration ────────────────────────────────────────────────
+  registerPrompts() {
+    this.mcp.prompt(
+      "rvf-search",
+      "Search for similar vectors in an RVF store",
+      {
+        storeId: z.string().describe("Store ID to search"),
+        description: z.string().describe("Natural language description of what to search for")
+      },
+      async ({ storeId, description }) => ({
+        messages: [{
+          role: "user",
+          content: {
+            type: "text",
+            text: `Search the RVF store "${storeId}" for vectors similar to: "${description}". Use the rvf_query tool to perform the search. If you need to create an embedding from the description first, generate a suitable vector representation.`
+          }
+        }]
+      })
+    );
+    this.mcp.prompt(
+      "rvf-ingest",
+      "Ingest data into an RVF store",
+      {
+        storeId: z.string().describe("Store ID to ingest into"),
+        data: z.string().describe("Data to embed and ingest")
+      },
+      async ({ storeId, data }) => ({
+        messages: [{
+          role: "user",
+          content: {
+            type: "text",
+            text: `Ingest the following data into RVF store "${storeId}": ${data}. Generate appropriate vector embeddings and metadata, then use the rvf_ingest tool.`
+          }
+        }]
+      })
+    );
+  }
+  // ─── Connection ─────────────────────────────────────────────────────────
+  async connect(transport) {
+    await this.mcp.connect(transport);
+  }
+  async close() {
+    const handles = Array.from(this.stores.values());
+    await Promise.all(
+      handles.map(async (h) => {
+        try {
+          await h.db.close();
+        } catch {
+        }
+      })
+    );
+    this.stores.clear();
+    await this.mcp.close();
+  }
+  get storeCount() {
+    return this.stores.size;
+  }
+}
+export {
+  RvfMcpServer
+};

package/dist/transports.js

@@ -0,0 +1,53 @@
+import { RvfMcpServer } from "./server.js";
+async function createStdioServer(options) {
+  const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+  const server = new RvfMcpServer(options);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  return server;
+}
+async function createSseServer(port = 3100, options) {
+  const { SSEServerTransport } = await import("@modelcontextprotocol/sdk/server/sse.js");
+  const express = (await import("express")).default;
+  const app = express();
+  const server = new RvfMcpServer(options);
+  let sseTransport = null;
+  app.get("/sse", (req, res) => {
+    sseTransport = new SSEServerTransport("/messages", res);
+    server.connect(sseTransport).catch((err) => {
+      console.error("SSE connection error:", err);
+    });
+  });
+  app.post("/messages", (req, res) => {
+    if (!sseTransport) {
+      res.status(503).json({ error: "No SSE connection" });
+      return;
+    }
+    sseTransport.handlePostMessage(req, res);
+  });
+  app.get("/health", (_req, res) => {
+    res.json({
+      status: "ok",
+      server: options?.name ?? "rvf-mcp-server",
+      stores: server.storeCount
+    });
+  });
+  app.listen(port, () => {
+    console.error(`RVF MCP Server (SSE) listening on http://localhost:${port}`);
+    console.error(`  SSE endpoint:     http://localhost:${port}/sse`);
+    console.error(`  Message endpoint: http://localhost:${port}/messages`);
+    console.error(`  Health check:     http://localhost:${port}/health`);
+  });
+  return server;
+}
+async function createServer(transport = "stdio", port = 3100, options) {
+  if (transport === "sse") {
+    return createSseServer(port, options);
+  }
+  return createStdioServer(options);
+}
+export {
+  createServer,
+  createSseServer,
+  createStdioServer
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@quantic-impact/rvf-mcp-server",
+  "version": "0.2.0",
+  "description": "MCP server for RuVector Format (RVF) vector database with META_SEG, COW branching, and witness chain — stdio and SSE transports",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "rvf-mcp-server": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist/", "package.json"],
+  "keywords": ["rvf", "ruvector", "mcp", "vector-database", "model-context-protocol"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@quantic-impact/rvf": "0.2.0",
+    "express": "^4.18.0",
+    "zod": "^3.22.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}