@aeriondyseti/vector-memory-mcp 0.5.0 → 0.8.0

package/src/http/mcp-transport.ts

@@ -0,0 +1,255 @@
+/**
+ * MCP HTTP Transport Handler
+ *
+ * Provides StreamableHTTP transport for MCP over HTTP.
+ * and other HTTP-based MCP clients to connect to the memory server.
+ *
+ * This implementation handles the MCP protocol directly using Hono's streaming
+ * capabilities, since StreamableHTTPServerTransport expects Node.js req/res objects.
+ */
+
+import { Hono } from "hono";
+import { streamSSE } from "hono/streaming";
+import { randomUUID } from "node:crypto";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  type JSONRPCMessage,
+  type JSONRPCRequest,
+  type JSONRPCNotification,
+} from "@modelcontextprotocol/sdk/types.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+
+import { tools } from "../mcp/tools.js";
+import { handleToolCall } from "../mcp/handlers.js";
+import type { MemoryService } from "../services/memory.service.js";
+
+interface Session {
+  server: Server;
+  serverTransport: InstanceType<typeof InMemoryTransport>;
+  clientTransport: InstanceType<typeof InMemoryTransport>;
+  pendingResponses: Map<string | number, (response: JSONRPCMessage) => void>;
+  sseClients: Set<(message: JSONRPCMessage) => void>;
+}
+
+/**
+ * Creates MCP routes for a Hono app.
+ *
+ * Uses InMemoryTransport internally and bridges to HTTP/SSE manually,
+ * since StreamableHTTPServerTransport requires Node.js req/res objects.
+ */
+export function createMcpRoutes(memoryService: MemoryService): Hono {
+  const app = new Hono();
+
+  // Store active sessions by session ID
+  const sessions: Map<string, Session> = new Map();
+
+  /**
+   * Creates a new MCP server instance configured with memory tools.
+   */
+  async function createSession(): Promise<Session> {
+    const server = new Server(
+      { name: "vector-memory-mcp", version: "0.6.0" },
+      { capabilities: { tools: {} } }
+    );
+
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+      return { tools };
+    });
+
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+      return handleToolCall(name, args, memoryService);
+    });
+
+    // Create linked in-memory transports
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+
+    // Connect server to its transport
+    await server.connect(serverTransport);
+
+    const session: Session = {
+      server,
+      serverTransport,
+      clientTransport,
+      pendingResponses: new Map(),
+      sseClients: new Set(),
+    };
+
+    // Handle messages from server (responses and notifications)
+    clientTransport.onmessage = (message: JSONRPCMessage) => {
+      // Check if this is a response to a pending request
+      if ("id" in message && message.id !== undefined) {
+        const resolver = session.pendingResponses.get(message.id);
+        if (resolver) {
+          resolver(message);
+          session.pendingResponses.delete(message.id);
+          return;
+        }
+      }
+
+      // Otherwise, broadcast to SSE clients (notifications)
+      for (const sendToClient of session.sseClients) {
+        sendToClient(message);
+      }
+    };
+
+    return session;
+  }
+
+  /**
+   * Handle POST requests - session initialization and message handling
+   */
+  app.post("/mcp", async (c) => {
+    const sessionId = c.req.header("mcp-session-id");
+    const body = await c.req.json();
+
+    let session: Session | undefined;
+    let newSessionId: string | undefined;
+
+    if (sessionId && sessions.has(sessionId)) {
+      // Reuse existing session
+      session = sessions.get(sessionId)!;
+    } else if (isInitializeRequest(body)) {
+      // New session initialization
+      newSessionId = randomUUID();
+      session = await createSession();
+      sessions.set(newSessionId, session);
+      console.error(`[vector-memory-mcp] MCP session initialized: ${newSessionId}`);
+    } else {
+      // Invalid request - no session ID and not an initialize request
+      return c.json(
+        {
+          jsonrpc: "2.0",
+          error: {
+            code: -32000,
+            message: "Invalid session. Send initialize request without session ID to start.",
+          },
+          id: body.id ?? null,
+        },
+        400
+      );
+    }
+
+    // Send message to server and wait for response
+    const response = await sendAndWaitForResponse(session, body);
+
+    // Include session ID header for new sessions
+    if (newSessionId) {
+      c.header("mcp-session-id", newSessionId);
+    }
+
+    return c.json(response);
+  });
+
+  /**
+   * Handle GET requests - SSE stream for server-to-client notifications
+   */
+  app.get("/mcp", async (c) => {
+    const sessionId = c.req.header("mcp-session-id");
+
+    if (!sessionId || !sessions.has(sessionId)) {
+      return c.json(
+        {
+          jsonrpc: "2.0",
+          error: { code: -32000, message: "Invalid or missing session ID" },
+          id: null,
+        },
+        400
+      );
+    }
+
+    const session = sessions.get(sessionId)!;
+
+    return streamSSE(c, async (stream) => {
+      // Register this SSE client
+      const sendMessage = (message: JSONRPCMessage) => {
+        stream.writeSSE({
+          data: JSON.stringify(message),
+          event: "message",
+        });
+      };
+
+      session.sseClients.add(sendMessage);
+
+      // Keep connection open
+      try {
+        // Send a ping every 30 seconds to keep connection alive
+        while (true) {
+          await stream.sleep(30000);
+          await stream.writeSSE({ event: "ping", data: "" });
+        }
+      } finally {
+        session.sseClients.delete(sendMessage);
+      }
+    });
+  });
+
+  /**
+   * Handle DELETE requests - session termination
+   */
+  app.delete("/mcp", async (c) => {
+    const sessionId = c.req.header("mcp-session-id");
+
+    if (!sessionId || !sessions.has(sessionId)) {
+      return c.json(
+        {
+          jsonrpc: "2.0",
+          error: { code: -32000, message: "Invalid or missing session ID" },
+          id: null,
+        },
+        400
+      );
+    }
+
+    const session = sessions.get(sessionId)!;
+
+    // Close transports
+    await session.clientTransport.close();
+    await session.serverTransport.close();
+    await session.server.close();
+
+    sessions.delete(sessionId);
+    console.error(`[vector-memory-mcp] MCP session closed: ${sessionId}`);
+
+    return c.json({ success: true });
+  });
+
+  return app;
+}
+
+/**
+ * Send a message to the server and wait for its response.
+ */
+async function sendAndWaitForResponse(
+  session: Session,
+  message: JSONRPCRequest | JSONRPCNotification
+): Promise<JSONRPCMessage> {
+  return new Promise((resolve) => {
+    // Register response handler for requests (messages with id)
+    if ("id" in message && message.id !== undefined) {
+      session.pendingResponses.set(message.id, resolve);
+    }
+
+    // Send message to server
+    session.clientTransport.send(message);
+
+    // For notifications (no id), resolve immediately with empty response
+    if (!("id" in message) || message.id === undefined) {
+      resolve({ jsonrpc: "2.0" } as JSONRPCMessage);
+    }
+  });
+}
+
+/**
+ * Check if a message is an initialize request.
+ */
+function isInitializeRequest(body: unknown): boolean {
+  return (
+    typeof body === "object" &&
+    body !== null &&
+    "method" in body &&
+    (body as { method: string }).method === "initialize"
+  );
+}

package/src/http/server.ts

@@ -3,58 +3,43 @@ import { cors } from "hono/cors";
 import type { MemoryService } from "../services/memory.service.js";
 import type { Config } from "../config/index.js";
 import { isDeleted } from "../types/memory.js";
+import { createMcpRoutes } from "./mcp-transport.js";
+import type { Memory } from "../types/memory.js";
 
 export interface HttpServerOptions {
   memoryService: MemoryService;
   config: Config;
 }
 
-export function createHttpApp(memoryService: MemoryService): Hono {
+// Track server start time for uptime calculation
+const startedAt = Date.now();
+
+export function createHttpApp(memoryService: MemoryService, config: Config): Hono {
   const app = new Hono();
 
   // Enable CORS for local development
   app.use("/*", cors());
 
-  // Health check endpoint
-  app.get("/health", (c) => {
-    return c.json({ status: "ok", timestamp: new Date().toISOString() });
-  });
-
-  // Context endpoint for Claude Code hooks
-  // Returns relevant memories formatted for injection into conversation
-  app.post("/context", async (c) => {
-    try {
-      const body = await c.req.json();
-      const query = body.query;
+  // Mount MCP routes for StreamableHTTP transport
+  const mcpApp = createMcpRoutes(memoryService);
+  app.route("/", mcpApp);
 
-      if (!query || typeof query !== "string") {
-        return c.json({ error: "Missing or invalid 'query' field" }, 400);
-      }
-
-      const memories = await memoryService.search(query, 5);
-
-      if (memories.length === 0) {
-        return c.json({ context: null });
-      }
-
-      // Format memories for context injection
-      const contextLines = memories.map((m, i) => {
-        const metadata = m.metadata as Record<string, unknown>;
-        const type = metadata.type ? `[${metadata.type}]` : "";
-        const date = m.createdAt.toISOString().split("T")[0];
-        return `${i + 1}. ${type} (${date}): ${m.content}`;
-      });
-
-      const context = `<relevant-memories>\n${contextLines.join("\n")}\n</relevant-memories>`;
-
-      return c.json({ context, count: memories.length });
-    } catch (error) {
-      const message = error instanceof Error ? error.message : "Unknown error";
-      return c.json({ error: message }, 500);
-    }
+  // Health check endpoint with config info
+  app.get("/health", (c) => {
+    return c.json({
+      status: "ok",
+      timestamp: new Date().toISOString(),
+      pid: process.pid,
+      uptime: Math.floor((Date.now() - startedAt) / 1000),
+      config: {
+        dbPath: config.dbPath,
+        embeddingModel: config.embeddingModel,
+        embeddingDimension: config.embeddingDimension,
+      },
+    });
   });
 
-  // Search endpoint (more detailed than /context)
+  // Search endpoint
   app.post("/search", async (c) => {
     try {
       const body = await c.req.json();
@@ -125,6 +110,38 @@ export function createHttpApp(memoryService: MemoryService): Hono {
     }
   });
 
+  // Get latest handoff
+  app.get("/handoff", async (c) => {
+    try {
+      const handoff = await memoryService.getLatestHandoff();
+
+      if (!handoff) {
+        return c.json({ error: "No handoff found" }, 404);
+      }
+
+      // Fetch referenced memories if any
+      const memoryIds = (handoff.metadata.memory_ids as string[] | undefined) ?? [];
+      const referencedMemories: Array<{ id: string; content: string }> = [];
+
+      for (const id of memoryIds) {
+        const memory = await memoryService.get(id);
+        if (memory && !isDeleted(memory)) {
+          referencedMemories.push({ id: memory.id, content: memory.content });
+        }
+      }
+
+      return c.json({
+        content: handoff.content,
+        metadata: handoff.metadata,
+        referencedMemories,
+        updatedAt: handoff.updatedAt.toISOString(),
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      return c.json({ error: message }, 500);
+    }
+  });
+
   // Get single memory
   app.get("/memories/:id", async (c) => {
     try {
@@ -155,7 +172,7 @@ export async function startHttpServer(
   memoryService: MemoryService,
   config: Config
 ): Promise<{ stop: () => void }> {
-  const app = createHttpApp(memoryService);
+  const app = createHttpApp(memoryService, config);
 
   const server = Bun.serve({
     port: config.httpPort,

package/src/index.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { config } from "./config/index.js";
+import { loadConfig, parseCliArgs } from "./config/index.js";
 import { connectToDatabase } from "./db/connection.js";
 import { MemoryRepository } from "./db/memory.repository.js";
 import { EmbeddingsService } from "./services/embeddings.service.js";
@@ -9,14 +9,19 @@ import { startServer } from "./mcp/server.js";
 import { startHttpServer } from "./http/server.js";
 
 async function main(): Promise<void> {
-  // Check for warmup command
   const args = process.argv.slice(2);
+
+  // Check for warmup command
   if (args[0] === "warmup") {
     const { warmup } = await import("../scripts/warmup.js");
     await warmup();
     return;
   }
 
+  // Parse CLI args and load config
+  const overrides = parseCliArgs(args);
+  const config = loadConfig(overrides);
+
   // Initialize database
   const db = await connectToDatabase(config.dbPath);
 
@@ -25,13 +30,41 @@ async function main(): Promise<void> {
   const embeddings = new EmbeddingsService(config.embeddingModel, config.embeddingDimension);
   const memoryService = new MemoryService(repository, embeddings);
 
-  // Start HTTP server if enabled
+  // Track cleanup functions
+  let httpStop: (() => void) | null = null;
+
+  // Graceful shutdown handler
+  const shutdown = () => {
+    console.error("[vector-memory-mcp] Shutting down...");
+    if (httpStop) httpStop();
+    db.close();
+    process.exit(0);
+  };
+
+  // Handle signals and stdin close (parent process exit)
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+  process.stdin.on("close", shutdown);
+  process.stdin.on("end", shutdown);
+
+  // Start HTTP server if transport mode includes it
   if (config.enableHttp) {
-    await startHttpServer(memoryService, config);
+    const http = await startHttpServer(memoryService, config);
+    httpStop = http.stop;
+    console.error(
+      `[vector-memory-mcp] MCP available at http://${config.httpHost}:${config.httpPort}/mcp`
+    );
   }
 
-  // Start MCP server (stdio)
-  await startServer(memoryService);
+  // Start stdio transport unless in HTTP-only mode
+  if (config.transportMode !== "http") {
+    await startServer(memoryService);
+  } else {
+    // In HTTP-only mode, keep the process running
+    console.error("[vector-memory-mcp] Running in HTTP-only mode (no stdio)");
+    // Keep process alive - the HTTP server runs indefinitely
+    await new Promise(() => {});
+  }
 }
 
 main().catch(console.error);