@esankhan3/code-search-mcp 1.0.5 → 1.1.0

package/dist/index.js

@@ -1,51 +1,13 @@
 #!/usr/bin/env node
-import { resolve } from "node:path";
+import { resolve, basename, join } from "node:path";
 import { existsSync } from "node:fs";
-import { printConfig, resolveCodeSearchConfig, parseCliFlags } from "./core/config.js";
-const args = process.argv.slice(2);
-if (args.includes("--print-config")) {
-  const { patch } = parseCliFlags(args.filter((a) => a !== "--print-config"));
-  const cfg = resolveCodeSearchConfig({ cli: patch });
-  process.stdout.write(printConfig(cfg) + "\n");
-  process.exit(0);
-}
-let mode = "remote";
-let remoteUrl = null;
-let apiKey;
-let source = null;
-let projectName = null;
-let githubToken;
-let force = false;
-let port;
-let transport;
-let authMode;
-for (let i = 0; i < args.length; i++) {
-  if (args[i] === "--remote" && args[i + 1]) {
-    mode = "remote";
-    remoteUrl = args[++i];
-  } else if (args[i] === "--local") {
-    mode = "local";
-    if (args[i + 1] && !args[i + 1].startsWith("--")) {
-      source = args[++i];
-    }
-  } else if (args[i] === "--serve") {
-    mode = "serve";
-  } else if (args[i] === "--api-key" && args[i + 1]) {
-    apiKey = args[++i];
-  } else if (args[i] === "--project" && args[i + 1]) {
-    projectName = args[++i];
-  } else if (args[i] === "--token" && args[i + 1]) {
-    githubToken = args[++i];
-  } else if (args[i] === "--force") {
-    force = true;
-  } else if (args[i] === "--port" && args[i + 1]) {
-    port = args[++i];
-  } else if (args[i] === "--transport" && args[i + 1]) {
-    transport = args[++i];
-  } else if (args[i] === "--auth" && args[i + 1]) {
-    authMode = args[++i];
-  } else if (args[i] === "--help" || args[i] === "-h") {
-    console.error(`
+import { homedir } from "node:os";
+import { printConfig, resolveCodeSearchConfig, parseCliFlags, exportDataDir } from "./core/config.js";
+import { loadServerConfig } from "./core/env-config.js";
+import { validateProjectName } from "./core/project-name.js";
+import { configureLogger, getComponentLogger } from "./observability/logger.js";
+const log = getComponentLogger("code-search-mcp");
+const HELP = `
 Code Search MCP \u2014 multi-repo code intelligence via MCP
 
 REMOTE MODE (default \u2014 connects to a deployed server):
@@ -70,7 +32,7 @@ REMOTE MODE (default \u2014 connects to a deployed server):
       }
     }
 
-LOCAL MODE (self-hosted \u2014 indexes repos locally):
+LOCAL MODE (self-hosted \u2014 indexes repos locally, serves over stdio):
   code-search-mcp --local /path/to/repos             Index local directory
   code-search-mcp --local github:org-name             Clone from GitHub org
   code-search-mcp --local --project my-project        Serve existing index
@@ -78,45 +40,111 @@ LOCAL MODE (self-hosted \u2014 indexes repos locally):
   Options:
     --project <name>        Project name (default: derived from source)
     --token <token>         GitHub token (or GITHUB_TOKEN env)
-    --force                 Force full re-index
+    --force                 Force a full re-index at startup
 
-SERVER MODE (deploy as HTTP service):
-  code-search-mcp --serve                             Start HTTP server
-  code-search-mcp --serve --port 3100 --auth api-key
+SERVER MODE (deploy as HTTP service \u2014 Streamable HTTP on /mcp):
+  code-search-mcp --serve [path]                      Start HTTP server (project "default")
+  code-search-mcp --serve /repos --port 3100 --auth api-key
+  (--local <path> --serve and --serve --local <path> are equivalent)
 
   Options:
-    --port <port>           HTTP port (default: 3100)
-    --auth <mode>           none | api-key | jwt
-    --transport <mode>      streamable-http | sse
+    --port <port>           HTTP port (default: 3100) = --server.port
+    --host <host>           Bind address = --server.host
+    --auth <mode>           none | api-key | jwt = --auth.mode
+    --project <name>        Project name (default: "default")
 
   Environment:
-    CODE_SEARCH_TRANSPORT           streamable-http | sse
     CODE_SEARCH_PORT                HTTP port (default: 3100)
     CODE_SEARCH_AUTH_MODE           none | api-key | jwt
     CODE_SEARCH_AUTH_API_KEYS       Comma-separated API keys
     CODE_SEARCH_EMBEDDING_PROVIDER  auto | codestral | openai | voyage | ollama | custom
     CODE_SEARCH_EMBEDDING_API_KEY   Unified embedding API key
     CODE_SEARCH_DATA_DIR            Data directory override
-`);
-    process.exit(0);
-  } else if (!args[i].startsWith("-")) {
-    const arg = args[i];
-    if (arg.startsWith("http://") || arg.startsWith("https://")) {
-      mode = "remote";
-      remoteUrl = arg;
-    } else {
-      mode = "local";
-      source = arg;
-    }
+
+CONFIG (every mode):
+  --<dotted.path> <value>   Any CodeSearchConfig leaf, e.g. --retrieval.max-chunks 12
+  --print-config            Print the resolved config (secrets redacted) and exit
+`;
+function usageError(msg) {
+  log.error(`${msg} \u2014 see --help`);
+  process.exit(2);
+}
+const { patch, rest, unknown } = parseCliFlags(process.argv.slice(2));
+if (unknown.length) usageError(`unknown flag(s): ${unknown.join(", ")}`);
+let printOnly = false;
+let serve = false;
+let local = false;
+let remoteUrl = null;
+let apiKey;
+let source = null;
+let projectName = null;
+let githubToken;
+let force = false;
+for (let i = 0; i < rest.length; i++) {
+  const arg = rest[i];
+  const value = () => {
+    const v = rest[i + 1];
+    if (v === void 0 || v.startsWith("--")) usageError(`${arg} needs a value`);
+    i++;
+    return v;
+  };
+  const optionalPath = () => rest[i + 1] !== void 0 && !rest[i + 1].startsWith("-") ? rest[++i] : null;
+  switch (arg) {
+    case "--print-config":
+      printOnly = true;
+      break;
+    case "--remote":
+      remoteUrl = value();
+      break;
+    case "--local":
+      local = true;
+      source = optionalPath() ?? source;
+      break;
+    case "--serve":
+      serve = true;
+      source = optionalPath() ?? source;
+      break;
+    case "--api-key":
+      apiKey = value();
+      break;
+    case "--project":
+      projectName = value();
+      break;
+    case "--token":
+      githubToken = value();
+      break;
+    case "--force":
+      force = true;
+      break;
+    case "--help":
+    case "-h":
+      process.stderr.write(HELP);
+      process.exit(0);
+    default:
+      if (arg.startsWith("-")) usageError(`unknown flag: ${arg}`);
+      if (/^https?:\/\//.test(arg)) remoteUrl = arg;
+      else source = arg;
   }
 }
+const mode = serve ? "serve" : remoteUrl ? "remote" : local || source ? "local" : "remote";
+const workspaceDir = source && !source.startsWith("github:") ? resolve(source) : process.cwd();
+const preview = resolveCodeSearchConfig({ cli: patch, workspaceDir });
+if (preview.server.transport === "sse") {
+  usageError("SSE transport is not supported \u2014 the server speaks Streamable HTTP on /mcp (drop --transport / CODE_SEARCH_TRANSPORT)");
+}
+if (mode === "serve") patch.server = { ...patch.server, transport: "streamable-http" };
+if (printOnly) {
+  process.stdout.write(printConfig(resolveCodeSearchConfig({ cli: patch, workspaceDir })) + "\n");
+  process.exit(0);
+}
+configureLogger({ structured: preview.telemetry.structuredLogs });
 (async () => {
   try {
     if (mode === "remote") {
       const serverUrl = remoteUrl ?? process.env.CODE_SEARCH_SERVER ?? process.env.CODE_SEARCH_REMOTE_URL;
       const key = apiKey ?? process.env.CODE_SEARCH_API_KEY ?? process.env.CODE_SEARCH_AUTH_API_KEY;
       if (!serverUrl) {
-        console.error(`[code-search-mcp] No remote server configured.
+        log.error(`No remote server configured.
 
 Set CODE_SEARCH_SERVER environment variable:
   export CODE_SEARCH_SERVER=https://your-server:3100
@@ -136,14 +164,8 @@ For help:
       await startRemoteProxy({ serverUrl, apiKey: key });
       return;
     }
-    if (mode === "serve") {
-      if (port) process.env.CODE_SEARCH_PORT = port;
-      if (authMode) process.env.CODE_SEARCH_AUTH_MODE = authMode;
-      process.env.CODE_SEARCH_TRANSPORT = transport === "sse" ? "sse" : "streamable-http";
-      const { startServer: startServer2 } = await import("./server.js");
-      await startServer2(projectName ?? "default", source ? resolve(source) : null);
-      return;
-    }
+    const config = loadServerConfig({ cli: patch, workspaceDir });
+    exportDataDir(config.__unified);
     let directoryPath = null;
     if (source?.startsWith("github:")) {
       const { cloneOrUpdateOrg } = await import("./sources/github-org.js");
@@ -151,34 +173,36 @@ For help:
       const slashIdx = spec.indexOf("/");
       const org = slashIdx > 0 ? spec.slice(0, slashIdx) : spec;
       const pattern = slashIdx > 0 ? spec.slice(slashIdx + 1) : void 0;
-      if (!projectName) projectName = org;
-      console.error(`[code-search-mcp] Cloning repos from github:${org}${pattern ? `/${pattern}` : ""}...`);
+      if (!projectName && mode === "local") projectName = org;
+      log.info(`Cloning repos from github:${org}${pattern ? `/${pattern}` : ""}...`);
       const repos = await cloneOrUpdateOrg(org, {
         pattern,
         token: githubToken,
-        onProgress: (m) => console.error(m)
+        onProgress: (m) => log.info(m)
       });
-      console.error(`[code-search-mcp] ${repos.length} repos ready`);
-      const { homedir } = await import("node:os");
-      const { join } = await import("node:path");
+      log.info(`${repos.length} repos ready`);
       directoryPath = join(homedir(), ".code-search", org);
     } else if (source) {
       directoryPath = resolve(source);
       if (!existsSync(directoryPath)) {
-        console.error(`[code-search-mcp] Directory not found: ${directoryPath}`);
+        log.error(`Directory not found: ${directoryPath}`);
         process.exit(1);
       }
-      if (!projectName) {
-        projectName = directoryPath.split("/").filter(Boolean).pop() || "project";
-      }
-    } else if (!projectName) {
+    } else if (local && !projectName) {
       directoryPath = process.cwd();
-      projectName = directoryPath.split("/").filter(Boolean).pop() || "project";
+    }
+    if (!projectName) {
+      projectName = mode === "serve" ? "default" : directoryPath && basename(directoryPath) || "project";
+    }
+    try {
+      validateProjectName(projectName);
+    } catch (err) {
+      usageError(err.message);
     }
     const { startServer } = await import("./server.js");
-    await startServer(projectName, directoryPath);
+    await startServer(projectName, directoryPath, { force });
   } catch (err) {
-    console.error(`[code-search-mcp] Fatal:`, err);
+    log.error(`Fatal: ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
     process.exit(1);
   }
 })();

package/dist/middleware/auth.js

@@ -1,22 +1,5 @@
-import { createHmac, timingSafeEqual } from "node:crypto";
-const rateBuckets = /* @__PURE__ */ new Map();
-function checkRateLimit(identity, maxPerMinute) {
-  const now = Date.now();
-  const bucket = rateBuckets.get(identity);
-  if (!bucket || now > bucket.resetAt) {
-    rateBuckets.set(identity, { count: 1, resetAt: now + 6e4 });
-    return true;
-  }
-  if (bucket.count >= maxPerMinute) return false;
-  bucket.count++;
-  return true;
-}
-setInterval(() => {
-  const now = Date.now();
-  for (const [key, bucket] of rateBuckets) {
-    if (now > bucket.resetAt) rateBuckets.delete(key);
-  }
-}, 3e5).unref();
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { localRateLimiter } from "./rate-limit.js";
 function verifyJwt(token, secret, issuer) {
   try {
     const parts = token.split(".");
@@ -31,7 +14,9 @@ function verifyJwt(token, secret, issuer) {
       return null;
     }
     const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString());
-    if (payload.exp && payload.exp < Math.floor(Date.now() / 1e3)) return null;
+    const now = Math.floor(Date.now() / 1e3);
+    if (typeof payload.exp !== "number" || payload.exp <= now) return null;
+    if (payload.nbf !== void 0 && (typeof payload.nbf !== "number" || payload.nbf > now)) return null;
     if (issuer && payload.iss !== issuer) return null;
     return { sub: payload.sub ?? "unknown", scope: payload.scope };
   } catch {
@@ -44,64 +29,47 @@ function safeCompare(a, b) {
   if (bufA.length !== bufB.length) return false;
   return timingSafeEqual(bufA, bufB);
 }
-function createAuthMiddleware(config) {
-  return function authenticate(req, res) {
+function apiKeySubject(key) {
+  return `key:${createHash("sha256").update(key).digest("hex").slice(0, 16)}`;
+}
+function createAuthMiddleware(config, opts = {}) {
+  if (config.authMode === "jwt" && !config.authJwtSecret) {
+    throw new Error('Auth mode "jwt" needs a signing secret: set CODE_SEARCH_AUTH_JWT_SECRET (or auth.jwt_secret in config).');
+  }
+  const rateLimiter = opts.rateLimiter ?? localRateLimiter;
+  const reject = (res, status, error, headers = {}) => {
+    res.writeHead(status, { "Content-Type": "application/json", ...headers });
+    res.end(JSON.stringify({ error }));
+    return null;
+  };
+  return async function authenticate(req, res) {
     if (config.authMode === "none") {
       return { mode: "anonymous", subject: "anonymous", scopes: ["*"] };
     }
     const authHeader = req.headers.authorization;
-    if (!authHeader?.startsWith("Bearer ")) {
-      res.writeHead(401, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ error: "Missing Authorization header" }));
-      return null;
-    }
+    if (!authHeader?.startsWith("Bearer ")) return reject(res, 401, "Missing Authorization header");
     const token = authHeader.slice(7);
+    let identity;
     if (config.authMode === "api-key") {
       const matched = config.authApiKeys.some((key) => safeCompare(token, key));
-      if (!matched) {
-        res.writeHead(401, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ error: "Invalid API key" }));
-        return null;
-      }
-      const identity = {
-        mode: "api-key",
-        subject: `key:${token.slice(0, 8)}...`,
-        scopes: ["*"]
-      };
-      if (!checkRateLimit(identity.subject, config.rateLimitPerMinute)) {
-        res.writeHead(429, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ error: "Rate limit exceeded" }));
-        return null;
-      }
-      return identity;
-    }
-    if (config.authMode === "jwt") {
-      if (!config.authJwtSecret) {
-        res.writeHead(500, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ error: "JWT secret not configured" }));
-        return null;
-      }
+      if (!matched) return reject(res, 401, "Invalid API key");
+      identity = { mode: "api-key", subject: apiKeySubject(token), scopes: ["*"] };
+    } else if (config.authMode === "jwt") {
       const claims = verifyJwt(token, config.authJwtSecret, config.authJwtIssuer);
-      if (!claims) {
-        res.writeHead(401, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ error: "Invalid or expired JWT" }));
-        return null;
-      }
-      const identity = {
+      if (!claims) return reject(res, 401, "Invalid or expired JWT");
+      identity = {
         mode: "jwt",
         subject: claims.sub,
-        scopes: claims.scope ? claims.scope.split(" ") : ["*"]
+        scopes: claims.scope ? claims.scope.split(" ").filter(Boolean) : []
       };
-      if (!checkRateLimit(identity.subject, config.rateLimitPerMinute)) {
-        res.writeHead(429, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ error: "Rate limit exceeded" }));
-        return null;
-      }
-      return identity;
+    } else {
+      return reject(res, 500, `Unknown auth mode: ${config.authMode}`);
     }
-    res.writeHead(500, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({ error: `Unknown auth mode: ${config.authMode}` }));
-    return null;
+    const decision = await rateLimiter(`auth:${identity.subject}`, config.rateLimitPerMinute);
+    if (!decision.ok) {
+      return reject(res, 429, "Rate limit exceeded", { "Retry-After": String(decision.retryAfterSec) });
+    }
+    return identity;
   };
 }
 export {

package/dist/middleware/rate-limit.js

@@ -0,0 +1,37 @@
+class SlidingWindow {
+  constructor(windowMs = 6e4, now = Date.now) {
+    this.windowMs = windowMs;
+    this.now = now;
+  }
+  hits = /* @__PURE__ */ new Map();
+  hit(key, limit) {
+    if (limit <= 0) return { ok: true, retryAfterSec: 0 };
+    const t = this.now();
+    const recent = (this.hits.get(key) ?? []).filter((at) => at > t - this.windowMs);
+    if (recent.length >= limit) {
+      this.hits.set(key, recent);
+      return { ok: false, retryAfterSec: Math.max(1, Math.ceil((recent[0] + this.windowMs - t) / 1e3)) };
+    }
+    recent.push(t);
+    this.hits.set(key, recent);
+    return { ok: true, retryAfterSec: 0 };
+  }
+  /** Forget keys with no hit inside the window. */
+  prune() {
+    const cutoff = this.now() - this.windowMs;
+    for (const [key, at] of this.hits) {
+      if (at[at.length - 1] <= cutoff) this.hits.delete(key);
+    }
+  }
+}
+const processWindow = new SlidingWindow();
+setInterval(() => processWindow.prune(), 3e5).unref();
+const localRateLimiter = async (key, limit) => processWindow.hit(key, limit);
+function localRateHit(key, limit) {
+  return processWindow.hit(key, limit);
+}
+export {
+  SlidingWindow,
+  localRateHit,
+  localRateLimiter
+};

package/dist/observability/logger.js

@@ -46,8 +46,7 @@ class Logger {
       const entry = { level, msg, ts: (/* @__PURE__ */ new Date()).toISOString(), ...fields };
       this.opts.write(JSON.stringify(entry));
     } else {
-      const comp = fields?.component ? `[${fields.component}]` : "";
-      this.opts.write(`${level.toUpperCase()} ${comp} ${msg}`);
+      this.opts.write(fields?.component ? `[${fields.component}] ${msg}` : msg);
     }
   }
 }
@@ -59,8 +58,17 @@ function getLogger() {
 function configureLogger(opts) {
   _default = new Logger(opts);
 }
+function getComponentLogger(component) {
+  return {
+    debug: (msg, fields) => getLogger().debug(msg, { component, ...fields }),
+    info: (msg, fields) => getLogger().info(msg, { component, ...fields }),
+    warn: (msg, fields) => getLogger().warn(msg, { component, ...fields }),
+    error: (msg, fields) => getLogger().error(msg, { component, ...fields })
+  };
+}
 export {
   Logger,
   configureLogger,
+  getComponentLogger,
   getLogger
 };

package/dist/observability/metrics.js

@@ -46,6 +46,10 @@ class Gauge {
   set(value, labels) {
     this.buckets.set(labelKey(labels), { labels, value });
   }
+  /** Drop every series (a collector that owns the gauge starts each scrape empty). */
+  clear() {
+    this.buckets.clear();
+  }
   render() {
     const lines = [];
     lines.push(`# HELP ${this.name} ${this.help}`);
@@ -122,14 +126,11 @@ const registry = new Registry();
 const metrics = {
   queriesTotal: registry.register(new Counter("code_search_queries_total", "Total search queries by mode + repo.")),
   queryDuration: registry.register(new Histogram("code_search_query_duration_seconds", "Query latency by mode.")),
-  indexChunks: registry.register(new Gauge("code_search_index_chunks_total", "Indexed chunks by repo.")),
-  indexAge: registry.register(new Gauge("code_search_index_age_seconds", "Seconds since last index by repo.")),
+  indexChunks: registry.register(new Gauge("code_search_index_chunks_total", "Indexed chunks by project + repo.")),
+  indexAge: registry.register(new Gauge("code_search_index_age_seconds", "Seconds since the last successful index, by project.")),
   vectorIndexUnindexedRows: registry.register(new Gauge("code_search_vector_index_unindexed_rows", "Rows not yet folded into the vector index (brute-force scanned) by project.")),
   vectorIndexGrowthRatio: registry.register(new Gauge("code_search_vector_index_growth_ratio", "Rows written since the vector index was last trained / rows it was trained on, by project (retrains at CODE_SEARCH_VECTOR_RETRAIN_RATIO).")),
-  embeddingCalls: registry.register(new Counter("code_search_embeddings_calls_total", "Embedding API calls by provider.")),
-  llmCalls: registry.register(new Counter("code_search_llm_calls_total", "LLM API calls by phase.")),
-  errors: registry.register(new Counter("code_search_errors_total", "Errors by kind.")),
-  rerankerCacheHits: registry.register(new Counter("code_search_reranker_cache_hits_total", "Rerank cache lookups by outcome."))
+  errors: registry.register(new Counter("code_search_errors_total", "Errors by kind."))
 };
 export {
   Counter,

package/dist/projects/registry.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import {
   resolveCodeSearchConfig
 } from "../core/config.js";
+import { localRateHit } from "../middleware/rate-limit.js";
 const DEFAULT_QUOTAS = {
   maxQueriesPerMinute: 100,
   maxEmbeddingCostUsd: 0,
@@ -123,24 +124,21 @@ function projectAccessAllowed(project, identityScopes) {
   }
   return false;
 }
-const projectRateBuckets = /* @__PURE__ */ new Map();
+function projectQuotaKey(project, identity) {
+  return `project:${project.name}|${identity}`;
+}
 function checkProjectQuota(project, identity) {
-  if (project.quotas.maxQueriesPerMinute <= 0) return { ok: true };
-  const key = `${identity}|${project.name}`;
-  const now = Date.now();
-  const bucket = projectRateBuckets.get(key);
-  if (!bucket || now > bucket.resetAt) {
-    projectRateBuckets.set(key, { count: 1, resetAt: now + 6e4 });
-    return { ok: true };
-  }
-  if (bucket.count >= project.quotas.maxQueriesPerMinute) {
-    return { ok: false, reason: `quota exceeded for project="${project.name}": ${project.quotas.maxQueriesPerMinute}/min` };
-  }
-  bucket.count++;
-  return { ok: true };
+  const d = localRateHit(projectQuotaKey(project, identity), project.quotas.maxQueriesPerMinute);
+  if (d.ok) return { ok: true };
+  return {
+    ok: false,
+    reason: `quota exceeded for project="${project.name}": ${project.quotas.maxQueriesPerMinute}/min`,
+    retryAfterSec: d.retryAfterSec
+  };
 }
 export {
   ProjectRegistry,
   checkProjectQuota,
-  projectAccessAllowed
+  projectAccessAllowed,
+  projectQuotaKey
 };

package/dist/resources/resources.js

@@ -18,6 +18,22 @@ function registerResources(ctx) {
     }
   ];
 }
+function registerResourceTemplates() {
+  return [
+    {
+      uriTemplate: "code-search://repo/{name}/profile",
+      name: "Repo Profile",
+      description: "Profile of one repo (see code-search://repos for names)",
+      mimeType: "application/json"
+    },
+    {
+      uriTemplate: "code-search://repo/{name}/graph",
+      name: "Repo Graph",
+      description: "Code graph (nodes + links) of one repo",
+      mimeType: "application/json"
+    }
+  ];
+}
 async function handleResource(uri, ctx) {
   try {
     if (uri === "code-search://repos") {
@@ -78,5 +94,6 @@ async function handleResource(uri, ctx) {
 }
 export {
   handleResource,
+  registerResourceTemplates,
   registerResources
 };