@takara-ai/miru-code 0.4.12 → 0.6.0

package/src/installer/prompt.ts

@@ -15,11 +15,63 @@ const ESC = "\x1b";
 const HIDE_CURSOR = `${ESC}[?25l`;
 const SHOW_CURSOR = `${ESC}[?25h`;
 const CLEAR_LINE = `${ESC}[2K`;
+const CURSOR_START = `${ESC}[G`;
 
 function writeRaw(text: string): void {
   output.write(text);
 }
 
+function moveCursorUp(lines: number): void {
+  if (lines > 0) {
+    writeRaw(`${ESC}[${lines}A`);
+  }
+}
+
+function moveCursorDown(lines: number): void {
+  if (lines > 0) {
+    writeRaw(`${ESC}[${lines}B`);
+  }
+}
+
+function rewriteLineAtOffsetFromBottom(offsetFromBottom: number, content: string): void {
+  moveCursorUp(offsetFromBottom);
+  writeRaw(`${CURSOR_START}${CLEAR_LINE}${content}`);
+  moveCursorDown(offsetFromBottom);
+}
+
+const MULTI_SELECT_HEADER_LINES = 3;
+const MULTI_SELECT_TRAILER_LINES = 2;
+
+function multiSelectTotalLines(itemCount: number): number {
+  return MULTI_SELECT_HEADER_LINES + itemCount + MULTI_SELECT_TRAILER_LINES;
+}
+
+function multiSelectItemOffsetFromBottom(itemIndex: number, itemCount: number): number {
+  return multiSelectTotalLines(itemCount) - (MULTI_SELECT_HEADER_LINES + itemIndex);
+}
+
+function formatMultiSelectItemLine(
+  item: { label: string; checked: boolean },
+  selected: boolean,
+): string {
+  const pointer = selected ? cyan("›") : " ";
+  const mark = item.checked ? cyan("[x]") : dim("[ ]");
+  const label = selected ? bold(item.label) : item.label;
+  return `  ${pointer} ${mark} ${label}`;
+}
+
+function updateMultiSelectItemRow(
+  item: { label: string; checked: boolean },
+  itemIndex: number,
+  itemCount: number,
+  selected: boolean,
+): void {
+  rewriteLineAtOffsetFromBottom(
+    multiSelectItemOffsetFromBottom(itemIndex, itemCount),
+    formatMultiSelectItemLine(item, selected),
+  );
+}
+
 function readKey(): Promise<Buffer> {
   return new Promise((resolve, reject) => {
     const onData = (chunk: Buffer) => {
@@ -90,12 +142,12 @@ async function withRawMode<T>(fn: () => Promise<T>): Promise<T> {
   }
 }
 
-function renderMultiSelect<T>(
+function buildMultiSelectLines<T>(
   title: string,
   items: Array<{ label: string; value: T; checked: boolean }>,
   cursor: number,
   footer: string,
-): void {
+): string[] {
   const lines: string[] = [];
   lines.push("");
   lines.push(bold(title));
@@ -105,15 +157,11 @@ function renderMultiSelect<T>(
     if (!item) {
       continue;
     }
-    const selected = i === cursor;
-    const pointer = selected ? cyan("›") : " ";
-    const mark = item.checked ? cyan("[x]") : dim("[ ]");
-    const label = selected ? bold(item.label) : item.label;
-    lines.push(`  ${pointer} ${mark} ${label}`);
+    lines.push(formatMultiSelectItemLine(item, i === cursor));
   }
   lines.push("");
   lines.push(dim(footer));
-  writeRaw(`${CLEAR_LINE}${lines.join(`\n${CLEAR_LINE}`)}\n`);
+  return lines;
 }
 
 export async function promptMultiSelect<T>(
@@ -130,10 +178,12 @@ export async function promptMultiSelect<T>(
 
   const footer = "↑↓ move  space toggle  a all  enter confirm  ctrl-c cancel";
   let cursor = 0;
+  const itemCount = items.length;
 
   return withRawMode(async () => {
+    writeRaw(`${buildMultiSelectLines(title, items, cursor, footer).join("\n")}\n`);
+
     while (true) {
-      renderMultiSelect(title, items, cursor, footer);
       const key = parseKey(await readKey());
 
       if (key === "ctrl-c") {
@@ -145,29 +195,72 @@ export async function promptMultiSelect<T>(
         return items.filter((item) => item.checked).map((item) => item.value);
       }
       if (key === "up") {
-        cursor = Math.max(0, cursor - 1);
+        if (cursor > 0) {
+          const previous = cursor;
+          cursor--;
+          const previousItem = items[previous];
+          const currentItem = items[cursor];
+          if (previousItem) {
+            updateMultiSelectItemRow(previousItem, previous, itemCount, false);
+          }
+          if (currentItem) {
+            updateMultiSelectItemRow(currentItem, cursor, itemCount, true);
+          }
+        }
       } else if (key === "down") {
-        cursor = Math.min(items.length - 1, cursor + 1);
+        if (cursor < items.length - 1) {
+          const previous = cursor;
+          cursor++;
+          const previousItem = items[previous];
+          const currentItem = items[cursor];
+          if (previousItem) {
+            updateMultiSelectItemRow(previousItem, previous, itemCount, false);
+          }
+          if (currentItem) {
+            updateMultiSelectItemRow(currentItem, cursor, itemCount, true);
+          }
+        }
       } else if (key === "space") {
         const item = items[cursor];
         if (item) {
           item.checked = !item.checked;
+          updateMultiSelectItemRow(item, cursor, itemCount, true);
         }
       } else if (key === "all") {
         const allChecked = items.every((item) => item.checked);
-        for (const item of items) {
+        for (let i = 0; i < items.length; i++) {
+          const item = items[i];
+          if (!item) {
+            continue;
+          }
           item.checked = !allChecked;
+          updateMultiSelectItemRow(item, i, itemCount, i === cursor);
         }
       }
     }
   });
 }
 
-function renderConfirm(question: string, yesSelected: boolean): void {
+function buildConfirmPromptLine(question: string, yesSelected: boolean): string {
   const yes = yesSelected ? green(bold(" Yes ")) : dim(" Yes ");
   const no = yesSelected ? dim(" No ") : green(bold(" No "));
-  writeRaw(`${CLEAR_LINE}${question}  ${yes} / ${no}\n`);
-  writeRaw(`${CLEAR_LINE}${dim("←→ or y/n to choose  enter to confirm  ctrl-c to cancel")}\n`);
+  return `${question}  ${yes} / ${no}`;
+}
+
+function buildConfirmLines(question: string, yesSelected: boolean): string[] {
+  return [
+    buildConfirmPromptLine(question, yesSelected),
+    dim("←→ or y/n to choose  enter to confirm  ctrl-c to cancel"),
+  ];
+}
+
+const CONFIRM_PROMPT_LINES = 2;
+
+function updateConfirmPromptLine(question: string, yesSelected: boolean): void {
+  rewriteLineAtOffsetFromBottom(
+    CONFIRM_PROMPT_LINES,
+    buildConfirmPromptLine(question, yesSelected),
+  );
 }
 
 export async function promptConfirm(question: string, defaultYes = true): Promise<boolean> {
@@ -188,8 +281,9 @@ export async function promptConfirm(question: string, defaultYes = true): Promis
   let yesSelected = defaultYes;
 
   return withRawMode(async () => {
+    writeRaw(`${buildConfirmLines(question, yesSelected).join("\n")}\n`);
+
     while (true) {
-      renderConfirm(question, yesSelected);
       const key = parseKey(await readKey());
 
       if (key === "ctrl-c") {
@@ -201,9 +295,15 @@ export async function promptConfirm(question: string, defaultYes = true): Promis
         return yesSelected;
       }
       if (key === "left" || key === "no") {
-        yesSelected = false;
+        if (yesSelected) {
+          yesSelected = false;
+          updateConfirmPromptLine(question, yesSelected);
+        }
       } else if (key === "right" || key === "yes") {
-        yesSelected = true;
+        if (!yesSelected) {
+          yesSelected = true;
+          updateConfirmPromptLine(question, yesSelected);
+        }
       }
     }
   });

package/src/installer/search-policy.ts

@@ -1,32 +1,86 @@
 /** Shared code-search policy text for instructions, Cursor rules, and sub-agents. */
 
-export const SEARCH_POLICY_TABLE = `| Task | Use | Not |
+export const SNIPPET_GUIDANCE =
+  "Search returns compact snippets (~±15 lines around the best match). " +
+  "When a hit has `truncated: true`, call `expand` with `file_path` and `anchor_line` " +
+  "(or `start_line`) — do not re-search or Read the whole file.";
+
+export interface NativeToolNames {
+  explorationDenied: string;
+  grep: string;
+  read: string;
+}
+
+export function buildSearchPolicyTable(native: NativeToolNames): string {
+  return `| Task | Use | Not |
 |------|-----|-----|
-| How/where/what handles X? | Miru MCP \`search\` (once) | Grep, Glob, SemanticSearch, repeat searches |
-| Same file, more context | Miru MCP \`expand\` | Re-search, Read whole file |
-| Similar code elsewhere | Miru MCP \`find_related\` | Grep chains |
-| Search docs or config | Miru \`search\` with \`content\` | Grep README paths |
-| Exact literal exists? | Grep | Miru |
-| Edit a known file:line | Read (after Miru found it) | Read-before-search |`;
+| How/where/what handles X? | Miru MCP \`search\` (once) | ${native.explorationDenied}, repeat searches |
+| Same file, more context | Miru MCP \`expand\` on \`truncated: true\` | Re-search, ${native.read} whole file |
+| Similar code elsewhere | Miru MCP \`find_related\` | ${native.grep} chains |
+| Search docs or config | Miru \`search\` | ${native.grep} README paths |
+| Exact literal exists? | ${native.grep} | Miru |
+| Edit a known file:line | ${native.read} (after Miru found it) | ${native.read}-before-search |`;
+}
 
-export const SEARCH_POLICY_BODY = `DO NOT use Grep, Glob, SemanticSearch, or Read to explore how code works when Miru MCP is available.
+export function buildSearchPolicyBody(native: NativeToolNames): string {
+  return `DO NOT use ${native.explorationDenied} to explore how code works when Miru MCP is available.
+
+${SNIPPET_GUIDANCE}
 
 Use Miru MCP tools:
 - \`search\` — one call per question; pass project root as \`repo\`
-- \`expand\` — adjacent chunks in the same file when a hit looks truncated (\`file_path\` + \`line\` from the hit)
-- \`find_related\` — similar code in other files after a \`search\` hit
+- \`expand\` — more context in the same file when \`truncated: true\` (\`file_path\` + \`anchor_line\` or \`start_line\`)
+- \`find_related\` — similar code in other files (hits may also be snippets; use \`expand\` if truncated)
 
 Stop rules:
 - Answer from the first \`search\` — do not re-search with paraphrases
-- If context is cut off in one file, call \`expand\` — not another \`search\` or a full-file Read
-- Read is for editing a path Miru already gave you, not for exploration
+- On \`truncated: true\`, call \`expand\` — not another \`search\` or a full-file ${native.read}
+- ${native.read} is for editing a path Miru already gave you, not for exploration
 
 Native tools are allowed ONLY when:
 - confirming an exact literal string (env var name, error code, quoted text)
 - reading a file you already located via Miru, to edit it
 - searching outside the indexed repo
 
-${SEARCH_POLICY_TABLE}`;
+${buildSearchPolicyTable(native)}`;
+}
+
+export function buildMcpWorkflow(native: NativeToolNames): string {
+  return `### MCP workflow
+
+1. Call \`search\` with \`repo\` set to the project root (local path or https:// git URL).
+2. If a hit has \`truncated: true\`, call \`expand\` with \`file_path\` and \`anchor_line\` (or \`start_line\`).
+3. Use \`find_related\` to trace similar code in other files — not for more context in the same file.
+4. ${native.read} via \`absolute_path\` only when editing or when \`expand\` still lacks context.`;
+}
+
+const CLI_FALLBACK = `### CLI fallback (no MCP in this session)
+
+\`\`\`bash
+miru search "authentication flow" .
+miru expand src/auth.ts 42 .
+miru find-related src/auth.ts 42 .
+\`\`\`
+
+If \`miru\` is not on \`$PATH\`, use \`bunx @takara-ai/miru-code\`.`;
+
+export function buildSubagentBody(native: NativeToolNames): string {
+  return `When Miru MCP is available, use MCP \`search\`, \`expand\`, and \`find_related\` — not ${native.explorationDenied} for exploration.
+
+${buildSearchPolicyBody(native)}
+
+${buildMcpWorkflow(native)}
+
+${CLI_FALLBACK}`;
+}
+
+export const DEFAULT_NATIVE_TOOLS: NativeToolNames = {
+  explorationDenied: "Grep, Glob, SemanticSearch, or Read",
+  grep: "Grep",
+  read: "Read",
+};
+
+export const SEARCH_POLICY_BODY = buildSearchPolicyBody(DEFAULT_NATIVE_TOOLS);
 
 export const INSTRUCTIONS_MARKDOWN = `## Miru Code Search
 
@@ -54,25 +108,31 @@ alwaysApply: true
 
 ${SEARCH_POLICY_BODY}
 
-When Miru MCP is connected, call \`search\` once per question. Use \`expand\` for same-file context. Never use Cursor SemanticSearch or Grep for codebase questions unless confirming an exact literal.`;
+When Miru MCP is connected, call \`search\` once per question. On \`truncated: true\`, call \`expand\` with \`file_path\` and \`anchor_line\`. Never use Cursor SemanticSearch or Grep for codebase questions unless confirming an exact literal.`;
 
-export const SUBAGENT_BODY = `When Miru MCP is available, use MCP \`search\`, \`expand\`, and \`find_related\` — not Grep, Glob, SemanticSearch, or Read-for-exploration.
+export const SUBAGENT_BODY = buildSubagentBody(DEFAULT_NATIVE_TOOLS);
 
-${SEARCH_POLICY_BODY}
+export const MCP_SERVER_INSTRUCTIONS =
+  "DO NOT use Grep, Glob, SemanticSearch, or Read to explore code when this server is available. " +
+  `${SNIPPET_GUIDANCE} ` +
+  "Workflow: (1) `search` once per question — do NOT re-search with paraphrases. " +
+  "(2) On `truncated: true`, call `expand` with `file_path` and `anchor_line` (or `start_line`) — do NOT read the whole file. " +
+  "(3) `find_related` traces similar code in other files, not more context in the same file. " +
+  "Always pass the project root as `repo`. Local repos return `absolute_path` on each hit — use Read only to edit. " +
+  "Native search is only for exact literal confirmation or files outside the indexed repo.";
 
-### MCP workflow
+export const MCP_SEARCH_TOOL_DESCRIPTION =
+  "DEFAULT code exploration tool. Returns compact snippets (~±15 lines). One call per question is usually enough. " +
+  "When a hit has `truncated: true`, call `expand` with `file_path` and `anchor_line` (or `start_line`) — not re-search or Read.";
 
-1. Call \`search\` with \`repo\` set to the project root (local path or https:// git URL).
-2. If a hit looks truncated, call \`expand\` with the hit's \`file_path\` and \`line\`.
-3. Use \`find_related\` to trace similar code in other files — not for more context in the same file.
-4. Read via \`absolute_path\` only when editing or when \`expand\` still lacks context.
+export const MCP_EXPAND_TOOL_DESCRIPTION =
+  "More context in the SAME file as a search hit. Pass `file_path` + `anchor_line` or `start_line` from a truncated hit; " +
+  "returns adjacent indexed chunks. Use when `truncated: true` — NOT for similar code in other files (use find_related). " +
+  "Prefer this over re-searching or reading the whole file.";
 
-### CLI fallback (no MCP in this session)
+export const MCP_FIND_RELATED_TOOL_DESCRIPTION =
+  "Find code similar to a file:line in OTHER parts of the codebase. Results may be snippets; use `expand` when `truncated: true`. " +
+  "For more context in the same file, use `expand` instead.";
 
-\`\`\`bash
-miru search "authentication flow" .
-miru expand src/auth.ts 42 .
-miru find-related src/auth.ts 42 .
-\`\`\`
-
-If \`miru\` is not on \`$PATH\`, use \`bunx @takara-ai/miru-code\`.`;
+export const SEARCH_GUARD_EXPAND_HINT =
+  "If a hit has `truncated: true`, call `expand` with `file_path` and `anchor_line` — do not re-search or read the whole file.";

package/src/mcp/index-cache.ts

@@ -3,7 +3,12 @@ import { resolve } from "node:path";
 import { normalizeRelativePath, relativePathFromRoot } from "../index/incremental.ts";
 import { MiruIndex } from "../miru-index.ts";
 import type { ContentType } from "../types.ts";
-import { computeSourceCacheKey, isGitUrl } from "../utils.ts";
+import {
+  computeSourceCacheKey,
+  isAllowedRepoSource,
+  isGitUrl,
+  validateLocalRepoPath,
+} from "../utils.ts";
 
 const CACHE_MAX_SIZE = 10;
 
@@ -28,7 +33,10 @@ const WATCH_IGNORED_DIR_NAMES = new Set([
   ".eggs",
 ]);
 
+type WatcherHandle = ReturnType<typeof watch>;
+
 type CacheEntry = {
+  source: string;
   index: MiruIndex | null;
   task: Promise<MiruIndex> | null;
   pendingPaths: Set<string>;
@@ -37,7 +45,7 @@ type CacheEntry = {
 };
 
 export function mcpWatchEnabled(): boolean {
-  const raw = process.env.MIRU_MCP_WATCH ?? process.env.SEMBLE_MCP_WATCH;
+  const raw = process.env.MIRU_MCP_WATCH;
   return raw !== "0" && raw !== "false";
 }
 
@@ -59,15 +67,14 @@ export class IndexCache {
   private readonly content: ContentType[];
   private readonly defaultRef: string | null;
   private readonly entries = new Map<string, CacheEntry>();
-  private watcher: ReturnType<typeof watch> | null = null;
-  private watchedSource: string | null = null;
+  readonly watchers = new Map<string, WatcherHandle>();
 
   constructor(content: ContentType[] = ["code"], defaultRef: string | null = null) {
     this.content = content;
     this.defaultRef = defaultRef;
   }
 
-  private ensureEntry(cacheKey: string): CacheEntry {
+  private ensureEntry(cacheKey: string, source: string): CacheEntry {
     let entry = this.entries.get(cacheKey);
     if (!entry) {
       if (this.entries.size >= CACHE_MAX_SIZE) {
@@ -77,6 +84,7 @@ export class IndexCache {
         }
       }
       entry = {
+        source,
         index: null,
         task: null,
         pendingPaths: new Set(),
@@ -89,9 +97,19 @@ export class IndexCache {
   }
 
   private clearEntry(cacheKey: string): void {
+    const entry = this.entries.get(cacheKey);
+    if (entry && !isGitUrl(entry.source)) {
+      this.stopWatcher(resolve(entry.source));
+    }
     this.entries.delete(cacheKey);
   }
 
+  private stopWatcher(resolvedPath: string): void {
+    const watcher = this.watchers.get(resolvedPath);
+    watcher?.close();
+    this.watchers.delete(resolvedPath);
+  }
+
   private startBuild(
     source: string,
     ref: string | null | undefined,
@@ -105,7 +123,7 @@ export class IndexCache {
       return index;
     })();
 
-    const entry = this.ensureEntry(cacheKey);
+    const entry = this.ensureEntry(cacheKey, source);
     entry.task = task;
     void task
       .then((index) => {
@@ -126,7 +144,7 @@ export class IndexCache {
   async get(source: string, ref?: string | null): Promise<MiruIndex> {
     const resolvedRef = ref ?? this.defaultRef;
     const cacheKey = computeSourceCacheKey(source, resolvedRef);
-    const entry = this.ensureEntry(cacheKey);
+    const entry = this.ensureEntry(cacheKey, source);
 
     if (!entry.task) {
       this.startBuild(source, resolvedRef, cacheKey);
@@ -151,7 +169,7 @@ export class IndexCache {
 
   private queueIndexedPaths(source: string, index: MiruIndex): void {
     const cacheKey = computeSourceCacheKey(source);
-    const entry = this.ensureEntry(cacheKey);
+    const entry = this.ensureEntry(cacheKey, source);
     for (const chunk of index.chunks) {
       entry.pendingPaths.add(normalizeRelativePath(chunk.file_path));
     }
@@ -161,7 +179,10 @@ export class IndexCache {
   /** macOS recursive fs.watch often omits filename; refresh all indexed paths incrementally. */
   private noteAmbiguousDirectoryChange(source: string): void {
     const cacheKey = computeSourceCacheKey(source);
-    const entry = this.ensureEntry(cacheKey);
+    const entry = this.entries.get(cacheKey);
+    if (!entry) {
+      return;
+    }
 
     if (entry.index) {
       this.queueIndexedPaths(source, entry.index);
@@ -186,7 +207,10 @@ export class IndexCache {
     }
 
     const cacheKey = computeSourceCacheKey(source);
-    const entry = this.ensureEntry(cacheKey);
+    const entry = this.entries.get(cacheKey);
+    if (!entry) {
+      return;
+    }
     const rel = relativePathFromRoot(source, filename);
     if (!rel) {
       return;
@@ -246,29 +270,31 @@ export class IndexCache {
     if (!mcpWatchEnabled() || isGitUrl(source)) {
       return;
     }
-    const resolved = resolve(source);
-    if (this.watchedSource === resolved) {
-      return;
-    }
-    this.watchedSource = resolved;
-    this.startWatcher(resolved);
+    this.startWatcher(source);
   }
 
   startWatcher(path: string): void {
     const resolved = resolve(path);
-    if (this.watcher) {
-      this.watcher.close();
+    if (this.watchers.has(resolved)) {
+      return;
     }
 
-    this.watcher = watch(resolved, { recursive: true }, (_event, filename) => {
+    const watcher = watch(resolved, { recursive: true }, (_event, filename) => {
       this.noteFileChange(resolved, filename);
     });
+    this.watchers.set(resolved, watcher);
+  }
+
+  get watcher(): WatcherHandle | null {
+    const handles = [...this.watchers.values()];
+    return handles[handles.length - 1] ?? null;
   }
 
   close(): void {
-    this.watcher?.close();
-    this.watcher = null;
-    this.watchedSource = null;
+    for (const watcher of this.watchers.values()) {
+      watcher.close();
+    }
+    this.watchers.clear();
     this.entries.clear();
   }
 }
@@ -284,12 +310,19 @@ export async function getIndexForRepo(
     );
   }
 
-  if (isGitUrl(repo) && !repo.startsWith("https://") && !repo.startsWith("http://")) {
+  if (isGitUrl(repo) && !isAllowedRepoSource(repo)) {
+    if (repo.startsWith("http://")) {
+      throw new Error(
+        "Plain http:// git URLs are disabled by default. Set MIRU_ALLOW_HTTP_GIT=1 to opt in.",
+      );
+    }
     throw new Error(
-      `Only https://, http://, or local directory paths are accepted as \`repo\`. Got: ${repo}`,
+      `Only https:// git URLs or local directory paths are accepted as \`repo\`. Got: ${repo}`,
     );
   }
 
+  validateLocalRepoPath(repo);
+
   try {
     return await cache.get(repo, ref);
   } catch (err) {

package/src/mcp/server.ts

@@ -1,5 +1,12 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
+import packageJson from "../../package.json";
+import {
+  MCP_EXPAND_TOOL_DESCRIPTION,
+  MCP_FIND_RELATED_TOOL_DESCRIPTION,
+  MCP_SEARCH_TOOL_DESCRIPTION,
+  MCP_SERVER_INSTRUCTIONS,
+} from "../installer/search-policy.ts";
 import type { ContentType } from "../types.ts";
 import {
   clampMcpTopK,
@@ -19,32 +26,21 @@ const REPO_DESCRIPTION =
   "Pass the project root for local workspaces. " +
   "The index is built on the first tool call and cached for the session.";
 
-const SERVER_INSTRUCTIONS =
-  "DO NOT use Grep, Glob, SemanticSearch, or Read to explore code when this server is available. " +
-  "Workflow: (1) `search` once per question — do NOT re-search with paraphrases. " +
-  "(2) If context looks cut off, call `expand` on the hit's file_path + line — do NOT read the whole file. " +
-  "(3) `find_related` traces similar code in other files, not more context in the same file. " +
-  "Always pass the project root as `repo`. Local repos return `absolute_path` on each hit — use Read only to edit. " +
-  "Native search is only for exact literal confirmation or files outside the indexed repo.";
-
 export function createMcpServer(cache: IndexCache): McpServer {
   const server = new McpServer(
     {
       name: "miru",
-      version: "0.1.0",
+      version: packageJson.version,
     },
     {
-      instructions: SERVER_INSTRUCTIONS,
+      instructions: MCP_SERVER_INSTRUCTIONS,
     },
   );
 
   server.registerTool(
     "search",
     {
-      description:
-        "DEFAULT code exploration tool. One call per question is usually enough. " +
-        "If a hit looks truncated, call `expand` (same file) instead of re-searching or Read. " +
-        "Indexes `repo` on first call; later calls reuse the session cache.",
+      description: `${MCP_SEARCH_TOOL_DESCRIPTION} Indexes \`repo\` on first call; later calls reuse the session cache.`,
       inputSchema: {
         query: z.string().describe("Natural language or code query."),
         repo: z.string().describe(REPO_DESCRIPTION),
@@ -72,7 +68,7 @@ export function createMcpServer(cache: IndexCache): McpServer {
           return toolText(JSON.stringify({ error: "No results found." }));
         }
         const repoRoot = localRepoRoot(repo);
-        return toolText(JSON.stringify(formatResults(query, results, { repoRoot })));
+        return toolText(JSON.stringify(formatResults(query, results, { repoRoot, snippet: true })));
       } catch (err) {
         return toolText(err instanceof Error ? err.message : String(err));
       }
@@ -82,15 +78,17 @@ export function createMcpServer(cache: IndexCache): McpServer {
   server.registerTool(
     "expand",
     {
-      description:
-        "More context in the SAME file as a search hit. Pass file_path + line from a hit; returns adjacent indexed chunks. " +
-        "Use when a chunk looks cut off — NOT for finding similar code in other files (use find_related). " +
-        "Prefer this over re-searching or reading the whole file.",
+      description: MCP_EXPAND_TOOL_DESCRIPTION,
       inputSchema: {
         file_path: z
           .string()
           .describe("Path from a search hit (`file_path` or `absolute_path` for local repos)."),
-        line: z.number().int().describe("Line number (1-indexed) from the hit."),
+        line: z
+          .number()
+          .int()
+          .describe(
+            "Line from the hit: `anchor_line` when truncated, otherwise `start_line` (1-indexed).",
+          ),
         repo: z.string().describe(REPO_DESCRIPTION),
         before: z
           .number()
@@ -143,16 +141,17 @@ export function createMcpServer(cache: IndexCache): McpServer {
   server.registerTool(
     "find_related",
     {
-      description:
-        "Find code similar to a file:line in OTHER parts of the codebase. " +
-        "For more context in the same file, use `expand` instead.",
+      description: MCP_FIND_RELATED_TOOL_DESCRIPTION,
       inputSchema: {
         file_path: z
           .string()
+          .describe("Path from a search hit (`file_path` or `absolute_path` for local repos)."),
+        line: z
+          .number()
+          .int()
           .describe(
-            "Path from a search hit (`file_path` or `absolute_path` for local repos).",
+            "Line from the hit: `anchor_line` when truncated, otherwise `start_line` (1-indexed).",
           ),
-        line: z.number().int().describe("Line number (1-indexed)."),
         repo: z.string().describe(REPO_DESCRIPTION),
         top_k: z
           .number()
@@ -160,7 +159,9 @@ export function createMcpServer(cache: IndexCache): McpServer {
           .min(1)
           .max(MAX_MCP_TOP_K)
           .optional()
-          .describe(`Number of similar chunks to return (default ${DEFAULT_MCP_TOP_K}, max ${MAX_MCP_TOP_K}).`),
+          .describe(
+            `Number of similar chunks to return (default ${DEFAULT_MCP_TOP_K}, max ${MAX_MCP_TOP_K}).`,
+          ),
       },
     },
     async ({ file_path: filePath, line, repo, top_k: topK }) => {
@@ -181,7 +182,10 @@ export function createMcpServer(cache: IndexCache): McpServer {
         }
         return toolText(
           JSON.stringify(
-            formatResults(`Chunks related to ${filePath}:${line}`, results, { repoRoot }),
+            formatResults(`Chunks related to ${filePath}:${line}`, results, {
+              repoRoot,
+              snippet: true,
+            }),
           ),
         );
       } catch (err) {