@wrongstack/codebase-index-mcp 1.1.1 → 1.1.4

package/dist/adapter.d.ts

@@ -1,7 +1,7 @@
 import type { Context } from '@wrongstack/core/agent';
 import type { Tool } from '@wrongstack/core/types';
 import { MCPServer, type MCPServerToolHost } from '@wrongstack/mcp';
-import { type CodebaseIndexMcpPolicyOptions } from './policy.js';
+import { type CodebaseIndexMcpPolicyOptions, type CodebaseIndexMcpToolName } from './policy.js';
 interface GraphBaseArgs {
     projectRoot: string;
     indexDir?: string | undefined;
@@ -22,6 +22,15 @@ export interface CodebaseIndexMcpToolHostOptions extends CodebaseIndexMcpPolicyO
     indexDir?: string | undefined;
     dependencies?: CodebaseIndexMcpDependencies | undefined;
 }
+/**
+ * The navigation tools a coding agent reaches for most. Claude Code defers MCP
+ * tools behind a tool search, and an agent that must search before it can call
+ * the index falls back to its always-loaded grep; loading these three upfront
+ * costs little context and makes the index the shorter path.
+ */
+export declare const ALWAYS_LOADED_TOOLS: ReadonlySet<CodebaseIndexMcpToolName>;
+/** `InitializeResult.instructions`: shown to the client even while tools are deferred. */
+export declare const CODEBASE_INDEX_MCP_INSTRUCTIONS: string;
 export declare function createCodebaseIndexMcpToolHost(projectRoot: string, opts?: CodebaseIndexMcpToolHostOptions): MCPServerToolHost;
 export declare function createCodebaseIndexMcpServer(projectRoot: string, opts?: CodebaseIndexMcpToolHostOptions): MCPServer;
 export {};

package/dist/cli.d.ts

@@ -1,17 +1,3 @@
 #!/usr/bin/env node
-export interface ParsedArgs {
-    projectRoot: string;
-    indexDir?: string | undefined;
-    transport: 'stdio' | 'http';
-    httpPort: number;
-    httpHost: string;
-    httpToken?: string | undefined;
-    writable: boolean;
-    help: boolean;
-}
-export declare function printHelp(stdout: NodeJS.WriteStream): void;
-export declare function parseArgs(argv: readonly string[], env?: NodeJS.ProcessEnv): ParsedArgs;
-/** Resolve the checkout whose source files and local index are served. */
-export declare function resolveIndexProjectRoot(projectRoot: string): string;
-export declare function main(argv?: string[]): Promise<number>;
+export * from './main.js';
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -1,14 +1,19 @@
 #!/usr/bin/env node
 
 // src/cli.ts
+import { realpathSync as realpathSync2 } from "node:fs";
+import * as path2 from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+
+// src/main.ts
 import { realpathSync } from "node:fs";
 import * as path from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { serveHttp, serveStdio } from "@wrongstack/mcp";
 import {
   checkCodebaseIndexServerHealth,
   ensureCodebaseIndexServer,
   resolveProjectIndexDaemonAvailability,
+  runStartupIndex,
   shutdownCodebaseIndexHost
 } from "@wrongstack/tools/codebase-index";
 
@@ -18,8 +23,14 @@ import {
 } from "@wrongstack/mcp";
 import {
   codebaseContextTool,
+  codebaseImpactAnalysisTool,
+  codebaseIncomingCallsTool,
   codebaseIndexTool,
+  codebaseOutgoingCallsTool,
+  codebaseReadSymbolTool,
+  codebaseRepoMapTool,
   codebaseSearchTool,
+  codebaseSkeletonTool,
   codebaseStatsTool,
   fileGraphService,
   packageGraphService,
@@ -33,7 +44,13 @@ var CODEBASE_INDEX_READ_TOOLS = [
   "codebase_stats",
   "codebase_package_graph",
   "codebase_file_graph",
-  "codebase_symbol_graph"
+  "codebase_symbol_graph",
+  "codebase_incoming_calls",
+  "codebase_outgoing_calls",
+  "codebase_read_symbol",
+  "codebase_skeleton",
+  "codebase_impact_analysis",
+  "codebase_repo_map"
 ];
 var CODEBASE_INDEX_WRITE_TOOLS = ["codebase_index"];
 function selectCodebaseIndexMcpTools(opts = {}) {
@@ -99,12 +116,24 @@ var TOOL_DESCRIPTIONS = {
   codebase_package_graph: "Return the project package dependency graph from the authoritative Codebase Index service.",
   codebase_file_graph: "Return the file dependency graph for one package or package-path fragment.",
   codebase_symbol_graph: "Return the symbol dependency graph for one project-relative source file.",
+  codebase_incoming_calls: "List who calls or references a function, method or type: compact call sites with file and line. Use this, not codebase_symbol_graph, to find callers.",
+  codebase_outgoing_calls: "List what a function or method calls: compact call sites with file and line.",
+  codebase_read_symbol: "Return one symbol's source (function, class, method) by file and name, without reading the whole file.",
+  codebase_skeleton: "Outline a file or directory: exported signatures and declarations without bodies.",
+  codebase_impact_analysis: "Estimate what a change to a symbol affects: dependent symbols and files, optionally transitive.",
+  codebase_repo_map: "A ranked overview of the repository: the most central files and their key symbols.",
   codebase_index: "Build or incrementally refresh the project Codebase Index. Hidden unless the server starts with --writable."
 };
 var BUILTIN_TOOLS = {
   codebase_context: codebaseContextTool,
   codebase_search: codebaseSearchTool,
   codebase_stats: codebaseStatsTool,
+  codebase_incoming_calls: codebaseIncomingCallsTool,
+  codebase_outgoing_calls: codebaseOutgoingCallsTool,
+  codebase_read_symbol: codebaseReadSymbolTool,
+  codebase_skeleton: codebaseSkeletonTool,
+  codebase_impact_analysis: codebaseImpactAnalysisTool,
+  codebase_repo_map: codebaseRepoMapTool,
   codebase_index: codebaseIndexTool
 };
 function cloneToolSchema(name, tool) {
@@ -115,6 +144,12 @@ function cloneToolSchema(name, tool) {
   }
   return schema;
 }
+var ALWAYS_LOADED_TOOLS = /* @__PURE__ */ new Set([
+  "codebase_search",
+  "codebase_incoming_calls",
+  "codebase_read_symbol"
+]);
+var CODEBASE_INDEX_MCP_INSTRUCTIONS = "A prebuilt, ranked symbol index of this repository. Use it before grep/glob or whole-file reads to navigate code: codebase_search finds where a symbol is defined, codebase_incoming_calls / codebase_outgoing_calls list callers and callees, codebase_read_symbol returns one symbol's source, codebase_skeleton outlines a file or folder, codebase_impact_analysis estimates what a change affects, and codebase_context finds files relevant to a task. Grep stays the right tool for literal text such as strings, comments and config values.";
 function toolDescriptor(name) {
   const builtin = BUILTIN_TOOLS[name];
   const graphSchema = GRAPH_SCHEMAS[name];
@@ -122,7 +157,8 @@ function toolDescriptor(name) {
   return {
     name,
     description: TOOL_DESCRIPTIONS[name],
-    inputSchema: builtin ? cloneToolSchema(name, builtin) : graphSchema
+    inputSchema: builtin ? cloneToolSchema(name, builtin) : graphSchema,
+    ...ALWAYS_LOADED_TOOLS.has(name) ? { _meta: { "anthropic/alwaysLoad": true } } : {}
   };
 }
 function createContext(projectRoot, indexDir) {
@@ -152,6 +188,15 @@ function validateArgs(name, args) {
   if (name === "codebase_file_graph" && !nonEmptyString(args["package"])) {
     return 'codebase_file_graph requires a non-empty string "package"';
   }
+  const builtin = BUILTIN_TOOLS[name];
+  if (builtin && name !== "codebase_search") {
+    const schema = builtin.inputSchema;
+    for (const field of schema.required ?? []) {
+      if (schema.properties?.[field]?.type === "string" && !nonEmptyString(args[field])) {
+        return `${name} requires a non-empty string "${field}"`;
+      }
+    }
+  }
   if (name === "codebase_symbol_graph" && !nonEmptyString(args["file"])) {
     return 'codebase_symbol_graph requires a non-empty string "file"';
   }
@@ -201,7 +246,12 @@ function createCodebaseIndexMcpToolHost(projectRoot, opts = {}) {
           }
           const content2 = await executeTool(builtin, args, context, signal);
           signal.throwIfAborted();
-          return { content: content2, isError: isDegradedFailure(content2) };
+          if (isDegradedFailure(content2)) return { content: content2, isError: true };
+          const serialize = builtin.serialize;
+          return {
+            content: typeof serialize === "function" ? serialize(content2, args) : content2,
+            isError: false
+          };
         }
         const base = {
           projectRoot,
@@ -239,6 +289,7 @@ function createCodebaseIndexMcpServer(projectRoot, opts = {}) {
   return new MCPServer({
     host: createCodebaseIndexMcpToolHost(projectRoot, opts),
     serverInfo: { name: "wrongstack-codebase-index-mcp", version: SERVER_INFO.version },
+    instructions: CODEBASE_INDEX_MCP_INSTRUCTIONS,
     prompts: [
       {
         name: "explore-codebase",
@@ -251,7 +302,7 @@ function createCodebaseIndexMcpServer(projectRoot, opts = {}) {
   });
 }
 
-// src/cli.ts
+// src/main.ts
 function printHelp(stdout) {
   stdout.write(
     [
@@ -271,6 +322,8 @@ function printHelp(stdout) {
       "                          Prefer WRONGSTACK_MCP_TOKEN \u2014 a command line is readable",
       "                          by other local processes (WS-064).",
       "  --writable              Also expose codebase_index for incremental/full rebuilds.",
+      "  --watch                 Keep the index fresh while connected: catch up incrementally",
+      "                          at start, then reindex files changed on disk.",
       "  -h, --help              Show this message.",
       "",
       "The MCP process is an IPC client. The detached project daemon remains the only SQLite owner."
@@ -285,6 +338,7 @@ function parseArgs(argv, env = process.env) {
     httpPort: 0,
     httpHost: "127.0.0.1",
     writable: false,
+    watch: false,
     help: false
   };
   const warn = (event, message) => {
@@ -342,6 +396,9 @@ function parseArgs(argv, env = process.env) {
       case "--writable":
         parsed.writable = true;
         break;
+      case "--watch":
+        parsed.watch = true;
+        break;
       case "-h":
       case "--help":
         parsed.help = true;
@@ -405,7 +462,9 @@ async function main(argv = process.argv.slice(2)) {
     await ensureCodebaseIndexServer({
       projectRoot,
       ...args.indexDir ? { indexDir: args.indexDir } : {},
-      watchExternal: false
+      // A client that edits outside WrongStack (an external agent) makes the
+      // index stale unless the project server watches the disk for it.
+      watchExternal: args.watch
     });
     const health = await checkCodebaseIndexServerHealth(projectRoot, args.indexDir);
     if (health.status === "unresponsive") {
@@ -421,11 +480,24 @@ async function main(argv = process.argv.slice(2)) {
   } finally {
     clearInterval(startupLease);
   }
+  if (args.watch) {
+    void runStartupIndex({ projectRoot, ...args.indexDir ? { indexDir: args.indexDir } : {} }).then(
+      (result) => process.stderr.write(
+        `${SERVER_INFO.name}: index caught up (${JSON.stringify(result).slice(0, 160)})
+`
+      )
+    ).catch(
+      (error) => process.stderr.write(
+        `${SERVER_INFO.name}: index catch-up failed: ${error instanceof Error ? error.message : String(error)}
+`
+      )
+    );
+  }
   const server = createCodebaseIndexMcpServer(projectRoot, {
     writable: args.writable,
     ...args.indexDir ? { indexDir: args.indexDir } : {}
   });
-  const policyText = `writable=${String(args.writable)}`;
+  const policyText = `writable=${String(args.writable)} watch=${String(args.watch)}`;
   if (args.transport === "http") {
     try {
       const handle = await serveHttp(server, {
@@ -439,9 +511,9 @@ async function main(argv = process.argv.slice(2)) {
         `${SERVER_INFO.name}: ready at ${handle.url} \u2014 projectRoot=${projectRoot} transport=http ${policyText}${args.httpToken ? " [token auth]" : ""}
 `
       );
-      await new Promise((resolve3) => {
-        process.once("SIGINT", resolve3);
-        process.once("SIGTERM", resolve3);
+      await new Promise((resolve4) => {
+        process.once("SIGINT", resolve4);
+        process.once("SIGTERM", resolve4);
       });
       await handle.close();
       return 0;
@@ -461,17 +533,19 @@ async function main(argv = process.argv.slice(2)) {
     await shutdownCodebaseIndexHost();
   }
 }
+
+// src/cli.ts
 function isMainModule() {
   const entry = process.argv[1];
   if (!entry) return false;
   const self = fileURLToPath2(import.meta.url);
   const comparablePath = (value) => {
-    const normalized = path.resolve(value).replace(/^\\\\\?\\/, "");
+    const normalized = path2.resolve(value).replace(/^\\\\\?\\/, "");
     return process.platform === "win32" ? normalized.toLowerCase() : normalized;
   };
   if (comparablePath(entry) === comparablePath(self)) return true;
   try {
-    return comparablePath(realpathSync(entry)) === comparablePath(realpathSync(self));
+    return comparablePath(realpathSync2(entry)) === comparablePath(realpathSync2(self));
   } catch {
     return false;
   }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { type CodebaseIndexMcpDependencies, type CodebaseIndexMcpToolHostOptions, createCodebaseIndexMcpServer, createCodebaseIndexMcpToolHost, } from './adapter.js';
+export { main as runCodebaseIndexMcpServer } from './main.js';
 export { CODEBASE_INDEX_READ_TOOLS, CODEBASE_INDEX_WRITE_TOOLS, type CodebaseIndexMcpPolicyOptions, type CodebaseIndexMcpToolName, selectCodebaseIndexMcpTools, } from './policy.js';
 export { SERVER_INFO } from './version.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -4,8 +4,14 @@ import {
 } from "@wrongstack/mcp";
 import {
   codebaseContextTool,
+  codebaseImpactAnalysisTool,
+  codebaseIncomingCallsTool,
   codebaseIndexTool,
+  codebaseOutgoingCallsTool,
+  codebaseReadSymbolTool,
+  codebaseRepoMapTool,
   codebaseSearchTool,
+  codebaseSkeletonTool,
   codebaseStatsTool,
   fileGraphService,
   packageGraphService,
@@ -19,7 +25,13 @@ var CODEBASE_INDEX_READ_TOOLS = [
   "codebase_stats",
   "codebase_package_graph",
   "codebase_file_graph",
-  "codebase_symbol_graph"
+  "codebase_symbol_graph",
+  "codebase_incoming_calls",
+  "codebase_outgoing_calls",
+  "codebase_read_symbol",
+  "codebase_skeleton",
+  "codebase_impact_analysis",
+  "codebase_repo_map"
 ];
 var CODEBASE_INDEX_WRITE_TOOLS = ["codebase_index"];
 function selectCodebaseIndexMcpTools(opts = {}) {
@@ -85,12 +97,24 @@ var TOOL_DESCRIPTIONS = {
   codebase_package_graph: "Return the project package dependency graph from the authoritative Codebase Index service.",
   codebase_file_graph: "Return the file dependency graph for one package or package-path fragment.",
   codebase_symbol_graph: "Return the symbol dependency graph for one project-relative source file.",
+  codebase_incoming_calls: "List who calls or references a function, method or type: compact call sites with file and line. Use this, not codebase_symbol_graph, to find callers.",
+  codebase_outgoing_calls: "List what a function or method calls: compact call sites with file and line.",
+  codebase_read_symbol: "Return one symbol's source (function, class, method) by file and name, without reading the whole file.",
+  codebase_skeleton: "Outline a file or directory: exported signatures and declarations without bodies.",
+  codebase_impact_analysis: "Estimate what a change to a symbol affects: dependent symbols and files, optionally transitive.",
+  codebase_repo_map: "A ranked overview of the repository: the most central files and their key symbols.",
   codebase_index: "Build or incrementally refresh the project Codebase Index. Hidden unless the server starts with --writable."
 };
 var BUILTIN_TOOLS = {
   codebase_context: codebaseContextTool,
   codebase_search: codebaseSearchTool,
   codebase_stats: codebaseStatsTool,
+  codebase_incoming_calls: codebaseIncomingCallsTool,
+  codebase_outgoing_calls: codebaseOutgoingCallsTool,
+  codebase_read_symbol: codebaseReadSymbolTool,
+  codebase_skeleton: codebaseSkeletonTool,
+  codebase_impact_analysis: codebaseImpactAnalysisTool,
+  codebase_repo_map: codebaseRepoMapTool,
   codebase_index: codebaseIndexTool
 };
 function cloneToolSchema(name, tool) {
@@ -101,6 +125,12 @@ function cloneToolSchema(name, tool) {
   }
   return schema;
 }
+var ALWAYS_LOADED_TOOLS = /* @__PURE__ */ new Set([
+  "codebase_search",
+  "codebase_incoming_calls",
+  "codebase_read_symbol"
+]);
+var CODEBASE_INDEX_MCP_INSTRUCTIONS = "A prebuilt, ranked symbol index of this repository. Use it before grep/glob or whole-file reads to navigate code: codebase_search finds where a symbol is defined, codebase_incoming_calls / codebase_outgoing_calls list callers and callees, codebase_read_symbol returns one symbol's source, codebase_skeleton outlines a file or folder, codebase_impact_analysis estimates what a change affects, and codebase_context finds files relevant to a task. Grep stays the right tool for literal text such as strings, comments and config values.";
 function toolDescriptor(name) {
   const builtin = BUILTIN_TOOLS[name];
   const graphSchema = GRAPH_SCHEMAS[name];
@@ -108,7 +138,8 @@ function toolDescriptor(name) {
   return {
     name,
     description: TOOL_DESCRIPTIONS[name],
-    inputSchema: builtin ? cloneToolSchema(name, builtin) : graphSchema
+    inputSchema: builtin ? cloneToolSchema(name, builtin) : graphSchema,
+    ...ALWAYS_LOADED_TOOLS.has(name) ? { _meta: { "anthropic/alwaysLoad": true } } : {}
   };
 }
 function createContext(projectRoot, indexDir) {
@@ -138,6 +169,15 @@ function validateArgs(name, args) {
   if (name === "codebase_file_graph" && !nonEmptyString(args["package"])) {
     return 'codebase_file_graph requires a non-empty string "package"';
   }
+  const builtin = BUILTIN_TOOLS[name];
+  if (builtin && name !== "codebase_search") {
+    const schema = builtin.inputSchema;
+    for (const field of schema.required ?? []) {
+      if (schema.properties?.[field]?.type === "string" && !nonEmptyString(args[field])) {
+        return `${name} requires a non-empty string "${field}"`;
+      }
+    }
+  }
   if (name === "codebase_symbol_graph" && !nonEmptyString(args["file"])) {
     return 'codebase_symbol_graph requires a non-empty string "file"';
   }
@@ -187,7 +227,12 @@ function createCodebaseIndexMcpToolHost(projectRoot, opts = {}) {
           }
           const content2 = await executeTool(builtin, args, context, signal);
           signal.throwIfAborted();
-          return { content: content2, isError: isDegradedFailure(content2) };
+          if (isDegradedFailure(content2)) return { content: content2, isError: true };
+          const serialize = builtin.serialize;
+          return {
+            content: typeof serialize === "function" ? serialize(content2, args) : content2,
+            isError: false
+          };
         }
         const base = {
           projectRoot,
@@ -225,6 +270,7 @@ function createCodebaseIndexMcpServer(projectRoot, opts = {}) {
   return new MCPServer({
     host: createCodebaseIndexMcpToolHost(projectRoot, opts),
     serverInfo: { name: "wrongstack-codebase-index-mcp", version: SERVER_INFO.version },
+    instructions: CODEBASE_INDEX_MCP_INSTRUCTIONS,
     prompts: [
       {
         name: "explore-codebase",
@@ -236,12 +282,255 @@ function createCodebaseIndexMcpServer(projectRoot, opts = {}) {
     ]
   });
 }
+
+// src/main.ts
+import { realpathSync } from "node:fs";
+import * as path from "node:path";
+import { serveHttp, serveStdio } from "@wrongstack/mcp";
+import {
+  checkCodebaseIndexServerHealth,
+  ensureCodebaseIndexServer,
+  resolveProjectIndexDaemonAvailability,
+  runStartupIndex,
+  shutdownCodebaseIndexHost
+} from "@wrongstack/tools/codebase-index";
+function printHelp(stdout) {
+  stdout.write(
+    [
+      `${SERVER_INFO.name} v${SERVER_INFO.version} \u2014 WrongStack Codebase Index MCP server`,
+      "",
+      "Usage:",
+      `  ${SERVER_INFO.name} --project-root <path> [options]`,
+      "",
+      "Options:",
+      "  --project-root <path>   Project whose IPC-backed index should be served (required).",
+      "  --index-dir <path>      Override the project Codebase Index directory.",
+      "  --stdio                 Use stdio transport (default).",
+      "  --http                  Use HTTP transport.",
+      "  --port <n>              HTTP port (default 0 = ephemeral).",
+      "  --host <h>              HTTP bind host (default 127.0.0.1).",
+      "  --token <t>             Bearer token. Required for a non-loopback HTTP bind.",
+      "                          Prefer WRONGSTACK_MCP_TOKEN \u2014 a command line is readable",
+      "                          by other local processes (WS-064).",
+      "  --writable              Also expose codebase_index for incremental/full rebuilds.",
+      "  --watch                 Keep the index fresh while connected: catch up incrementally",
+      "                          at start, then reindex files changed on disk.",
+      "  -h, --help              Show this message.",
+      "",
+      "The MCP process is an IPC client. The detached project daemon remains the only SQLite owner."
+    ].join("\n") + "\n"
+  );
+}
+var HTTP_TOKEN_ENV = "WRONGSTACK_MCP_TOKEN";
+function parseArgs(argv, env = process.env) {
+  const parsed = {
+    projectRoot: "",
+    transport: "stdio",
+    httpPort: 0,
+    httpHost: "127.0.0.1",
+    writable: false,
+    watch: false,
+    help: false
+  };
+  const warn = (event, message) => {
+    console.warn(
+      JSON.stringify({ level: "warn", event, message, timestamp: (/* @__PURE__ */ new Date()).toISOString() })
+    );
+  };
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    const value = () => {
+      const next = argv[index + 1];
+      if (next === void 0 || next.startsWith("-")) {
+        warn("mcp_cli_flag_missing_value", `${arg} expects a value; ignoring it.`);
+        return void 0;
+      }
+      index++;
+      return next;
+    };
+    switch (arg) {
+      case "--project-root": {
+        const v = value();
+        if (v !== void 0) parsed.projectRoot = path.resolve(v);
+        break;
+      }
+      case "--index-dir": {
+        const v = value();
+        if (v !== void 0) parsed.indexDir = path.resolve(v);
+        break;
+      }
+      case "--stdio":
+        parsed.transport = "stdio";
+        break;
+      case "--http":
+        parsed.transport = "http";
+        break;
+      case "--port": {
+        const v = value();
+        if (v === void 0) break;
+        const port = Number(v);
+        if (Number.isInteger(port) && port >= 0 && port <= 65535) parsed.httpPort = port;
+        else
+          warn("mcp_cli_invalid_port", `--port ${v} is not a valid port; using an ephemeral port.`);
+        break;
+      }
+      case "--host": {
+        const v = value();
+        if (v !== void 0) parsed.httpHost = v;
+        break;
+      }
+      case "--token": {
+        const v = value();
+        if (v !== void 0) parsed.httpToken = v;
+        break;
+      }
+      case "--writable":
+        parsed.writable = true;
+        break;
+      case "--watch":
+        parsed.watch = true;
+        break;
+      case "-h":
+      case "--help":
+        parsed.help = true;
+        break;
+      default:
+        if (arg?.startsWith("-")) warn("mcp_cli_unknown_option", `unknown option ${arg} ignored.`);
+        break;
+    }
+  }
+  if (parsed.httpToken === void 0) {
+    const fromEnv = env[HTTP_TOKEN_ENV]?.trim();
+    if (fromEnv) parsed.httpToken = fromEnv;
+  } else if (parsed.httpToken.length > 0) {
+    console.warn(
+      `[mcp] --token puts the auth token in this process's command line, which other local processes can read. Prefer ${HTTP_TOKEN_ENV}.`
+    );
+  }
+  return parsed;
+}
+function resolveIndexProjectRoot(projectRoot) {
+  const resolved = path.resolve(projectRoot);
+  try {
+    return realpathSync(resolved);
+  } catch {
+    return resolved;
+  }
+}
+function availabilityError(availability) {
+  if (availability.kind === "available") return null;
+  if (availability.kind === "inline-requested") {
+    return "the Codebase Index daemon is disabled by WRONGSTACK_INDEX_INLINE or WRONGSTACK_INDEX_SERVER=0";
+  }
+  if (availability.kind === "missing-build") {
+    return "the @wrongstack/tools Codebase Index project-server build is missing";
+  }
+  return `the IPC endpoint is too long (${availability.byteLength}/${availability.maxBytes} bytes): ` + availability.endpoint;
+}
+async function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    printHelp(process.stdout);
+    return 0;
+  }
+  if (!args.projectRoot) {
+    process.stderr.write(`${SERVER_INFO.name}: --project-root is required
+`);
+    printHelp(process.stderr);
+    return 2;
+  }
+  const projectRoot = resolveIndexProjectRoot(args.projectRoot);
+  const availability = resolveProjectIndexDaemonAvailability(projectRoot, args.indexDir);
+  const unavailable = availabilityError(availability);
+  if (unavailable) {
+    process.stderr.write(`${SERVER_INFO.name}: cannot use project-scoped IPC: ${unavailable}
+`);
+    return 3;
+  }
+  const startupLease = setInterval(() => {
+  }, 1e3);
+  try {
+    await ensureCodebaseIndexServer({
+      projectRoot,
+      ...args.indexDir ? { indexDir: args.indexDir } : {},
+      // A client that edits outside WrongStack (an external agent) makes the
+      // index stale unless the project server watches the disk for it.
+      watchExternal: args.watch
+    });
+    const health = await checkCodebaseIndexServerHealth(projectRoot, args.indexDir);
+    if (health.status === "unresponsive") {
+      throw new Error("project server health check was unresponsive");
+    }
+  } catch (error) {
+    await shutdownCodebaseIndexHost();
+    process.stderr.write(
+      `${SERVER_INFO.name}: cannot attach to Codebase Index project server for ${projectRoot}: ${error instanceof Error ? error.message : String(error)}
+`
+    );
+    return 3;
+  } finally {
+    clearInterval(startupLease);
+  }
+  if (args.watch) {
+    void runStartupIndex({ projectRoot, ...args.indexDir ? { indexDir: args.indexDir } : {} }).then(
+      (result) => process.stderr.write(
+        `${SERVER_INFO.name}: index caught up (${JSON.stringify(result).slice(0, 160)})
+`
+      )
+    ).catch(
+      (error) => process.stderr.write(
+        `${SERVER_INFO.name}: index catch-up failed: ${error instanceof Error ? error.message : String(error)}
+`
+      )
+    );
+  }
+  const server = createCodebaseIndexMcpServer(projectRoot, {
+    writable: args.writable,
+    ...args.indexDir ? { indexDir: args.indexDir } : {}
+  });
+  const policyText = `writable=${String(args.writable)} watch=${String(args.watch)}`;
+  if (args.transport === "http") {
+    try {
+      const handle = await serveHttp(server, {
+        port: args.httpPort,
+        host: args.httpHost,
+        ...args.httpToken ? { token: args.httpToken } : {},
+        logger: { warn: (message) => process.stderr.write(`[codebase-index-mcp] ${message}
+`) }
+      });
+      process.stderr.write(
+        `${SERVER_INFO.name}: ready at ${handle.url} \u2014 projectRoot=${projectRoot} transport=http ${policyText}${args.httpToken ? " [token auth]" : ""}
+`
+      );
+      await new Promise((resolve3) => {
+        process.once("SIGINT", resolve3);
+        process.once("SIGTERM", resolve3);
+      });
+      await handle.close();
+      return 0;
+    } finally {
+      await shutdownCodebaseIndexHost();
+    }
+  }
+  try {
+    const handle = serveStdio(server);
+    process.stderr.write(
+      `${SERVER_INFO.name}: ready on stdio \u2014 projectRoot=${projectRoot} transport=stdio ${policyText}
+`
+    );
+    await handle.done;
+    return 0;
+  } finally {
+    await shutdownCodebaseIndexHost();
+  }
+}
 export {
   CODEBASE_INDEX_READ_TOOLS,
   CODEBASE_INDEX_WRITE_TOOLS,
   SERVER_INFO,
   createCodebaseIndexMcpServer,
   createCodebaseIndexMcpToolHost,
+  main as runCodebaseIndexMcpServer,
   selectCodebaseIndexMcpTools
 };
 //# sourceMappingURL=index.js.map

package/dist/main.d.ts

@@ -0,0 +1,17 @@
+export interface ParsedArgs {
+    projectRoot: string;
+    indexDir?: string | undefined;
+    transport: 'stdio' | 'http';
+    httpPort: number;
+    httpHost: string;
+    httpToken?: string | undefined;
+    writable: boolean;
+    watch: boolean;
+    help: boolean;
+}
+export declare function printHelp(stdout: NodeJS.WriteStream): void;
+export declare function parseArgs(argv: readonly string[], env?: NodeJS.ProcessEnv): ParsedArgs;
+/** Resolve the checkout whose source files and local index are served. */
+export declare function resolveIndexProjectRoot(projectRoot: string): string;
+export declare function main(argv?: string[]): Promise<number>;
+//# sourceMappingURL=main.d.ts.map

package/dist/policy.d.ts

@@ -1,4 +1,4 @@
-export declare const CODEBASE_INDEX_READ_TOOLS: readonly ['codebase_context', 'codebase_search', 'codebase_stats', 'codebase_package_graph', 'codebase_file_graph', 'codebase_symbol_graph'];
+export declare const CODEBASE_INDEX_READ_TOOLS: readonly ['codebase_context', 'codebase_search', 'codebase_stats', 'codebase_package_graph', 'codebase_file_graph', 'codebase_symbol_graph', 'codebase_incoming_calls', 'codebase_outgoing_calls', 'codebase_read_symbol', 'codebase_skeleton', 'codebase_impact_analysis', 'codebase_repo_map'];
 export declare const CODEBASE_INDEX_WRITE_TOOLS: readonly ['codebase_index'];
 export type CodebaseIndexMcpReadToolName = (typeof CODEBASE_INDEX_READ_TOOLS)[number];
 export type CodebaseIndexMcpWriteToolName = (typeof CODEBASE_INDEX_WRITE_TOOLS)[number];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrongstack/codebase-index-mcp",
-  "version": "1.1.1",
+  "version": "1.1.4",
   "license": "MIT",
   "description": "WrongStack Codebase Index as an MCP server, backed by the existing project-scoped IPC daemon.",
   "repository": {
@@ -37,9 +37,9 @@
     "clean": "bun -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""
   },
   "dependencies": {
-    "@wrongstack/core": "1.1.0",
-    "@wrongstack/mcp": "1.1.0",
-    "@wrongstack/tools": "1.1.0"
+    "@wrongstack/core": "1.1.2",
+    "@wrongstack/mcp": "1.1.2",
+    "@wrongstack/tools": "1.1.2"
   },
   "devDependencies": {
     "@types/node": "^26.5.1",