@takara-ai/miru-code 0.4.11 → 0.4.12

package/package.json

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

package/src/agents/claude.md

@@ -16,7 +16,7 @@ When Miru MCP is available, use MCP `search`, `expand`, and `find_related` — n
 
 ### MCP workflow
 
-1. Call `search` with `repo` set to the project root; follow `guidance` in the response.
+1. Call `search` with `repo` set to the project root.
 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.

package/src/agents/copilot.md

@@ -7,7 +7,7 @@ When Miru MCP is available, use `search`, `expand`, and `find_related` instead o
 
 | Task | Tool |
 |------|------|
-| How/where/what handles X? | Miru `search` (once; follow `guidance`) |
+| How/where/what handles X? | Miru `search` (once) |
 | Same file, more context | Miru `expand` |
 | Similar implementations | Miru `find_related` |
 | Exact literal confirmation | grep_search |

package/src/agents/cursor.md

@@ -5,11 +5,11 @@ description: Code search via Miru MCP. Use search, expand, and find_related. DO
 
 Use Miru MCP tools when connected:
 
-- `search` — one call per question; always pass project root as `repo`; read `guidance` in the response
+- `search` — one call per question; always pass project root as `repo`
 - `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 re-search with paraphrases when `guidance.sufficient` is true. Do not read whole files for exploration.
+Do not re-search with paraphrases after a good first hit. Do not read whole files for exploration.
 
 | Task | Tool |
 |------|------|

package/src/agents/gemini.md

@@ -7,12 +7,12 @@ When Miru MCP is available, use `search`, `expand`, and `find_related` instead o
 
 | Task | Tool |
 |------|------|
-| How/where/what handles X? | Miru `search` (once; follow `guidance`) |
+| How/where/what handles X? | Miru `search` (once) |
 | 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. Do not re-search when `guidance.sufficient` is true.
+Pass project root as `repo` on every MCP call. Do not re-search with paraphrases after a good first hit.
 
 CLI fallback: `miru search "query" .` or `bunx @takara-ai/miru-code search "query" .`

package/src/agents/kiro.md

@@ -5,6 +5,6 @@ description: Code search via Miru MCP. Use search, expand, and find_related for
 
 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`. Follow `guidance` in search responses. Use `expand` for truncated hits in the same file. Use Grep only for exact literal confirmation.
+Pass project root as `repo`. 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

@@ -6,6 +6,6 @@ mode: subagent
 
 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. Follow `guidance` in search responses.
+Pass project root as `repo` on every MCP call.
 
 CLI fallback: `miru search "query" .`

package/src/installer/search-policy.ts

@@ -12,12 +12,12 @@ export const SEARCH_POLICY_TABLE = `| Task | Use | Not |
 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:
-- \`search\` — one call per question; pass project root as \`repo\`; read \`guidance.sufficient\` and \`suggested_next\` in the response
+- \`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
 
 Stop rules:
-- If \`guidance.sufficient\` is true, answer — do not re-search with paraphrases
+- 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
 
@@ -54,7 +54,7 @@ alwaysApply: true
 
 ${SEARCH_POLICY_BODY}
 
-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.`;
+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.`;
 
 export const SUBAGENT_BODY = `When Miru MCP is available, use MCP \`search\`, \`expand\`, and \`find_related\` — not Grep, Glob, SemanticSearch, or Read-for-exploration.
 
@@ -63,7 +63,7 @@ ${SEARCH_POLICY_BODY}
 ### MCP workflow
 
 1. Call \`search\` with \`repo\` set to the project root (local path or https:// git URL).
-2. If \`guidance.suggested_next\` is \`expand\`, call \`expand\` with the hit's \`file_path\` and \`line\`.
+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.
 

package/src/mcp/server.ts

@@ -2,12 +2,14 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import type { ContentType } from "../types.ts";
 import {
+  clampMcpTopK,
   DEFAULT_MCP_TOP_K,
   dedupeResultsByFile,
   expandChunksAtLine,
   formatExpandResults,
   formatResults,
   localRepoRoot,
+  MAX_MCP_TOP_K,
   resolveChunk,
 } from "../utils.ts";
 import { getIndexForRepo, type IndexCache, toolText } from "./index-cache.ts";
@@ -19,8 +21,8 @@ const REPO_DESCRIPTION =
 
 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 — 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. " +
+  "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.";
@@ -40,7 +42,7 @@ export function createMcpServer(cache: IndexCache): McpServer {
     "search",
     {
       description:
-        "DEFAULT code exploration tool. One call per question is usually enough — read `guidance` in the response. " +
+        "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.",
       inputSchema: {
@@ -50,8 +52,9 @@ export function createMcpServer(cache: IndexCache): McpServer {
           .number()
           .int()
           .min(1)
+          .max(MAX_MCP_TOP_K)
           .optional()
-          .describe(`Number of results (default ${DEFAULT_MCP_TOP_K}).`),
+          .describe(`Number of results (default ${DEFAULT_MCP_TOP_K}, max ${MAX_MCP_TOP_K}).`),
         dedupe_by_file: z
           .boolean()
           .optional()
@@ -61,7 +64,7 @@ export function createMcpServer(cache: IndexCache): McpServer {
     async ({ query, repo, top_k: topK, dedupe_by_file: dedupeByFile }) => {
       try {
         const index = await getIndexForRepo(repo, cache);
-        let results = await index.search({ query, topK: topK ?? DEFAULT_MCP_TOP_K });
+        let results = await index.search({ query, topK: clampMcpTopK(topK) });
         if (dedupeByFile !== false) {
           results = dedupeResultsByFile(results);
         }
@@ -151,7 +154,13 @@ export function createMcpServer(cache: IndexCache): McpServer {
           ),
         line: z.number().int().describe("Line number (1-indexed)."),
         repo: z.string().describe(REPO_DESCRIPTION),
-        top_k: z.number().int().min(1).optional().describe("Number of similar chunks to return."),
+        top_k: z
+          .number()
+          .int()
+          .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}).`),
       },
     },
     async ({ file_path: filePath, line, repo, top_k: topK }) => {
@@ -164,7 +173,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 ?? DEFAULT_MCP_TOP_K);
+        const results = await index.findRelated(chunk, clampMcpTopK(topK));
         if (results.length === 0) {
           return toolText(
             JSON.stringify({ error: `No related chunks found for ${filePath}:${line}.` }),

package/src/utils.ts

@@ -66,29 +66,25 @@ 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;
+export const MAX_MCP_TOP_K = 10;
+
+/** Clamp MCP top_k to a sane range; omit for the default. */
+export function clampMcpTopK(topK?: number): number {
+  const value = topK ?? DEFAULT_MCP_TOP_K;
+  if (!Number.isFinite(value) || value < 1) {
+    return DEFAULT_MCP_TOP_K;
+  }
+  return Math.min(Math.floor(value), MAX_MCP_TOP_K);
+}
 
 function chunkToResponseDict(chunk: Chunk, repoRoot?: string | null): Record<string, unknown> {
   const dict = chunkToDict(chunk);
@@ -158,90 +154,14 @@ export function expandChunksAtLine(
   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; guidance: SearchGuidance; results: Record<string, unknown>[] } {
+): { query: string; 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,
@@ -258,22 +178,11 @@ export function formatExpandResults(
 ): 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)),
   };