@takara-ai/miru-code 0.4.10 → 0.4.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takara-ai/miru-code",
-  "version": "0.4.10",
+  "version": "0.4.11",
   "description": "Miru (見る) — hybrid code search for agents. Bun, TypeScript, Takara embeddings.",
   "type": "module",
   "license": "MIT",

package/src/agents/claude.md

@@ -1,28 +1,31 @@
 ---
 name: miru-code
-description: Code search via Miru MCP. Use search and find_related for any question about how code works. DO NOT use Grep, Glob, or Read for exploration when Miru MCP is available.
+description: Code search via Miru MCP. Use search, expand, and find_related. DO NOT use Grep, Glob, or Read for exploration when Miru MCP is available.
 tools: Bash, Read
 ---
 
-When Miru MCP is available, use MCP `search` and `find_related` — not Grep, Glob, or Read-for-exploration.
+When Miru MCP is available, use MCP `search`, `expand`, and `find_related` — not Grep, Glob, or Read-for-exploration.
 
 | Task | Tool |
 |------|------|
-| How/where/what handles X? | Miru `search` |
+| How/where/what handles X? | Miru `search` (once) |
+| Same file, more context | Miru `expand` |
 | Similar implementations | Miru `find_related` |
 | Exact literal confirmation | Grep |
 | Edit a located file | Read |
 
 ### MCP workflow
 
-1. Call `search` with `repo` set to the project root.
-2. Use `find_related` with a hit's `file_path` and `line`.
-3. Read files only to edit or when chunks lack context.
+1. Call `search` with `repo` set to the project root; follow `guidance` in the response.
+2. If context is cut off, call `expand` with the hit's `file_path` and `line`.
+3. Use `find_related` for similar code in other files — not for same-file context.
+4. Read files only to edit or when `expand` still lacks context.
 
 ### CLI fallback
 
 ```bash
 miru search "authentication flow" .
+miru expand src/auth.ts 42 .
 miru find-related src/auth.ts 42 .
 ```
 

package/src/agents/copilot.md

@@ -1,13 +1,14 @@
 ---
 name: miru-code
-description: Code search via Miru MCP. Use search and find_related instead of grep_search or codebase_search when Miru is connected.
+description: Code search via Miru MCP. Use search, expand, and find_related instead of grep_search or codebase_search when Miru is connected.
 ---
 
-When Miru MCP is available, use `search` and `find_related` instead of `grep_search`, `codebase_search`, or broad file reads.
+When Miru MCP is available, use `search`, `expand`, and `find_related` instead of `grep_search`, `codebase_search`, or broad file reads.
 
 | Task | Tool |
 |------|------|
-| How/where/what handles X? | Miru `search` |
+| How/where/what handles X? | Miru `search` (once; follow `guidance`) |
+| Same file, more context | Miru `expand` |
 | Similar implementations | Miru `find_related` |
 | Exact literal confirmation | grep_search |
 | Edit a located file | read_file |

package/src/agents/cursor.md

@@ -1,18 +1,20 @@
 ---
 name: miru-code
-description: Code search via Miru MCP. Use search and find_related for any question about how code works. DO NOT use Grep, Glob, or SemanticSearch when Miru MCP is available.
+description: Code search via Miru MCP. Use search, expand, and find_related. DO NOT use Grep, Glob, or SemanticSearch when Miru MCP is available.
 ---
 
 Use Miru MCP tools when connected:
 
-- `search` — natural-language or code query; always pass project root as `repo`
-- `find_related` — similar chunks after a search hit (`file_path` + `line`)
+- `search` — one call per question; always pass project root as `repo`; read `guidance` in the response
+- `expand` — adjacent chunks in the same file when a hit looks truncated (`file_path` + `line`)
+- `find_related` — similar code in other files after a search hit
 
-Do not use Grep, Glob, SemanticSearch, or Read to explore the codebase when Miru MCP is available.
+Do not re-search with paraphrases when `guidance.sufficient` is true. Do not read whole files for exploration.
 
 | Task | Tool |
 |------|------|
-| How/where/what handles X? | Miru `search` |
+| How/where/what handles X? | Miru `search` (once) |
+| Same file, more context | Miru `expand` |
 | Similar implementations | Miru `find_related` |
 | Exact literal confirmation | Grep |
 | Edit a located file | Read |
@@ -21,6 +23,7 @@ CLI fallback when MCP is unavailable:
 
 ```bash
 miru search "authentication flow" .
+miru expand src/auth.ts 42 .
 miru find-related src/auth.ts 42 .
 ```
 

package/src/agents/gemini.md

@@ -1,17 +1,18 @@
 ---
 name: miru-code
-description: Code search via Miru MCP. Use search and find_related instead of grep_search or read_file for exploration.
+description: Code search via Miru MCP. Use search, expand, and find_related instead of grep_search or read_file for exploration.
 ---
 
-When Miru MCP is available, use `search` and `find_related` instead of `grep_search`, `glob`, or `read_file` for codebase exploration.
+When Miru MCP is available, use `search`, `expand`, and `find_related` instead of `grep_search`, `glob`, or `read_file` for codebase exploration.
 
 | Task | Tool |
 |------|------|
-| How/where/what handles X? | Miru `search` |
+| How/where/what handles X? | Miru `search` (once; follow `guidance`) |
+| Same file, more context | Miru `expand` |
 | Similar implementations | Miru `find_related` |
 | Exact literal confirmation | grep_search |
 | Edit a located file | read_file |
 
-Pass project root as `repo` on every MCP call.
+Pass project root as `repo` on every MCP call. Do not re-search when `guidance.sufficient` is true.
 
 CLI fallback: `miru search "query" .` or `bunx @takara-ai/miru-code search "query" .`

package/src/agents/kiro.md

@@ -1,10 +1,10 @@
 ---
 name: miru-code
-description: Code search via Miru MCP. Use search and find_related for codebase exploration instead of built-in grep or file search.
+description: Code search via Miru MCP. Use search, expand, and find_related for codebase exploration instead of built-in grep or file search.
 ---
 
-When Miru MCP is available, use `search` and `find_related` before any built-in search or broad file reads.
+When Miru MCP is available, use `search`, `expand`, and `find_related` before any built-in search or broad file reads.
 
-Pass project root as `repo`. Use Grep only for exact literal confirmation.
+Pass project root as `repo`. Follow `guidance` in search responses. Use `expand` for truncated hits in the same file. Use Grep only for exact literal confirmation.
 
 CLI fallback: `miru search "query" .`

package/src/agents/opencode.md

@@ -1,11 +1,11 @@
 ---
 name: miru-code
-description: Code search via Miru MCP. Use search and find_related instead of grep or glob for exploration.
+description: Code search via Miru MCP. Use search, expand, and find_related instead of grep or glob for exploration.
 mode: subagent
 ---
 
-When Miru MCP is available, use `search` and `find_related` instead of grep, glob, or read-for-exploration.
+When Miru MCP is available, use `search`, `expand`, and `find_related` instead of grep, glob, or read-for-exploration.
 
-Pass project root as `repo` on every MCP call.
+Pass project root as `repo` on every MCP call. Follow `guidance` in search responses.
 
 CLI fallback: `miru search "query" .`

package/src/cli.ts

@@ -27,7 +27,15 @@ import { MiruIndex } from "./miru-index.ts";
 import { ensureCredentials, runClearCredentials, runSetup } from "./setup.ts";
 import { withSpinner } from "./spinner.ts";
 import type { ContentType, SearchResult } from "./types.ts";
-import { formatResults, resolveChunk, resolveContent, resolveSearchPath } from "./utils.ts";
+import {
+  expandChunksAtLine,
+  formatExpandResults,
+  formatResults,
+  localRepoRoot,
+  resolveChunk,
+  resolveContent,
+  resolveSearchPath,
+} from "./utils.ts";
 
 loadEnvFiles();
 normalizeTakaraApiKeyEnv();
@@ -35,6 +43,7 @@ await loadStoredCredentials();
 
 const CLI_COMMANDS = new Set([
   "search",
+  "expand",
   "find-related",
   "init",
   "install",
@@ -148,6 +157,54 @@ async function runSearch(
   emitSearchOutput(query, index.results, jsonFlag);
 }
 
+async function runExpand(
+  path: string,
+  filePath: string,
+  line: number,
+  before: number,
+  after: number,
+  content: ContentType[],
+  jsonFlag: boolean,
+): Promise<void> {
+  await ensureCredentials({ interactive: true });
+
+  const payload = await withSpinner("Expanding chunks", async () => {
+    const built = await MiruIndex.fromSource(path, content);
+    const repoRoot = localRepoRoot(path);
+    const { anchor, chunks: expanded } = expandChunksAtLine(
+      built.chunks,
+      filePath,
+      line,
+      repoRoot,
+      before,
+      after,
+    );
+    await built.saveToDefaultCache(path);
+    return formatExpandResults(filePath, line, anchor, expanded, {
+      repoRoot,
+      before,
+      after,
+    });
+  });
+
+  if (!payload.anchor) {
+    fail(`No chunk found at ${filePath}:${line}.`);
+    process.exit(1);
+  }
+
+  if (prefersJsonOutput(jsonFlag)) {
+    console.log(JSON.stringify(payload));
+    return;
+  }
+
+  const chunks = payload.chunks as Array<{ location?: string; content?: string }>;
+  for (const chunk of chunks) {
+    process.stdout.write(`\n${chunk.location ?? ""}\n`);
+    process.stdout.write(`${chunk.content ?? ""}\n`);
+  }
+  process.stdout.write("\n");
+}
+
 async function runFindRelated(
   path: string,
   filePath: string,
@@ -308,6 +365,29 @@ async function runCli(argv: string[]): Promise<void> {
     return;
   }
 
+  if (command === "expand") {
+    const filePath = sizedRest[0];
+    const lineRaw = sizedRest[1];
+    if (!filePath || !lineRaw) {
+      printCommandHelp("expand");
+      process.exit(1);
+    }
+    const line = Number(lineRaw);
+    const path = resolveSearchPath(sizedRest[2] ?? process.cwd());
+    let before = 1;
+    let after = 1;
+    for (let i = 3; i < sizedRest.length; i++) {
+      const arg = sizedRest[i];
+      if (arg === "--before" && sizedRest[i + 1]) {
+        before = Number(sizedRest[++i]);
+      } else if (arg === "--after" && sizedRest[i + 1]) {
+        after = Number(sizedRest[++i]);
+      }
+    }
+    await runExpand(path, filePath, line, before, after, content, jsonFlag);
+    return;
+  }
+
   if (command === "find-related") {
     const filePath = sizedRest[0];
     const lineRaw = sizedRest[1];

package/src/help.ts

@@ -31,6 +31,7 @@ export function printMainHelp(): void {
 
   section("Commands");
   commandRow("search", "Hybrid search over a codebase");
+  commandRow("expand", "Adjacent chunks in the same file as a hit");
   commandRow("find-related", "Find chunks related to a file:line");
   commandRow("setup", "Save your Takara API key locally");
   commandRow("install", "Configure miru across coding agents");
@@ -85,6 +86,14 @@ export function printCommandHelp(command: string): void {
       writeStdout('  miru search "where is auth" ./src -k 10 --content code docs');
       writeStdout("");
       return;
+    case "expand":
+      printCommandHeader("expand", "More context in the same file as a search hit.");
+      section("Usage");
+      writeStdout("  miru expand <file> <line> [path] [--before N] [--after N]");
+      section("Example");
+      writeStdout("  miru expand src/auth.ts 42 . --before 2 --after 2");
+      writeStdout("");
+      return;
     case "find-related":
       printCommandHeader("find-related", "Semantic neighbors of a file location.");
       section("Usage");
@@ -140,7 +149,7 @@ export function printCommandHelp(command: string): void {
       section("Usage");
       writeStdout("  miru [--ref BRANCH] [--content TYPE ...]");
       writeStdout("");
-      writeStdout("Indexes on the first search/find_related tool call (repo argument).");
+      writeStdout("Indexes on the first search/expand/find_related tool call (repo argument).");
       writeStdout("");
       return;
     default:

package/src/installer/hooks/search-guard.ts

@@ -1,5 +1,5 @@
-const REDIRECT_MESSAGE =
-  "Use Miru MCP `search` (pass project root as `repo`) instead of built-in search tools. " +
+const REDIRECT_PREFIX =
+  "Use Miru MCP instead of built-in search tools (pass project root as `repo`). " +
   "Grep/Glob/Shell are only for exact literal confirmation or non-code tasks.";
 
 const MIRU_TOOL_RE = /miru/i;
@@ -70,6 +70,61 @@ function grepPatternFromInput(toolInput: Record<string, unknown>): string {
   );
 }
 
+function globPatternFromInput(toolInput: Record<string, unknown>): string {
+  return String(
+    toolInput.glob_pattern ?? toolInput.pattern ?? toolInput.glob ?? toolInput.path ?? "",
+  );
+}
+
+/** MCP tool descriptor paths are not codebase exploration. */
+export function isMcpDescriptorGlob(pattern: string): boolean {
+  const normalized = pattern.replace(/\\/g, "/").toLowerCase();
+  return (
+    normalized.includes("/mcps/") ||
+    normalized.includes("mcps/**/tools") ||
+    /\/mcps\/[^/]+\/tools/.test(normalized)
+  );
+}
+
+function suggestedMiruQuery(toolName: string, toolInput: Record<string, unknown>): string {
+  if (GREP_TOOL_RE.test(toolName) || toolName.toLowerCase() === "grep_search") {
+    const pattern = grepPatternFromInput(toolInput).trim();
+    if (pattern) {
+      return pattern;
+    }
+  }
+  if (GLOB_TOOL_RE.test(toolName)) {
+    const pattern = globPatternFromInput(toolInput).trim();
+    if (pattern) {
+      return `files matching ${pattern}`;
+    }
+  }
+  if (SEMANTIC_TOOL_RE.test(toolName)) {
+    const query = String(toolInput.query ?? toolInput.search_term ?? "").trim();
+    if (query) {
+      return query;
+    }
+  }
+  if (SHELL_TOOL_RE.test(toolName)) {
+    const command = String(toolInput.command ?? toolInput.cmd ?? "").trim();
+    if (command) {
+      return command;
+    }
+  }
+  return "your question about how the code works";
+}
+
+export function searchGuardBlockReason(
+  toolName: string,
+  toolInput: Record<string, unknown>,
+): string {
+  const query = suggestedMiruQuery(toolName, toolInput);
+  return (
+    `${REDIRECT_PREFIX} Try Miru \`search\` with query "${query}". ` +
+    "If the hit looks truncated, call `expand` on its file_path + line — do not re-search or read the whole file."
+  );
+}
+
 /** Map host-specific stdin JSON into a common evaluation shape. */
 export function normalizeHookPayload(raw: Record<string, unknown>): HookPayload {
   const agentAction = raw.agent_action_name;
@@ -116,21 +171,25 @@ export function evaluateSearchGuard(payload: HookPayload): GuardDecision {
     if (isLiteralGrepPattern(pattern)) {
       return { block: false, reason: "" };
     }
-    return { block: true, reason: REDIRECT_MESSAGE };
+    return { block: true, reason: searchGuardBlockReason(toolName, toolInput) };
   }
 
   if (GLOB_TOOL_RE.test(toolName)) {
-    return { block: true, reason: REDIRECT_MESSAGE };
+    const pattern = globPatternFromInput(toolInput);
+    if (isMcpDescriptorGlob(pattern)) {
+      return { block: false, reason: "" };
+    }
+    return { block: true, reason: searchGuardBlockReason(toolName, toolInput) };
   }
 
   if (SEMANTIC_TOOL_RE.test(toolName)) {
-    return { block: true, reason: REDIRECT_MESSAGE };
+    return { block: true, reason: searchGuardBlockReason(toolName, toolInput) };
   }
 
   if (SHELL_TOOL_RE.test(toolName)) {
     const command = String(toolInput.command ?? toolInput.cmd ?? "");
     if (isExplorationShell(command)) {
-      return { block: true, reason: REDIRECT_MESSAGE };
+      return { block: true, reason: searchGuardBlockReason(toolName, toolInput) };
     }
     return { block: false, reason: "" };
   }
@@ -173,7 +232,7 @@ export function cursorHookResponse(reason: string): string {
   return JSON.stringify({
     permission: "deny",
     agent_message: reason,
-    user_message: "Miru: use MCP search instead of built-in grep/glob.",
+    user_message: "Miru: use MCP search/expand instead of built-in grep/glob.",
   });
 }
 

package/src/installer/search-policy.ts

@@ -2,17 +2,24 @@
 
 export const SEARCH_POLICY_TABLE = `| Task | Use | Not |
 |------|-----|-----|
-| How/where/what handles X? | Miru MCP \`search\` | Grep, Glob, SemanticSearch, Read |
-| Similar code elsewhere | Miru MCP \`find_related\` | Read whole files |
+| 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 |`;
 
 export const SEARCH_POLICY_BODY = `DO NOT use Grep, Glob, SemanticSearch, or Read to explore how code works when Miru MCP is available.
 
-Use Miru MCP tools first:
-- \`search\` — natural-language or code query; pass project root as \`repo\`
-- \`find_related\` — similar chunks after a \`search\` hit (\`file_path\` + \`line\`)
+Use Miru MCP tools:
+- \`search\` — one call per question; pass project root as \`repo\`; read \`guidance.sufficient\` and \`suggested_next\` in the response
+- \`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
+
+Stop rules:
+- If \`guidance.sufficient\` is true, answer — 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
 
 Native tools are allowed ONLY when:
 - confirming an exact literal string (env var name, error code, quoted text)
@@ -31,6 +38,7 @@ CLI fallback when MCP is unavailable:
 
 \`\`\`bash
 miru search "authentication flow" .
+miru expand src/auth.ts 42 .
 miru find-related src/auth.ts 42 .
 \`\`\`
 
@@ -46,22 +54,24 @@ alwaysApply: true
 
 ${SEARCH_POLICY_BODY}
 
-When Miru MCP is connected, call \`search\` before any built-in search tool. Never use Cursor SemanticSearch or Grep for codebase questions unless confirming an exact literal.`;
+When Miru MCP is connected, call \`search\` once per question and follow \`guidance\` in the response. Use \`expand\` for same-file context. 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\` and \`find_related\` — not Grep, Glob, SemanticSearch, or Read-for-exploration.
+export const SUBAGENT_BODY = `When Miru MCP is available, use MCP \`search\`, \`expand\`, and \`find_related\` — not Grep, Glob, SemanticSearch, or Read-for-exploration.
 
 ${SEARCH_POLICY_BODY}
 
 ### MCP workflow
 
 1. Call \`search\` with \`repo\` set to the project root (local path or https:// git URL).
-2. Use \`absolute_path\` (local repos) or \`file_path\` plus line from hits; call \`find_related\` to explore neighbors.
-3. Read files via \`absolute_path\` when a chunk lacks context or you are about to edit.
+2. If \`guidance.suggested_next\` is \`expand\`, 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.
 
 ### 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 .
 \`\`\`
 

package/src/mcp/server.ts

@@ -1,7 +1,15 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import type { ContentType } from "../types.ts";
-import { formatResults, localRepoRoot, resolveChunk } from "../utils.ts";
+import {
+  DEFAULT_MCP_TOP_K,
+  dedupeResultsByFile,
+  expandChunksAtLine,
+  formatExpandResults,
+  formatResults,
+  localRepoRoot,
+  resolveChunk,
+} from "../utils.ts";
 import { getIndexForRepo, type IndexCache, toolText } from "./index-cache.ts";
 
 const REPO_DESCRIPTION =
@@ -11,9 +19,10 @@ const REPO_DESCRIPTION =
 
 const SERVER_INSTRUCTIONS =
   "DO NOT use Grep, Glob, SemanticSearch, or Read to explore code when this server is available. " +
-  "Call `search` first for any question about how code works; call `find_related` on a hit to explore neighbors. " +
-  "Always pass the project root as `repo` (local path or https:// git URL). Never guess URLs. " +
-  "Local repos return `absolute_path` on each hit — use it for Read/edit. " +
+  "Workflow: (1) `search` once per question — check `guidance.sufficient` and `suggested_next` in the response. " +
+  "(2) If context looks cut off, call `expand` on the hit's file_path + line — do NOT re-search with paraphrases or 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 {
@@ -31,18 +40,31 @@ export function createMcpServer(cache: IndexCache): McpServer {
     "search",
     {
       description:
-        "DEFAULT code exploration tool. DO NOT use Grep, Glob, SemanticSearch, or Read instead. " +
-        "Search with natural language or a code query. Indexes `repo` on first call; later calls reuse the session cache.",
+        "DEFAULT code exploration tool. One call per question is usually enough — read `guidance` in the response. " +
+        "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.",
       inputSchema: {
         query: z.string().describe("Natural language or code query."),
         repo: z.string().describe(REPO_DESCRIPTION),
-        top_k: z.number().int().min(1).optional().describe("Number of results to return."),
+        top_k: z
+          .number()
+          .int()
+          .min(1)
+          .optional()
+          .describe(`Number of results (default ${DEFAULT_MCP_TOP_K}).`),
+        dedupe_by_file: z
+          .boolean()
+          .optional()
+          .describe("Keep only the best hit per file (default true)."),
       },
     },
-    async ({ query, repo, top_k: topK }) => {
+    async ({ query, repo, top_k: topK, dedupe_by_file: dedupeByFile }) => {
       try {
         const index = await getIndexForRepo(repo, cache);
-        const results = await index.search({ query, topK: topK ?? 5 });
+        let results = await index.search({ query, topK: topK ?? DEFAULT_MCP_TOP_K });
+        if (dedupeByFile !== false) {
+          results = dedupeResultsByFile(results);
+        }
         if (results.length === 0) {
           return toolText(JSON.stringify({ error: "No results found." }));
         }
@@ -54,12 +76,73 @@ 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.",
+      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."),
+        repo: z.string().describe(REPO_DESCRIPTION),
+        before: z
+          .number()
+          .int()
+          .min(0)
+          .optional()
+          .describe("Extra chunks before the anchor (default 1)."),
+        after: z
+          .number()
+          .int()
+          .min(0)
+          .optional()
+          .describe("Extra chunks after the anchor (default 1)."),
+      },
+    },
+    async ({ file_path: filePath, line, repo, before, after }) => {
+      try {
+        const index = await getIndexForRepo(repo, cache);
+        const repoRoot = localRepoRoot(repo);
+        const beforeCount = before ?? 1;
+        const afterCount = after ?? 1;
+        const { anchor, chunks: expanded } = expandChunksAtLine(
+          index.chunks,
+          filePath,
+          line,
+          repoRoot,
+          beforeCount,
+          afterCount,
+        );
+        if (!anchor) {
+          return toolText(
+            `No chunk found at ${filePath}:${line}. Make sure the file is indexed and the line number is within a known chunk.`,
+          );
+        }
+        return toolText(
+          JSON.stringify(
+            formatExpandResults(filePath, line, anchor, expanded, {
+              repoRoot,
+              before: beforeCount,
+              after: afterCount,
+            }),
+          ),
+        );
+      } catch (err) {
+        return toolText(err instanceof Error ? err.message : String(err));
+      }
+    },
+  );
+
   server.registerTool(
     "find_related",
     {
       description:
-        "Find code similar to a file:line from a prior `search` hit. " +
-        "Use instead of Grep chains or reading whole files to trace related code.",
+        "Find code similar to a file:line in OTHER parts of the codebase. " +
+        "For more context in the same file, use `expand` instead.",
       inputSchema: {
         file_path: z
           .string()
@@ -81,7 +164,7 @@ export function createMcpServer(cache: IndexCache): McpServer {
             `No chunk found at ${filePath}:${line}. Make sure the file is indexed and the line number is within a known chunk.`,
           );
         }
-        const results = await index.findRelated(chunk, topK ?? 5);
+        const results = await index.findRelated(chunk, topK ?? DEFAULT_MCP_TOP_K);
         if (results.length === 0) {
           return toolText(
             JSON.stringify({ error: `No related chunks found for ${filePath}:${line}.` }),

package/src/utils.ts

@@ -66,6 +66,30 @@ export function resolveChunk(
   return fallback;
 }
 
+export type SearchGuidance = {
+  sufficient: boolean;
+  reason: string;
+  suggested_next: "answer" | "expand" | "find_related" | "read_to_edit";
+  expand?: { file_path: string; line: number };
+};
+
+export type ExpandGuidance = {
+  sufficient: boolean;
+  reason: string;
+  suggested_next: "answer" | "search";
+};
+
+export type ExpandResults = {
+  file_path: string;
+  line: number;
+  chunk_count: number;
+  guidance: ExpandGuidance;
+  anchor: Record<string, unknown> | null;
+  chunks: Record<string, unknown>[];
+};
+
+export const DEFAULT_MCP_TOP_K = 3;
+
 function chunkToResponseDict(chunk: Chunk, repoRoot?: string | null): Record<string, unknown> {
   const dict = chunkToDict(chunk);
   if (!repoRoot) {
@@ -79,14 +103,145 @@ function chunkToResponseDict(chunk: Chunk, repoRoot?: string | null): Record<str
   };
 }
 
+/** Keep the best-scoring chunk per file (preserves score order). */
+export function dedupeResultsByFile(results: SearchResult[]): SearchResult[] {
+  const best = new Map<string, SearchResult>();
+  for (const result of results) {
+    const filePath = result.chunk.file_path;
+    const existing = best.get(filePath);
+    if (!existing || result.score > existing.score) {
+      best.set(filePath, result);
+    }
+  }
+  return [...best.values()].sort((a, b) => b.score - a.score);
+}
+
+export function chunksForFile(
+  chunks: Chunk[],
+  filePath: string,
+  repoRoot?: string | null,
+): Chunk[] {
+  const indexedPath = toIndexedFilePath(filePath, repoRoot);
+  return chunks
+    .filter((chunk) => chunk.file_path === indexedPath)
+    .sort((a, b) => a.start_line - b.start_line);
+}
+
+/** Adjacent indexed chunks in the same file around `line`. */
+export function expandChunksAtLine(
+  chunks: Chunk[],
+  filePath: string,
+  line: number,
+  repoRoot: string | null | undefined,
+  before: number,
+  after: number,
+): { anchor: Chunk | null; chunks: Chunk[] } {
+  const fileChunks = chunksForFile(chunks, filePath, repoRoot);
+  if (fileChunks.length === 0) {
+    return { anchor: null, chunks: [] };
+  }
+
+  const anchor = resolveChunk(chunks, filePath, line, repoRoot);
+  if (!anchor) {
+    return { anchor: null, chunks: [] };
+  }
+
+  const anchorIndex = fileChunks.findIndex(
+    (chunk) => chunk.start_line === anchor.start_line && chunk.end_line === anchor.end_line,
+  );
+  if (anchorIndex < 0) {
+    return { anchor, chunks: [anchor] };
+  }
+
+  const start = Math.max(0, anchorIndex - before);
+  const end = Math.min(fileChunks.length, anchorIndex + after + 1);
+  return { anchor, chunks: fileChunks.slice(start, end) };
+}
+
+export function assessSearchGuidance(query: string, results: SearchResult[]): SearchGuidance {
+  if (results.length === 0) {
+    return {
+      sufficient: false,
+      reason: "No results returned.",
+      suggested_next: "find_related",
+    };
+  }
+
+  const top = results[0];
+  if (!top) {
+    return {
+      sufficient: false,
+      reason: "No results returned.",
+      suggested_next: "find_related",
+    };
+  }
+
+  const topChunk = top.chunk;
+  const expandHint = { file_path: topChunk.file_path, line: topChunk.start_line };
+  const second = results[1];
+  const scoreRatio = second && second.score > 0 ? top.score / second.score : Number.POSITIVE_INFINITY;
+  const strongLead = results.length === 1 || scoreRatio >= 1.25;
+
+  const sameFileHits = results.filter((result) => result.chunk.file_path === topChunk.file_path).length;
+  const uniqueFiles = new Set(results.map((result) => result.chunk.file_path)).size;
+  const lineSpan = topChunk.end_line - topChunk.start_line + 1;
+  const narrowQuery = /\b(why|how|what|when|where|does|bug|error|fail)\b/i.test(query);
+
+  if (sameFileHits > 1 && lineSpan < 40) {
+    return {
+      sufficient: false,
+      reason: `${sameFileHits} hits in ${topChunk.file_path}; slices may be incomplete.`,
+      suggested_next: "expand",
+      expand: expandHint,
+    };
+  }
+
+  if (lineSpan < 12 && sameFileHits >= 1) {
+    return {
+      sufficient: false,
+      reason: "Top hit is a short slice; more context may be in adjacent chunks.",
+      suggested_next: "expand",
+      expand: expandHint,
+    };
+  }
+
+  if (uniqueFiles > 2 && !strongLead) {
+    return {
+      sufficient: false,
+      reason: "Results span several files; pick the best hit or use find_related to trace neighbors.",
+      suggested_next: "find_related",
+      expand: expandHint,
+    };
+  }
+
+  if (strongLead && (narrowQuery || lineSpan >= 15)) {
+    return {
+      sufficient: true,
+      reason:
+        results.length === 1
+          ? "Single focused hit — answer from this chunk unless you are editing."
+          : `Top hit leads (${scoreRatio === Number.POSITIVE_INFINITY ? "only result" : `${scoreRatio.toFixed(1)}x`}).`,
+      suggested_next: "answer",
+    };
+  }
+
+  return {
+    sufficient: true,
+    reason: "Top hit is likely enough; call expand if the chunk looks cut off.",
+    suggested_next: "answer",
+    expand: expandHint,
+  };
+}
+
 export function formatResults(
   query: string,
   results: SearchResult[],
   options?: { repoRoot?: string | null },
-): { query: string; results: Record<string, unknown>[] } {
+): { query: string; guidance: SearchGuidance; results: Record<string, unknown>[] } {
   const repoRoot = options?.repoRoot ?? null;
   return {
     query,
+    guidance: assessSearchGuidance(query, results),
     results: results.map((result) => ({
       chunk: chunkToResponseDict(result.chunk, repoRoot),
       score: result.score,
@@ -94,6 +249,36 @@ export function formatResults(
   };
 }
 
+export function formatExpandResults(
+  filePath: string,
+  line: number,
+  anchor: Chunk | null,
+  expanded: Chunk[],
+  options?: { repoRoot?: string | null; before?: number; after?: number },
+): ExpandResults {
+  const repoRoot = options?.repoRoot ?? null;
+  const indexedPath = toIndexedFilePath(filePath, repoRoot) || filePath;
+  const suggestedNext: ExpandGuidance["suggested_next"] = expanded.length > 0 ? "answer" : "search";
+
+  return {
+    file_path: indexedPath,
+    line,
+    chunk_count: expanded.length,
+    guidance: {
+      sufficient: expanded.length > 1,
+      reason:
+        expanded.length === 0
+          ? "No chunks at this location."
+          : expanded.length === 1
+            ? "Single chunk at location; call expand with higher before/after if still truncated."
+            : `Returned ${expanded.length} adjacent chunks in ${indexedPath}.`,
+      suggested_next: suggestedNext,
+    },
+    anchor: anchor ? chunkToResponseDict(anchor, repoRoot) : null,
+    chunks: expanded.map((chunk) => chunkToResponseDict(chunk, repoRoot)),
+  };
+}
+
 export function resolveContent(raw: string[]): ContentType[] {
   if (raw.includes("all")) {
     return ["code", "docs", "config"];