@esankhan3/code-search-mcp 1.0.6 → 1.1.1

package/dist/tools/index-tools.js

@@ -1,5 +1,6 @@
 import { resolvedKnowledgeConfig } from "../core/env-config.js";
 import { KnowledgeIndexer } from "@esankhan3/anvil-knowledge-core";
+import { toolError } from "./validate.js";
 const TOOL_NAMES = ["index_status"];
 function describeVectorIndex(v) {
   if (!v) return "none (flat scan \u2014 table below the index threshold or not yet indexed)";
@@ -8,6 +9,9 @@ function describeVectorIndex(v) {
     v.trainedRows ? `trained on ${v.trainedRows.toLocaleString()} rows at ${v.trainedAt}, +${v.rowsAddedSinceTrain.toLocaleString()} since (${Math.round(v.rowsAddedSinceTrain / v.trainedRows * 100)}%)` : "training untracked (retrains on the next writer run)"
   );
   parts.push(`${(v.numUnindexedRows ?? 0).toLocaleString()} unindexed rows`);
+  if (v.nprobes) {
+    parts.push(`${v.nprobes} probes per query (recall@10 ${v.calibratedRecall?.toFixed(3)} on ${v.calibrationQueries} query-like probes)`);
+  }
   if (v.retrainStartedAt) parts.push(`retrain started ${v.retrainStartedAt} has not completed`);
   if (v.lastError) parts.push(`last error: ${v.lastError}`);
   return parts.join("; ");
@@ -16,7 +20,7 @@ function registerIndexTools() {
   return [
     {
       name: "index_status",
-      description: "Get current index stats \u2014 chunk count, embedding provider, repos indexed, last indexed time.",
+      description: "Get current index stats \u2014 chunk count, embedding provider, last indexed time, vector-index health, and chunks per repo.",
       inputSchema: {
         type: "object",
         properties: {}
@@ -47,7 +51,7 @@ async function handleIndexTool(name, args, ctx) {
     return null;
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    return { content: [{ type: "text", text: `Index tool error: ${msg}` }] };
+    return toolError(`Index tool error: ${msg}`);
   }
 }
 export {

package/dist/tools/profile.js

@@ -1,6 +1,10 @@
-import { loadAllProfiles, loadProfile } from "@esankhan3/anvil-knowledge-core";
+import { loadAllProfiles, loadProfile, isLlmAvailable } from "@esankhan3/anvil-knowledge-core";
 import { resolvedKnowledgeConfig } from "../core/env-config.js";
 import { discoverRepos } from "@esankhan3/anvil-knowledge-core";
+import { toolError, toolText, validateArgs } from "./validate.js";
+function missingProfileText(repo) {
+  return isLlmAvailable() ? `No profile for "${repo}" yet. Profiles are generated during indexing, so it appears after the next index run (or check the name with list_repos).` : `No profile for "${repo}": repo profiles are generated during indexing only when an LLM is configured, and LLM mode is "none".`;
+}
 function registerProfileTools() {
   return [
     {
@@ -17,7 +21,7 @@ function registerProfileTools() {
       inputSchema: {
         type: "object",
         properties: {
-          repo: { type: "string", description: "Repository name" }
+          repo: { type: "string", minLength: 1, description: "Repository name" }
         },
         required: ["repo"]
       }
@@ -25,7 +29,10 @@ function registerProfileTools() {
   ];
 }
 async function handleProfileTool(name, args, ctx) {
-  if (!["list_repos", "get_repo_profile"].includes(name)) return null;
+  const schema = registerProfileTools().find((t) => t.name === name)?.inputSchema;
+  if (!schema) return null;
+  const invalid = validateArgs(schema, args);
+  if (invalid) return toolError(`${name}: ${invalid}`);
   try {
     if (name === "list_repos") {
       const profiles = await loadAllProfiles(ctx.projectName, resolvedKnowledgeConfig());
@@ -37,7 +44,7 @@ async function handleProfileTool(name, args, ctx) {
 
 ${text2}` }] };
         }
-        return { content: [{ type: "text", text: "No repos found. Run reindex first." }] };
+        return toolText("No repos indexed yet.");
       }
       const text = profiles.map(
         (p) => `- **${p.name}** \u2014 ${p.role} | ${p.domain} | ${p.description}`
@@ -49,9 +56,7 @@ ${text}` }] };
     if (name === "get_repo_profile") {
       const repo = args.repo;
       const profile = await loadProfile(ctx.projectName, repo, resolvedKnowledgeConfig());
-      if (!profile) {
-        return { content: [{ type: "text", text: `No profile found for "${repo}". Run reindex to generate profiles.` }] };
-      }
+      if (!profile) return toolText(missingProfileText(repo));
       const lines = [
         `# ${profile.name}`,
         "",
@@ -80,10 +85,11 @@ ${text}` }] };
     return null;
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    return { content: [{ type: "text", text: `Profile tool error: ${msg}` }] };
+    return toolError(`Profile tool error: ${msg}`);
   }
 }
 export {
   handleProfileTool,
+  missingProfileText,
   registerProfileTools
 };

package/dist/tools/search.js

@@ -1,43 +1,36 @@
 import { getRetriever, getBlobStore, findChunksInProject } from "@esankhan3/anvil-knowledge-core";
 import { resolvedKnowledgeConfig } from "../core/env-config.js";
+import { metrics } from "../observability/metrics.js";
+import { toolError, toolText, validateArgs } from "./validate.js";
+const queryProps = {
+  query: { type: "string", minLength: 1, description: "Search query (natural language or code identifier)" },
+  maxResults: { type: "integer", minimum: 1, description: "Max results to return (default: 10)" },
+  // Agents send repos as an array, one name, or a comma-joined string — all accepted.
+  repos: {
+    anyOf: [
+      { type: "array", items: { type: "string", minLength: 1 }, minItems: 1 },
+      { type: "string", minLength: 1 }
+    ],
+    description: "Only search these repos (optional): an array of names, one name, or a comma-separated list"
+  }
+};
+const repoList = (v) => (Array.isArray(v) ? v.map(String) : String(v).split(",")).map((s) => s.trim()).filter((s) => s.length > 0);
 function registerSearchTools() {
   return [
     {
       name: "search_code",
-      description: "Hybrid search across all repos using vector + BM25 + graph expansion + reranking. Best for general queries.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          query: { type: "string", description: "Search query (natural language or code identifier)" },
-          maxResults: { type: "number", description: "Max results to return (default: 10)" },
-          repos: { type: "array", items: { type: "string" }, description: "Filter to specific repos (optional)" }
-        },
-        required: ["query"]
-      }
+      description: "Hybrid search across all repos using vector + BM25 + graph expansion + reranking. Best for general queries. Needs the embedder.",
+      inputSchema: { type: "object", properties: queryProps, required: ["query"] }
     },
     {
       name: "search_semantic",
-      description: 'Vector-only semantic search. Best for conceptual questions like "how does X work?"',
-      inputSchema: {
-        type: "object",
-        properties: {
-          query: { type: "string", description: "Search query" },
-          maxResults: { type: "number", description: "Max results (default: 10)" }
-        },
-        required: ["query"]
-      }
+      description: 'Vector-only semantic search. Best for conceptual questions like "how does X work?". Needs the embedder.',
+      inputSchema: { type: "object", properties: queryProps, required: ["query"] }
     },
     {
       name: "search_exact",
-      description: "BM25 keyword search. Best for exact function names, error codes, file paths.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          query: { type: "string", description: "Exact search query" },
-          maxResults: { type: "number", description: "Max results (default: 10)" }
-        },
-        required: ["query"]
-      }
+      description: "BM25 keyword search, led by exact symbol-name and exact-phrase hits. Best for exact function names, error codes, file paths. Works without the embedder.",
+      inputSchema: { type: "object", properties: queryProps, required: ["query"] }
     },
     {
       name: "get_code_snippet",
@@ -45,31 +38,39 @@ function registerSearchTools() {
       inputSchema: {
         type: "object",
         properties: {
-          id: { type: "string", description: 'Qualified id "repo::filePath::entity" (or "repo::filePath" for a whole file)' },
-          repo: { type: "string", description: "Repository name (alternative to id)" },
-          file: { type: "string", description: "File path relative to repo root (alternative to id)" },
-          entity: { type: "string", description: "Entity name (optional; with repo/file)" }
+          id: { type: "string", minLength: 1, description: 'Qualified id "repo::filePath::entity" (or "repo::filePath" for a whole file)' },
+          repo: { type: "string", minLength: 1, description: "Repository name (alternative to id)" },
+          file: { type: "string", minLength: 1, description: "File path relative to repo root (alternative to id)" },
+          entity: { type: "string", minLength: 1, description: "Entity name (optional; with repo/file)" }
         }
       }
     }
   ];
 }
+const SCHEMAS = new Map(registerSearchTools().map((t) => [t.name, t.inputSchema]));
+const METRIC_MODE = { search_code: "hybrid", search_semantic: "vector", search_exact: "bm25" };
 async function handleSearchTool(name, args, ctx) {
+  const schema = SCHEMAS.get(name);
+  if (!schema) return null;
+  const invalid = validateArgs(schema, args);
+  if (invalid) return toolError(`${name}: ${invalid}`);
   if (name === "get_code_snippet") return await handleGetCodeSnippet(args, ctx);
-  if (!["search_code", "search_semantic", "search_exact"].includes(name)) return null;
-  if (!ctx.indexReady) {
-    return { content: [{ type: "text", text: "Index not ready. Run reindex tool or wait for auto-indexing to complete." }] };
+  if (!ctx.indexReady && name !== "search_exact") {
+    return toolText("Index not ready \u2014 indexing is still running or has not completed. Check index_status for progress.");
   }
+  const query = args.query;
+  const maxResults = args.maxResults ?? 10;
+  const repos = args.repos === void 0 || args.repos === null ? void 0 : repoList(args.repos);
+  if (repos?.length === 0) return toolError(`${name}: "repos" must name at least one repo.`);
+  const modeMap = {
+    search_code: "vector+bm25+graph",
+    search_semantic: "vector",
+    search_exact: "bm25"
+  };
+  const started = Date.now();
+  let outcome = "ok";
   try {
     const retriever = await getRetriever(ctx.projectName, resolvedKnowledgeConfig());
-    const query = args.query;
-    const maxResults = args.maxResults || 10;
-    const repos = args.repos;
-    const modeMap = {
-      search_code: "vector+bm25+graph",
-      search_semantic: "vector",
-      search_exact: "bm25"
-    };
     const result = await retriever.retrieve(query, {
       maxChunks: maxResults,
       // A search tool returns a fixed COUNT of results; the config token budget
@@ -81,7 +82,7 @@ async function handleSearchTool(name, args, ctx) {
       mode: modeMap[name]
     });
     if (result.chunks.length === 0) {
-      return { content: [{ type: "text", text: `No results found for "${query}"` }] };
+      return toolText(`No results found for "${query}"${ctx.indexReady ? "" : " (indexing has not completed \u2014 check index_status)"}`);
     }
     const text = result.chunks.map((sc, i) => {
       const c = sc.chunk;
@@ -90,14 +91,23 @@ async function handleSearchTool(name, args, ctx) {
 ${c.content}
 \`\`\``;
     }).join("\n\n");
-    return { content: [{ type: "text", text: `Found ${result.chunks.length} results for "${query}" (${result.totalTokens} tokens):
+    return toolText(`Found ${result.chunks.length} results for "${query}" (${result.totalTokens} tokens):
 
-${text}` }] };
+${text}`);
   } catch (err) {
+    outcome = "error";
+    metrics.errors.inc({ kind: "search" });
     const msg = err instanceof Error ? err.message : String(err);
-    return { content: [{ type: "text", text: `Search failed: ${msg}` }] };
+    return toolError(`Search failed: ${msg}`);
+  } finally {
+    const mode = METRIC_MODE[name];
+    metrics.queriesTotal.inc({ mode, outcome });
+    metrics.queryDuration.observe((Date.now() - started) / 1e3, { mode });
   }
 }
+function namesEntity(c, entity) {
+  return c.entityName === entity || !!c.parentEntity && `${c.parentEntity}.${c.entityName}` === entity;
+}
 async function handleGetCodeSnippet(args, ctx) {
   let repo = args.repo;
   let file = args.file;
@@ -113,7 +123,7 @@ async function handleGetCodeSnippet(args, ctx) {
     }
   }
   if (!repo || !file) {
-    return { content: [{ type: "text", text: 'Provide id="repo::file::entity" or repo + file (entity optional).' }] };
+    return toolError('get_code_snippet: provide id="repo::file::entity" or repo + file (entity optional).');
   }
   try {
     const esc = (v) => v.replace(/'/g, "''");
@@ -132,12 +142,12 @@ async function handleGetCodeSnippet(args, ctx) {
     if (matches.length === 0 && await getBlobStore(ctx.projectName, resolvedKnowledgeConfig()).exists("chunks.json")) {
       matches = await findChunksInProject(
         ctx.projectName,
-        (c) => c.repoName === repo && c.filePath === file && (!entity || c.entityName === entity),
+        (c) => c.repoName === repo && c.filePath === file && (!entity || namesEntity(c, entity)),
         5,
         resolvedKnowledgeConfig()
       );
       if (matches.length === 0 && entity) {
-        matches = await findChunksInProject(ctx.projectName, (c) => c.repoName === repo && c.entityName === entity, 5, resolvedKnowledgeConfig());
+        matches = await findChunksInProject(ctx.projectName, (c) => c.repoName === repo && namesEntity(c, entity), 5, resolvedKnowledgeConfig());
       }
     }
     if (matches.length === 0) {
@@ -153,7 +163,7 @@ ${c.content}
     return { content: [{ type: "text", text }] };
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    return { content: [{ type: "text", text: `Failed to read chunks: ${msg}` }] };
+    return toolError(`Failed to read chunks: ${msg}`);
   }
 }
 export {

package/dist/tools/validate.js

@@ -0,0 +1,48 @@
+const toolText = (text) => ({ content: [{ type: "text", text }] });
+const toolError = (text) => ({ content: [{ type: "text", text }], isError: true });
+const describe = (p) => p.type === "array" ? `${p.minItems ? "a non-empty " : "an "}array of ${p.items?.type ?? "value"}s` : `${p.minLength ? "a non-empty " : "a "}${p.type}`;
+function checkValue(name, v, p) {
+  if (p.anyOf) {
+    return p.anyOf.some((branch) => checkValue(name, v, branch) === null) ? null : `"${name}" must be ${p.anyOf.map(describe).join(" or ")}.`;
+  }
+  switch (p.type) {
+    case "string":
+      if (typeof v !== "string") return `"${name}" must be a string.`;
+      if (p.minLength !== void 0 && v.trim().length < p.minLength) return `"${name}" must not be empty.`;
+      break;
+    case "boolean":
+      if (typeof v !== "boolean") return `"${name}" must be a boolean.`;
+      break;
+    case "integer":
+      if (typeof v !== "number" || !Number.isInteger(v)) return `"${name}" must be an integer.`;
+      if (p.minimum !== void 0 && v < p.minimum) return `"${name}" must be at least ${p.minimum}.`;
+      if (p.maximum !== void 0 && v > p.maximum) return `"${name}" must be at most ${p.maximum}.`;
+      break;
+    case "array":
+      if (!Array.isArray(v)) return `"${name}" must be an array.`;
+      if (p.minItems !== void 0 && v.length < p.minItems) return `"${name}" must not be empty.`;
+      for (const item of v) {
+        const err = p.items ? checkValue(`${name}[]`, item, p.items) : null;
+        if (err) return err;
+      }
+      break;
+  }
+  if (p.enum && !p.enum.includes(v)) return `"${name}" must be one of: ${p.enum.join(", ")} (got ${JSON.stringify(v)}).`;
+  return null;
+}
+function validateArgs(schema, args) {
+  for (const k of schema.required ?? []) {
+    if (args[k] === void 0 || args[k] === null) return `Missing required argument "${k}".`;
+  }
+  for (const [k, p] of Object.entries(schema.properties)) {
+    if (args[k] === void 0 || args[k] === null) continue;
+    const err = checkValue(k, args[k], p);
+    if (err) return err;
+  }
+  return null;
+}
+export {
+  toolError,
+  toolText,
+  validateArgs
+};

package/dist/transports/http-transport.js

@@ -2,14 +2,56 @@ import { createServer } from "node:http";
 import { randomUUID } from "node:crypto";
 import { createMcpHandler } from "@modelcontextprotocol/server";
 import { toNodeHandler } from "@modelcontextprotocol/node";
+import { PACKAGE_VERSION } from "../core/version.js";
 import { createAuthMiddleware } from "../middleware/auth.js";
-import { registry, metrics } from "../observability/metrics.js";
+import { registry } from "../observability/metrics.js";
+import { getComponentLogger } from "../observability/logger.js";
+const log = getComponentLogger("code-search-mcp");
+class HttpError extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+  }
+}
+const MAX_INDEX_BODY_BYTES = 64 * 1024;
+function sendJson(res, status, body, headers = {}) {
+  res.writeHead(status, { "Content-Type": "application/json", ...headers });
+  res.end(JSON.stringify(body));
+}
+function readBody(req, res, limit) {
+  return new Promise((resolve, reject) => {
+    if (Number(req.headers["content-length"] ?? 0) > limit) {
+      sendJson(res, 413, { error: `Request body exceeds ${limit} bytes` }, { Connection: "close" });
+      req.resume();
+      resolve(null);
+      return;
+    }
+    const chunks = [];
+    let size = 0;
+    let tooLarge = false;
+    req.on("data", (chunk) => {
+      if (tooLarge) return;
+      size += chunk.length;
+      if (size > limit) {
+        tooLarge = true;
+        sendJson(res, 413, { error: `Request body exceeds ${limit} bytes` }, { Connection: "close" });
+        resolve(null);
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      if (!tooLarge) resolve(Buffer.concat(chunks).toString("utf-8"));
+    });
+    req.on("error", reject);
+  });
+}
 async function startHttpTransport(opts) {
   const { config, createMcpServer, onReady, getHealth } = opts;
-  const authenticate = createAuthMiddleware(config);
+  const authenticate = createAuthMiddleware(config, { rateLimiter: opts.rateLimiter });
   const startedAt = Date.now();
   const mcpHandler = createMcpHandler(async () => (await createMcpServer()).server, {
-    onerror: (err) => console.error(`[code-search-mcp] MCP handler error: ${err.message}`)
+    onerror: (err) => log.error(`MCP handler error: ${err.message}`)
   });
   const handleMcp = toNodeHandler(mcpHandler);
   const httpServer = createServer(async (req, res) => {
@@ -19,11 +61,7 @@ async function startHttpTransport(opts) {
     res.setHeader("X-Request-ID", requestId);
     if (path === "/health" && req.method === "GET") {
       const health = getHealth?.() ?? {};
-      res.writeHead(200, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({
-        status: "ok",
-        ...health
-      }));
+      sendJson(res, 200, { status: "ok", ...health });
       return;
     }
     if (path === "/status" && req.method === "GET") {
@@ -33,26 +71,21 @@ async function startHttpTransport(opts) {
       return;
     }
     if (path === "/version" && req.method === "GET") {
-      res.writeHead(200, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({
+      sendJson(res, 200, {
         name: "code-search-mcp",
-        version: "1.0.0",
+        version: PACKAGE_VERSION,
         node: process.version,
         platform: process.platform
-      }));
+      });
       return;
     }
     if (path === "/ready" && req.method === "GET") {
       const health = getHealth?.() ?? {};
       const ready = health.indexReady === true;
-      res.writeHead(ready ? 200 : 503, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ ready, ...health }));
+      sendJson(res, ready ? 200 : 503, { ready, ...health });
       return;
     }
     if (path === "/metrics" && req.method === "GET") {
-      const status = opts.getStatus?.() ?? {};
-      const indexing = status.indexing;
-      metrics.indexAge.set(0, { phase: indexing?.phase ?? "idle" });
       try {
         await opts.collectMetrics?.();
       } catch {
@@ -62,63 +95,68 @@ async function startHttpTransport(opts) {
       return;
     }
     if (path === "/admin/api/status" && req.method === "GET") {
+      if (config.authEnabled && !await authenticate(req, res)) return;
       const status = opts.getStatus?.() ?? {};
       res.writeHead(200, { "Content-Type": "application/json" });
       res.end(JSON.stringify({
-        version: "1.0.0",
+        version: PACKAGE_VERSION,
         uptime: Math.floor((Date.now() - startedAt) / 1e3),
         ...status
       }, null, 2));
       return;
     }
     if (path === "/index" && req.method === "POST") {
-      if (config.authEnabled) {
-        const identity = authenticate(req, res);
-        if (!identity) return;
+      if (config.authEnabled && !await authenticate(req, res)) return;
+      const raw = await readBody(req, res, MAX_INDEX_BODY_BYTES);
+      if (raw === null) return;
+      let body;
+      try {
+        body = JSON.parse(raw);
+      } catch {
+        sendJson(res, 400, { error: 'Body must be a JSON object: {"path": "...", "project"?: "...", "force"?: true}' });
+        return;
+      }
+      if (typeof body !== "object" || body === null || typeof body.path !== "string" || !body.path) {
+        sendJson(res, 400, { error: "`path` is required" });
+        return;
+      }
+      if (!opts.onIndex) {
+        sendJson(res, 501, { error: "Indexing handler not configured" });
+        return;
+      }
+      try {
+        sendJson(res, 200, await opts.onIndex(body));
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const status = err instanceof HttpError ? err.status : 500;
+        if (!res.headersSent) sendJson(res, status, { error: msg });
       }
-      let body = "";
-      req.on("data", (chunk) => {
-        body += chunk.toString();
-      });
-      req.on("end", async () => {
-        try {
-          const parsed = JSON.parse(body);
-          if (!parsed.path) {
-            res.writeHead(400, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({ error: "`path` is required" }));
-            return;
-          }
-          if (!opts.onIndex) {
-            res.writeHead(501, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({ error: "Indexing handler not configured" }));
-            return;
-          }
-          const result = await opts.onIndex(parsed);
-          res.writeHead(200, { "Content-Type": "application/json" });
-          res.end(JSON.stringify(result));
-        } catch (err) {
-          const msg = err instanceof Error ? err.message : String(err);
-          if (!res.headersSent) {
-            res.writeHead(500, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({ error: msg }));
-          }
-        }
-      });
       return;
     }
     if (path === "/mcp") {
-      if (config.authEnabled) {
-        const identity = authenticate(req, res);
-        if (!identity) return;
+      const identity = config.authEnabled ? await authenticate(req, res) : { mode: "anonymous", subject: "anonymous", scopes: ["*"] };
+      if (!identity) return;
+      if (opts.authorize) {
+        const decision = await opts.authorize(identity);
+        if (!decision.ok) {
+          sendJson(
+            res,
+            decision.status ?? 403,
+            { error: decision.error },
+            decision.retryAfterSec ? { "Retry-After": String(decision.retryAfterSec) } : {}
+          );
+          return;
+        }
       }
       await handleMcp(req, res);
       return;
     }
-    res.writeHead(404, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({ error: "Not found" }));
+    sendJson(res, 404, { error: "Not found" });
   });
-  return new Promise((resolve) => {
+  return new Promise((resolve, reject) => {
+    httpServer.once("error", reject);
     httpServer.listen(config.port, config.host, () => {
+      httpServer.off("error", reject);
       const url = `http://${config.host === "0.0.0.0" ? "localhost" : config.host}:${config.port}`;
       onReady?.(url);
       resolve(httpServer);
@@ -126,5 +164,6 @@ async function startHttpTransport(opts) {
   });
 }
 export {
+  HttpError,
   startHttpTransport
 };