@mmerterden/multi-agent-toolkit-mcp 3.9.0 → 3.11.0

package/tools/code-intel/index.js

@@ -0,0 +1,665 @@
+/**
+ * code-intel  -  compiler-grade answers about Swift and Kotlin source.
+ *
+ * ONE FAMILY, NOT TWO. The capability set is genuinely symmetric - both sides
+ * are LSP servers answering the same handful of methods - so the language is
+ * inferred from the file extension rather than doubling the tool surface for no
+ * new capability. The asymmetry that does exist lives in the OUTPUT: every
+ * result carries `language`, `semantic` and, on the Kotlin side, `confidence`,
+ * so a caller can tell an index-backed Swift answer from an Alpha Kotlin one.
+ *
+ * NO SHELL, ANYWHERE. Every child here is `spawn(bin, argvArray)`. Nothing in
+ * this directory builds a command string, so none of the seven sanitizers
+ * applies and there is nothing for a quoting mistake to exploit. A gate asserts
+ * it rather than a comment claiming it.
+ *
+ * WHAT IS DELIBERATELY ABSENT. Nothing writes. `swift_replace_symbol_body` and
+ * its relatives were considered and dropped: an agent already has an editing
+ * tool, and giving a read-only family a write verb is how "read-only" stops
+ * meaning anything. `code_server_reset` is the one non-read-only entry and it
+ * discards a cache, not anyone's work.
+ *
+ * @module tools/code-intel
+ */
+
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { isAbsolute, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { withServer, resetServers, poolStats, shutdownAllLsp } from "./pool.js";
+import {
+  languageOf,
+  toLspPosition,
+  fromLspPosition,
+  findSymbol,
+  shapeLocations,
+  markdownFromHover,
+} from "./positions.js";
+import { resolveSwiftBin, resolveWorkspaceRoot, indexReport } from "./swift.js";
+import {
+  probeKotlin,
+  resolveKotlinRoot,
+  kotlinReport,
+  KOTLIN_ARGV,
+  KOTLIN_INIT_TIMEOUT_MS,
+  KOTLIN_INSTALL,
+} from "./kotlin.js";
+
+const ERROR_PREFIX = "ERROR: ";
+const DEFAULT_MAX_RESULTS = 200;
+/** How long a cross-file question may wait for the background index. */
+const DEFAULT_INDEX_WAIT_MS = 120000;
+
+const FILE_ARG = {
+  file: { type: "string", description: "Absolute path to a .swift, .kt or .kts file" },
+  workspace_root: {
+    type: "string",
+    description:
+      "Package or project root. Resolved from the file when omitted; the resolved root and how it was found come back in every result",
+  },
+};
+const POSITION_ARGS = {
+  line: { type: "number", description: "1-based line, as an editor shows it" },
+  column: { type: "number", description: "1-based column (default 1)" },
+  symbol: {
+    type: "string",
+    description:
+      'Name or dotted path ("Greeter.greet") instead of line/column. Resolved from the file\'s own symbol tree, which needs no build configuration',
+  },
+};
+
+export const CODE_TOOLS = [
+  {
+    name: "code_definition",
+    description:
+      "Where a symbol is declared. Give a 1-based line+column, or a symbol name and skip counting columns. Swift via sourcekit-lsp (bundled with Xcode), Kotlin via kotlin-lsp when installed. Every result says which build settings the answer came from, because a fallback root answers confidently and wrongly.",
+    inputSchema: { type: "object", properties: { ...FILE_ARG, ...POSITION_ARGS }, required: ["file"] },
+  },
+  {
+    name: "code_references",
+    description:
+      "Every reference to a symbol across the workspace. Needs a built index: this waits for the background index to settle and says so rather than returning an empty list, because '0 references' reads as 'unused' and that is the wrong thing to be wrong about. Measured: the same query answered 0 at 0.7s and 3 at 5.8s on a two-file package.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ...FILE_ARG,
+        ...POSITION_ARGS,
+        include_declaration: { type: "boolean", description: "Include the declaration (default true)" },
+        max_results: { type: "number", description: `Cap (default ${DEFAULT_MAX_RESULTS})` },
+        index_wait_sec: { type: "number", description: "How long to wait for the index (default 120)" },
+      },
+      required: ["file"],
+    },
+  },
+  {
+    name: "code_hover",
+    description:
+      "The type and documentation a compiler has for a symbol: signature, inferred type, doc comment. Works without an index for symbols in the file and the standard library.",
+    inputSchema: { type: "object", properties: { ...FILE_ARG, ...POSITION_ARGS }, required: ["file"] },
+  },
+  {
+    name: "code_document_symbols",
+    description:
+      "The symbol tree of one file - types, members, nesting, with 1-based lines. The one capability that needs no build configuration at all, so it is the honest fallback when an index is missing.",
+    inputSchema: {
+      type: "object",
+      properties: { ...FILE_ARG, max_depth: { type: "number", description: "Tree depth (default 3)" } },
+      required: ["file"],
+    },
+  },
+  {
+    name: "code_workspace_symbols",
+    description:
+      "Find a symbol by name across the whole workspace. Index-backed, so it reports an unbuilt index instead of an empty list.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Name or fragment to search for" },
+        workspace_root: { type: "string", description: "Package or project root" },
+        language: { type: "string", enum: ["swift", "kotlin"], description: "Which server to ask" },
+        max_results: { type: "number", description: `Cap (default ${DEFAULT_MAX_RESULTS})` },
+        index_wait_sec: { type: "number", description: "How long to wait for the index (default 120)" },
+      },
+      required: ["query", "workspace_root"],
+    },
+  },
+  {
+    name: "code_diagnostics",
+    description:
+      "Compiler diagnostics for one file without running a full build. Reports how long it waited when the server published nothing, rather than returning 0 and letting that read as clean. On a root with fallback build settings the result is marked non-semantic, because 'no such module' there is an artefact of the missing configuration, not a finding.",
+    inputSchema: {
+      type: "object",
+      properties: { ...FILE_ARG, wait_ms: { type: "number", description: "Budget (default 4000, max 15000)" } },
+      required: ["file"],
+    },
+  },
+  {
+    name: "code_index_status",
+    description:
+      "Whether this machine can answer code-intelligence questions at all, per language: is a server installed, which build system was found for the root, is an index on disk, and what to do about it if not. Always succeeds - it is the tool you run because something is missing.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspace_root: { type: "string", description: "Root to report on" },
+        file: { type: "string", description: "A file to resolve the root from instead" },
+      },
+    },
+  },
+  {
+    name: "code_server_reset",
+    description:
+      "Stop the pooled language servers so the next question starts a fresh one. For when a server has wedged on stale build settings after a Package.swift edit. Discards a cache, never source.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspace_root: { type: "string", description: "Only this root" },
+        language: { type: "string", enum: ["swift", "kotlin"], description: "Only this language" },
+      },
+    },
+  },
+];
+
+export const CODE_READ_ONLY = CODE_TOOLS.map((t) => t.name).filter((n) => n !== "code_server_reset");
+export const CODE_IDEMPOTENT = ["code_server_reset"];
+
+const LOCATION_LIST = {
+  type: "array",
+  items: {
+    type: "object",
+    properties: {
+      file: { type: "string" },
+      line: { type: "number" },
+      column: { type: "number" },
+      preview: { type: "string" },
+    },
+    required: ["file", "line", "column"],
+  },
+};
+
+export const CODE_OUTPUT_SCHEMAS = {
+  code_definition: {
+    type: "object",
+    properties: {
+      language: { type: "string" },
+      root: { type: "string" },
+      buildSettingsSource: { type: "string" },
+      semantic: { type: "boolean" },
+      count: { type: "number" },
+      truncated: { type: "boolean" },
+      results: LOCATION_LIST,
+      reason: { type: "string" },
+    },
+    required: ["language", "root", "semantic", "count", "results"],
+  },
+  code_references: {
+    type: "object",
+    properties: {
+      language: { type: "string" },
+      root: { type: "string" },
+      buildSettingsSource: { type: "string" },
+      semantic: { type: "boolean" },
+      indexReady: { type: "boolean" },
+      count: { type: "number" },
+      truncated: { type: "boolean" },
+      results: LOCATION_LIST,
+      reason: { type: "string" },
+    },
+    required: ["language", "root", "semantic", "indexReady", "count", "results"],
+  },
+  code_document_symbols: {
+    type: "object",
+    properties: {
+      language: { type: "string" },
+      file: { type: "string" },
+      count: { type: "number" },
+      symbols: { type: "array", items: { type: "object" } },
+    },
+    required: ["language", "file", "count", "symbols"],
+  },
+  code_index_status: {
+    type: "object",
+    properties: {
+      swift: { type: "object" },
+      kotlin: { type: "object" },
+      servers: { type: "array", items: { type: "object" } },
+    },
+    required: ["swift", "kotlin"],
+  },
+  code_server_reset: {
+    type: "object",
+    properties: {
+      stopped: { type: "array", items: { type: "string" } },
+      remaining: { type: "number" },
+    },
+    required: ["stopped", "remaining"],
+  },
+};
+
+/** A path is not a shell string here, but a root mismatch still answers wrongly. */
+function checkFile(file, root) {
+  if (!file || typeof file !== "string") return "file is required";
+  if (!isAbsolute(file)) return `file must be an absolute path, got "${file}"`;
+  if (!existsSync(file)) return `no such file: ${file}`;
+  try {
+    const real = realpathSync(file);
+    const realRoot = realpathSync(root);
+    if (real !== realRoot && !real.startsWith(realRoot + sep)) {
+      return `${file} is outside the workspace root ${root}; a mismatched root answers with an empty result rather than an error`;
+    }
+  } catch (e) {
+    return `cannot resolve ${file}: ${e.message}`;
+  }
+  return null;
+}
+
+function swiftSpec(root) {
+  const bin = resolveSwiftBin();
+  if (!bin) {
+    return {
+      error: `${ERROR_PREFIX}sourcekit-lsp not found. It ships with Xcode: install Xcode, or set SOURCEKIT_LSP_PATH.`,
+    };
+  }
+  const rootUri = pathToFileURL(root).href;
+  return {
+    language: "swift",
+    root,
+    bin,
+    argv: [],
+    initTimeoutMs: 120000,
+    initializeParams: {
+      processId: process.pid,
+      rootUri,
+      workspaceFolders: [{ uri: rootUri, name: root.split(sep).pop() }],
+      capabilities: {
+        window: { workDoneProgress: true },
+        workspace: { workspaceFolders: true, configuration: false },
+        textDocument: {
+          documentSymbol: { hierarchicalDocumentSymbolSupport: true },
+          publishDiagnostics: { relatedInformation: false },
+        },
+      },
+    },
+  };
+}
+
+function kotlinSpec(root) {
+  const probe = probeKotlin();
+  if (!probe.available) {
+    return {
+      error: `${ERROR_PREFIX}${probe.reason}. Install: ${KOTLIN_INSTALL.join(" ; ")}`,
+    };
+  }
+  const rootUri = pathToFileURL(root).href;
+  return {
+    language: "kotlin",
+    root,
+    bin: probe.bin,
+    argv: KOTLIN_ARGV,
+    initTimeoutMs: KOTLIN_INIT_TIMEOUT_MS,
+    initializeParams: {
+      processId: process.pid,
+      rootUri,
+      workspaceFolders: [{ uri: rootUri, name: root.split(sep).pop() }],
+      capabilities: {
+        window: { workDoneProgress: true },
+        workspace: { workspaceFolders: true },
+        textDocument: { documentSymbol: { hierarchicalDocumentSymbolSupport: true } },
+      },
+    },
+  };
+}
+
+/** Resolve language, root and server spec for a file-shaped request. */
+function contextFor(args) {
+  const file = args.file;
+  const language = args.language || languageOf(file);
+  if (!language) {
+    return { error: `${ERROR_PREFIX}${file}: not a Swift or Kotlin source file` };
+  }
+  const resolved =
+    language === "swift"
+      ? resolveWorkspaceRoot(file, args.workspace_root)
+      : resolveKotlinRoot(file, args.workspace_root);
+  const bad = checkFile(file, resolved.root);
+  if (bad) return { error: `${ERROR_PREFIX}${bad}` };
+  const spec = language === "swift" ? swiftSpec(resolved.root) : kotlinSpec(resolved.root);
+  if (spec.error) return spec;
+  return { language, root: resolved.root, source: resolved.source, spec };
+}
+
+/** line/column or symbol, to an LSP position. */
+async function positionFor(args, client, uri, text) {
+  if (args.symbol) {
+    const res = await client.request("textDocument/documentSymbol", {
+      textDocument: { uri },
+    });
+    if (res.error) return { error: `${ERROR_PREFIX}${res.error.message}` };
+    const found = findSymbol(res.result, args.symbol);
+    if (found.error) return { error: `${ERROR_PREFIX}${found.error}` };
+    if (found.candidates) {
+      const list = found.candidates
+        .map((c) => `${c.path} (line ${(c.range?.start?.line ?? 0) + 1})`)
+        .join(", ");
+      return {
+        error: `${ERROR_PREFIX}"${args.symbol}" is ambiguous in this file: ${list}. Pass line and column, or a dotted path.`,
+      };
+    }
+    return { position: found.match.range.start };
+  }
+  const pos = toLspPosition(text, args.line, args.column);
+  if (pos.error) return { error: `${ERROR_PREFIX}${pos.error}` };
+  return { position: pos };
+}
+
+const readText = (p) => {
+  try {
+    return readFileSync(p, "utf8");
+  } catch {
+    return null;
+  }
+};
+
+async function locationTool(name, args, ctx) {
+  const c = contextFor(args);
+  if (c.error) return c.error;
+  const wantsIndex = name === "code_references";
+  const report = c.language === "swift" ? indexReport(c.root, c.source) : null;
+
+  return withServer(c.spec, async ({ client, openDoc, root }) => {
+    const doc = openDoc(args.file);
+    if (doc.error) return doc.error;
+    const p = await positionFor(args, client, doc.uri, doc.text);
+    if (p.error) return p.error;
+
+    let indexReady = true;
+    if (wantsIndex) {
+      const budget = Math.max(0, Number(args.index_wait_sec ?? DEFAULT_INDEX_WAIT_MS / 1000) * 1000);
+      indexReady = await client.waitForIndex(budget);
+    }
+
+    const method = wantsIndex ? "textDocument/references" : "textDocument/definition";
+    const params = {
+      textDocument: { uri: doc.uri },
+      position: p.position,
+      ...(wantsIndex
+        ? { context: { includeDeclaration: args.include_declaration !== false } }
+        : {}),
+    };
+    const res = await client.request(method, params, { signal: ctx?.signal });
+    if (res.error) return `${ERROR_PREFIX}${res.error.message}`;
+
+    const shaped = shapeLocations(res.result, {
+      root,
+      maxResults: Number(args.max_results) || DEFAULT_MAX_RESULTS,
+      readFile: readText,
+    });
+    const out = {
+      language: c.language,
+      root,
+      buildSettingsSource: c.source,
+      semantic: report ? report.semantic : true,
+      ...(wantsIndex ? { indexReady } : {}),
+      ...shaped,
+    };
+    if (c.language === "kotlin") out.confidence = "alpha";
+    if (wantsIndex && !indexReady) {
+      const idx = client.indexing();
+      out.reason = `The background index had not finished when this answered${idx?.message ? ` (${idx.message})` : ""}, so an empty or short list here means "not indexed yet", not "no references". Raise index_wait_sec or run code_index_status.`;
+    } else if (wantsIndex && shaped.count === 0 && report && !report.semantic) {
+      out.reason = `This root resolved to "${c.source}" build settings, which cannot produce cross-file references. ${report.remedy[0] || ""}`.trim();
+    }
+    return out;
+  });
+}
+
+async function hoverTool(args, ctx) {
+  const c = contextFor(args);
+  if (c.error) return c.error;
+  return withServer(c.spec, async ({ client, openDoc, root }) => {
+    const doc = openDoc(args.file);
+    if (doc.error) return doc.error;
+    const p = await positionFor(args, client, doc.uri, doc.text);
+    if (p.error) return p.error;
+    const res = await client.request(
+      "textDocument/hover",
+      { textDocument: { uri: doc.uri }, position: p.position },
+      { signal: ctx?.signal },
+    );
+    if (res.error) return `${ERROR_PREFIX}${res.error.message}`;
+    const text = markdownFromHover(res.result?.contents);
+    const range = res.result?.range;
+    const out = {
+      language: c.language,
+      root,
+      buildSettingsSource: c.source,
+      semantic: c.language === "swift" ? indexReport(c.root, c.source).semantic : true,
+      documentation: text,
+      ...(range ? { range: fromLspPosition(doc.text, range.start) } : {}),
+    };
+    if (!text) out.reason = "the server returned no hover information at this position";
+    if (c.language === "kotlin") out.confidence = "alpha";
+    return out;
+  });
+}
+
+async function documentSymbolsTool(args, ctx) {
+  const c = contextFor(args);
+  if (c.error) return c.error;
+  const maxDepth = Number(args.max_depth) || 3;
+  return withServer(c.spec, async ({ client, openDoc }) => {
+    const doc = openDoc(args.file);
+    if (doc.error) return doc.error;
+    const res = await client.request(
+      "textDocument/documentSymbol",
+      { textDocument: { uri: doc.uri } },
+      { signal: ctx?.signal },
+    );
+    if (res.error) return `${ERROR_PREFIX}${res.error.message}`;
+    let count = 0;
+    const shape = (nodes, depth) =>
+      (nodes || []).map((s) => {
+        count += 1;
+        const r = s.selectionRange || s.range || s.location?.range || {};
+        const node = {
+          name: s.name,
+          kind: s.kind,
+          line: (r.start?.line ?? 0) + 1,
+          endLine: ((s.range || r).end?.line ?? 0) + 1,
+        };
+        if (depth < maxDepth && Array.isArray(s.children) && s.children.length) {
+          node.children = shape(s.children, depth + 1);
+        }
+        return node;
+      });
+    const symbols = shape(res.result, 1);
+    return { language: c.language, file: args.file, count, symbols };
+  });
+}
+
+async function workspaceSymbolsTool(args, ctx) {
+  const root = args.workspace_root;
+  if (!root || !isAbsolute(root)) return `${ERROR_PREFIX}workspace_root must be an absolute path`;
+  const language = args.language || "swift";
+  const spec = language === "swift" ? swiftSpec(root) : kotlinSpec(root);
+  if (spec.error) return spec.error;
+  const report = language === "swift" ? indexReport(root, classifyRoot(root)) : null;
+
+  return withServer(spec, async ({ client }) => {
+    const budget = Math.max(0, Number(args.index_wait_sec ?? DEFAULT_INDEX_WAIT_MS / 1000) * 1000);
+    const indexReady = await client.waitForIndex(budget);
+    const res = await client.request(
+      "workspace/symbol",
+      { query: String(args.query || "") },
+      { signal: ctx?.signal },
+    );
+    if (res.error) return `${ERROR_PREFIX}${res.error.message}`;
+    const shaped = shapeLocations(
+      (res.result || []).map((s) => ({ uri: s.location?.uri, range: s.location?.range, name: s.name })),
+      { root, maxResults: Number(args.max_results) || DEFAULT_MAX_RESULTS, readFile: readText },
+    );
+    shaped.results = shaped.results.map((r, i) => ({ ...r, name: res.result[i]?.name }));
+    const out = {
+      language,
+      root,
+      query: args.query,
+      semantic: report ? report.semantic : true,
+      indexReady,
+      ...shaped,
+    };
+    if (!indexReady) {
+      out.reason =
+        "The background index had not finished, so this list is incomplete rather than exhaustive.";
+    } else if (shaped.count === 0 && report && !report.semantic) {
+      out.reason = `This root resolved to "${report.buildSettingsSource}" build settings and cannot answer workspace-wide questions. ${report.remedy[0] || ""}`.trim();
+    }
+    return out;
+  });
+}
+
+function classifyRoot(root) {
+  return resolveWorkspaceRoot(root, undefined).source;
+}
+
+async function diagnosticsTool(args, ctx) {
+  const c = contextFor(args);
+  if (c.error) return c.error;
+  const waitMs = Math.min(15000, Math.max(250, Number(args.wait_ms) || 4000));
+  const report = c.language === "swift" ? indexReport(c.root, c.source) : null;
+
+  return withServer(c.spec, async ({ client, openDoc }) => {
+    // Subscribe BEFORE opening the document: sourcekit-lsp publishes
+    // diagnostics unsolicited after didOpen, so a listener attached afterwards
+    // races the very message it is waiting for.
+    let resolveFirst;
+    const got = new Promise((r) => (resolveFirst = r));
+    const collected = [];
+    let uri = null;
+    const unsubscribe = client.subscribe((msg) => {
+      if (msg.method !== "textDocument/publishDiagnostics") return;
+      if (!uri || msg.params?.uri !== uri) return;
+      collected.length = 0;
+      collected.push(...(msg.params.diagnostics || []));
+      resolveFirst(true);
+    });
+    const timer = setTimeout(() => resolveFirst(false), waitMs);
+    if (ctx?.signal) ctx.signal.addEventListener("abort", () => resolveFirst(false), { once: true });
+
+    const doc = openDoc(args.file);
+    if (doc.error) {
+      clearTimeout(timer);
+      unsubscribe();
+      return doc.error;
+    }
+    uri = doc.uri;
+    const arrived = await got;
+    clearTimeout(timer);
+    unsubscribe();
+
+    const semantic = report ? report.semantic : true;
+    const diagnostics = collected.map((d) => ({
+      severity: ["", "error", "warning", "information", "hint"][d.severity] || "unknown",
+      line: (d.range?.start?.line ?? 0) + 1,
+      column: (d.range?.start?.character ?? 0) + 1,
+      message: d.message,
+      source: d.source,
+      code: typeof d.code === "object" ? d.code?.value : d.code,
+    }));
+    const out = {
+      language: c.language,
+      file: args.file,
+      root: c.root,
+      buildSettingsSource: c.source,
+      semantic,
+      count: diagnostics.length,
+      diagnostics,
+    };
+    if (!arrived) {
+      out.reason = `the server published no diagnostics within ${waitMs}ms - this is "did not look", not "clean"`;
+    }
+    if (!semantic) {
+      out.reason =
+        `This root resolved to "${c.source}" build settings, so the compiler is invoked without the project's module graph. Errors like "no such module" here are artefacts of that, not findings. ` +
+        (out.reason || "");
+    }
+    return out;
+  });
+}
+
+function indexStatusTool(args) {
+  const file = args.file;
+  // "Always succeeds" is a promise about a MISSING TOOLCHAIN, not about bad
+  // input, and implementing it as "never validates" made the two answers
+  // identical. A path that is relative, absent, or literally the string
+  // "undefined" resolved to source "fallback" and semantic:false - the same
+  // answer an unconfigured repo gets - and then printed a remedy telling the
+  // caller to point --workspace_root at a project root, sending them after a
+  // build-system problem that does not exist. Every other tool in this family
+  // refuses such a path by name; this one now does too.
+  for (const [value, label] of [
+    [file, "file"],
+    [args.workspace_root, "workspace_root"],
+  ]) {
+    if (value === undefined || value === null) continue;
+    if (typeof value !== "string" || !value.trim()) {
+      return `${ERROR_PREFIX}${label} must be a non-empty path`;
+    }
+    if (!isAbsolute(value)) {
+      return `${ERROR_PREFIX}${label} must be an absolute path, got "${value}"`;
+    }
+    if (!existsSync(value)) return `${ERROR_PREFIX}no such ${label}: ${value}`;
+  }
+  let swiftRoot = args.workspace_root;
+  let swiftSource = swiftRoot ? classifyRoot(swiftRoot) : null;
+  if (!swiftRoot && file) {
+    const r = resolveWorkspaceRoot(file, undefined);
+    swiftRoot = r.root;
+    swiftSource = r.source;
+  }
+  const bin = resolveSwiftBin();
+  const swift = bin
+    ? swiftRoot
+      ? { available: true, bin, ...indexReport(swiftRoot, swiftSource) }
+      : { available: true, bin, reason: "give a workspace_root or a file to report on a root" }
+    : {
+        available: false,
+        reason: "sourcekit-lsp not found",
+        install: ["install Xcode", "or set SOURCEKIT_LSP_PATH"],
+      };
+
+  const kotlinRoot = args.workspace_root || (file ? resolveKotlinRoot(file, undefined).root : null);
+  return { swift, kotlin: kotlinReport(kotlinRoot), servers: poolStats() };
+}
+
+/**
+ * @param {string} name
+ * @param {object} args
+ * @param {object} ctx  the per-request context, merged with the family's own
+ */
+export async function handleCode(name, args = {}, ctx = {}) {
+  try {
+    switch (name) {
+      case "code_definition":
+      case "code_references":
+        return await locationTool(name, args, ctx);
+      case "code_hover":
+        return await hoverTool(args, ctx);
+      case "code_document_symbols":
+        return await documentSymbolsTool(args, ctx);
+      case "code_workspace_symbols":
+        return await workspaceSymbolsTool(args, ctx);
+      case "code_diagnostics":
+        return await diagnosticsTool(args, ctx);
+      case "code_index_status":
+        return indexStatusTool(args);
+      case "code_server_reset":
+        return resetServers({ root: args.workspace_root, language: args.language });
+      default:
+        return null;
+    }
+  } catch (e) {
+    // A handler must not throw: an exception here is an MCP-level error with no
+    // useful text, and one bad path would take the whole call down.
+    return `${ERROR_PREFIX}${name}: ${e?.message || String(e)}`;
+  }
+}
+
+export { shutdownAllLsp };