@esankhan3/code-search-mcp 0.4.11 → 0.4.12

package/dist/__tests__/http-stateless.test.js

@@ -0,0 +1,50 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { startHttpTransport } from "../transports/http-transport.js";
+function makeMcpServer() {
+  const server = new Server(
+    { name: "stateless-test", version: "0.0.0" },
+    { capabilities: { tools: {} } }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [{ name: "ping", description: "test tool", inputSchema: { type: "object" } }]
+  }));
+  return server;
+}
+const config = {
+  port: 0,
+  host: "127.0.0.1",
+  transport: "streamable-http",
+  authEnabled: false,
+  authMode: "none",
+  authApiKeys: []
+};
+describe("http transport \u2014 stateless mode (cluster workers)", () => {
+  it("serves initialize + tools/list as independent sessionless requests", async () => {
+    const httpServer = await startHttpTransport({
+      config,
+      stateless: true,
+      createMcpServer: async () => ({ server: makeMcpServer() })
+    });
+    const base = `http://127.0.0.1:${httpServer.address().port}`;
+    try {
+      const client = new Client({ name: "test-client", version: "1.0.0" });
+      const transport = new StreamableHTTPClientTransport(new URL(`${base}/mcp`));
+      await client.connect(transport);
+      const tools = await client.listTools();
+      assert.equal(tools.tools[0]?.name, "ping");
+      assert.equal(transport.sessionId, void 0, "stateless server must not assign a session");
+      await client.close();
+      const get = await fetch(`${base}/mcp`, { method: "GET" });
+      assert.equal(get.status, 405);
+      const del = await fetch(`${base}/mcp`, { method: "DELETE" });
+      assert.equal(del.status, 405);
+    } finally {
+      httpServer.close();
+    }
+  });
+});

package/dist/server.js

@@ -7,7 +7,8 @@ import {
   ReadResourceRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
+import cluster from "node:cluster";
 import { registerSearchTools, handleSearchTool } from "./tools/search.js";
 import { registerGraphTools, handleGraphTool } from "./tools/graph.js";
 import { registerProfileTools, handleProfileTool } from "./tools/profile.js";
@@ -75,19 +76,31 @@ async function startServer(projectName, directoryPath) {
   };
   const llmInfo = config.llmMode === "none" ? "disabled (profiling + service mesh skipped)" : config.llmMode === "api" ? `api \u2192 ${config.llmProvider}/${config.llmModel}${config.llmApiKey ? "" : " (WARNING: no API key!)"}` : `cli \u2192 ${config.claudeBin}`;
   console.error(`[code-search-mcp] LLM: ${llmInfo}`);
-  await autoIndex(ctx);
+  await autoIndex(ctx, { readOnly: cluster.isWorker });
   if (config.transport === "stdio") {
     const server = createMcpServerInstance(ctx);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error(`[code-search-mcp] Server running for "${projectName}" (stdio)`);
   } else {
+    const workerCount = parseWorkerCount();
+    if (workerCount > 1 && cluster.isPrimary) {
+      armScheduledReindex(ctx, () => broadcastInvalidate(ctx));
+      runClusterPrimary(ctx, workerCount);
+      return;
+    }
     if (config.authMode === "none" && config.host !== "127.0.0.1" && config.host !== "localhost") {
       console.error(`[code-search-mcp] WARNING: Auth is disabled but server binds to ${config.host}. Any machine on the network can access your code search API.`);
       console.error(`[code-search-mcp] Set CODE_SEARCH_AUTH_MODE=api-key or CODE_SEARCH_HOST=127.0.0.1 for security.`);
     }
+    const isReadOnlyWorker = cluster.isWorker;
+    if (isReadOnlyWorker) registerWorkerIpc(ctx);
     await startHttpTransport({
       config,
+      // Workers must be stateless: the fronting proxy opens a new upstream
+      // connection per request, so in-memory MCP sessions cannot stick to one
+      // worker. Also opt-in for single-process deploys via env.
+      stateless: isReadOnlyWorker || process.env.CODE_SEARCH_STATELESS === "1",
       createMcpServer: async () => ({
         server: createMcpServerInstance(ctx)
       }),
@@ -116,35 +129,12 @@ async function startServer(projectName, directoryPath) {
           elapsedMs: ctx.indexing.startedAt ? Date.now() - ctx.indexing.startedAt : null
         }
       }),
-      onIndex: async (body) => {
-        const { resolve } = await import("node:path");
-        const { existsSync: existsSync2 } = await import("node:fs");
-        const dirPath = resolve(body.path);
-        if (!existsSync2(dirPath)) {
-          throw new Error(`Path does not exist: ${dirPath}`);
-        }
-        if (ctx.indexing.status === "indexing") {
-          throw new Error(`Indexing already in progress (phase: ${ctx.indexing.phase}). Wait for it to complete or check GET /status.`);
-        }
-        const project = body.project || dirPath.split("/").filter(Boolean).pop() || "project";
-        const stats = await trackedIndex(ctx, project, dirPath, {
-          force: body.force,
-          label: "admin-index"
-        });
-        ctx.projectName = project;
-        ctx.directoryPath = dirPath;
-        return {
-          status: "ok",
-          project,
-          path: dirPath,
-          chunks: stats.totalChunks,
-          repos: stats.repos.length,
-          crossRepoEdges: stats.crossRepoEdges,
-          durationMs: stats.indexDurationMs
-        };
-      }
+      onIndex: (body) => isReadOnlyWorker ? forwardIndexToPrimary(body) : runAdminIndex(ctx, body)
     });
   }
+  if (!cluster.isWorker) armScheduledReindex(ctx);
+}
+function armScheduledReindex(ctx, onSuccess) {
   const reindexIntervalMs = parseReindexInterval();
   if (reindexIntervalMs > 0 && ctx.directoryPath) {
     console.error(`[code-search-mcp] Auto-reindex every ${Math.round(reindexIntervalMs / 6e4)}m`);
@@ -152,12 +142,128 @@ async function startServer(projectName, directoryPath) {
       if (!ctx.directoryPath || ctx.indexing.status === "indexing") return;
       try {
         await trackedIndex(ctx, ctx.projectName, ctx.directoryPath, { label: "auto-reindex" });
+        onSuccess?.();
       } catch (err) {
         console.error(`[auto-reindex] Failed:`, err);
       }
     }, reindexIntervalMs).unref();
   }
 }
+async function runAdminIndex(ctx, body) {
+  const dirPath = resolve(body.path);
+  if (!existsSync(dirPath)) {
+    throw new Error(`Path does not exist: ${dirPath}`);
+  }
+  if (ctx.indexing.status === "indexing") {
+    throw new Error(`Indexing already in progress (phase: ${ctx.indexing.phase}). Wait for it to complete or check GET /status.`);
+  }
+  const project = body.project || dirPath.split("/").filter(Boolean).pop() || "project";
+  const stats = await trackedIndex(ctx, project, dirPath, {
+    force: body.force,
+    label: "admin-index"
+  });
+  ctx.projectName = project;
+  ctx.directoryPath = dirPath;
+  return {
+    status: "ok",
+    project,
+    path: dirPath,
+    chunks: stats.totalChunks,
+    repos: stats.repos.length,
+    crossRepoEdges: stats.crossRepoEdges,
+    durationMs: stats.indexDurationMs
+  };
+}
+function broadcastInvalidate(ctx) {
+  const msg = { type: "csm:invalidate", project: ctx.projectName, directoryPath: ctx.directoryPath };
+  for (const w of Object.values(cluster.workers ?? {})) {
+    try {
+      w?.send(msg);
+    } catch {
+    }
+  }
+}
+function parseWorkerCount() {
+  const n = parseInt(process.env.CODE_SEARCH_WORKERS ?? "", 10);
+  return Number.isFinite(n) && n > 1 ? Math.min(n, 16) : 1;
+}
+function runClusterPrimary(ctx, workerCount) {
+  console.error(`[code-search-mcp] Cluster primary ${process.pid}: forking ${workerCount} read-only workers (stateless MCP)`);
+  let shuttingDown = false;
+  const send = (w, msg) => {
+    try {
+      w?.send(msg);
+    } catch {
+    }
+  };
+  cluster.on("message", (worker, msg) => {
+    if (msg?.type !== "csm:index") return;
+    void (async () => {
+      try {
+        const result = await runAdminIndex(ctx, msg.body);
+        broadcastInvalidate(ctx);
+        send(worker, { type: "csm:index-result", id: msg.id, ok: true, result });
+      } catch (err) {
+        send(worker, {
+          type: "csm:index-result",
+          id: msg.id,
+          ok: false,
+          error: err instanceof Error ? err.message : String(err)
+        });
+      }
+    })();
+  });
+  cluster.on("exit", (worker, code, signal) => {
+    if (shuttingDown) return;
+    console.error(`[code-search-mcp] Worker ${worker.process.pid} exited (${signal ?? code}) \u2014 respawning`);
+    cluster.fork();
+  });
+  const shutdown = (sig) => {
+    shuttingDown = true;
+    for (const w of Object.values(cluster.workers ?? {})) {
+      try {
+        w?.kill(sig);
+      } catch {
+      }
+    }
+    process.exit(0);
+  };
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  for (let i = 0; i < workerCount; i++) cluster.fork();
+}
+let ipcSeq = 0;
+const pendingIndexRequests = /* @__PURE__ */ new Map();
+function forwardIndexToPrimary(body) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    if (!process.send) {
+      rejectPromise(new Error("IPC channel unavailable \u2014 not a cluster worker"));
+      return;
+    }
+    const id = ++ipcSeq;
+    pendingIndexRequests.set(id, { resolve: resolvePromise, reject: rejectPromise });
+    const msg = { type: "csm:index", id, body };
+    process.send(msg);
+  });
+}
+function registerWorkerIpc(ctx) {
+  process.on("message", (msg) => {
+    if (msg?.type === "csm:index-result") {
+      const pending = pendingIndexRequests.get(msg.id);
+      if (!pending) return;
+      pendingIndexRequests.delete(msg.id);
+      if (msg.ok) pending.resolve(msg.result ?? {});
+      else pending.reject(new Error(msg.error ?? "Index failed"));
+    } else if (msg?.type === "csm:invalidate") {
+      void invalidateRetriever(msg.project).catch(() => {
+      });
+      ctx.projectName = msg.project;
+      if (msg.directoryPath) ctx.directoryPath = msg.directoryPath;
+      ctx.indexReady = true;
+    }
+  });
+  process.on("disconnect", () => process.exit(0));
+}
 function parseReindexInterval() {
   const raw = process.env.CODE_SEARCH_REINDEX_INTERVAL?.trim();
   if (!raw || raw === "0" || raw === "none") return 0;
@@ -224,7 +330,7 @@ async function trackedIndex(ctx, project, dirPath, opts) {
     throw err;
   }
 }
-async function autoIndex(ctx) {
+async function autoIndex(ctx, opts) {
   try {
     const kbPath = getKnowledgeBasePath(ctx.projectName);
     const hasLanceDB = existsSync(join(kbPath, "lancedb"));
@@ -234,6 +340,10 @@ async function autoIndex(ctx) {
       console.error(`[code-search-mcp] Index loaded for "${ctx.projectName}"`);
       return;
     }
+    if (opts?.readOnly) {
+      console.error(`[code-search-mcp] No index yet \u2014 read-only worker waiting for the writer`);
+      return;
+    }
     if (!ctx.directoryPath) {
       console.error(`[code-search-mcp] No index found and no directory path \u2014 tools will return empty results`);
       return;

package/dist/transports/http-transport.js

@@ -117,6 +117,31 @@ async function startHttpTransport(opts) {
         const identity = authenticate(req, res);
         if (!identity) return;
       }
+      if (req.method === "POST" && opts.stateless) {
+        try {
+          const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: void 0,
+            enableJsonResponse: true
+          });
+          const { server: mcpServer } = await createMcpServer();
+          res.on("close", () => {
+            void transport.close();
+          });
+          await mcpServer.connect(transport);
+          await transport.handleRequest(req, res);
+        } catch {
+          if (!res.headersSent) {
+            res.writeHead(500, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Request handling failed" }));
+          }
+        }
+        return;
+      }
+      if ((req.method === "GET" || req.method === "DELETE") && opts.stateless) {
+        res.writeHead(405, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Stateless mode: sessions are not supported" }));
+        return;
+      }
       if (req.method === "POST") {
         const sessionId = req.headers["mcp-session-id"];
         if (sessionId && sessions.has(sessionId)) {
@@ -194,7 +219,7 @@ async function startHttpTransport(opts) {
     httpServer.listen(config.port, config.host, () => {
       const url = `http://${config.host === "0.0.0.0" ? "localhost" : config.host}:${config.port}`;
       onReady?.(url);
-      resolve();
+      resolve(httpServer);
     });
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esankhan3/code-search-mcp",
-  "version": "0.4.11",
+  "version": "0.4.12",
   "description": "MCP server for multi-repo code search — GitHub org or local path, zero config",
   "type": "module",
   "license": "MIT",