@takara-ai/miru-code 0.4.11 → 0.5.0

package/src/mcp/server.ts

@@ -2,14 +2,22 @@ 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 {
+  MCP_EXPAND_TOOL_DESCRIPTION,
+  MCP_FIND_RELATED_TOOL_DESCRIPTION,
+  MCP_SEARCH_TOOL_DESCRIPTION,
+  MCP_SERVER_INSTRUCTIONS,
+} from "../installer/search-policy.ts";
 import { getIndexForRepo, type IndexCache, toolText } from "./index-cache.ts";
 
 const REPO_DESCRIPTION =
@@ -17,14 +25,6 @@ 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 — 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 {
   const server = new McpServer(
     {
@@ -32,7 +32,7 @@ export function createMcpServer(cache: IndexCache): McpServer {
       version: "0.1.0",
     },
     {
-      instructions: SERVER_INSTRUCTIONS,
+      instructions: MCP_SERVER_INSTRUCTIONS,
     },
   );
 
@@ -40,9 +40,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. " +
-        "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.",
+        `${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),
@@ -50,8 +48,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 +60,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);
         }
@@ -69,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));
       }
@@ -79,15 +78,15 @@ 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()
@@ -140,18 +139,25 @@ 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("Line number (1-indexed)."),
+        line: z
+          .number()
+          .int()
+          .describe("Line from the hit: `anchor_line` when truncated, otherwise `start_line` (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 +170,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}.` }),
@@ -172,7 +178,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) {

package/src/ranking/boosting.ts

@@ -2,6 +2,12 @@ import { basename, dirname } from "node:path";
 import { splitIdentifier } from "../tokens.ts";
 import type { Chunk } from "../types.ts";
 import { chunkKey } from "../types.ts";
+import { searchImprovementsEnabled } from "./features.ts";
+import {
+  boostExactStemMatches,
+  boostLocationSignals,
+  penalizeInstallerForLocation,
+} from "./location.ts";
 
 const SYMBOL_QUERY_RE =
   /^(?:(?:[A-Za-z_][A-Za-z0-9_]*(?:(?:::|\\|->|\.)[A-Za-z_][A-Za-z0-9_]*)+)|_(?:[A-Za-z0-9_]*)|(?:[A-Za-z][A-Za-z0-9]*[A-Z_][A-Za-z0-9_]*)|(?:[A-Z][A-Za-z0-9]*))$/;
@@ -165,6 +171,11 @@ export function applyQueryBoost(
   } else {
     boostStemMatches(combinedScores, query, maxScore, chunksByKey);
     boostEmbeddedSymbols(combinedScores, query, maxScore, allChunks, chunksByKey);
+    if (searchImprovementsEnabled()) {
+      boostExactStemMatches(combinedScores, query, maxScore, chunksByKey);
+      boostLocationSignals(combinedScores, query, maxScore, allChunks, chunksByKey);
+      penalizeInstallerForLocation(combinedScores, query, chunksByKey);
+    }
   }
   return combinedScores;
 }

package/src/ranking/features.ts

@@ -0,0 +1,11 @@
+/** Toggle search ranking/indexing improvements (A/B via MIRU_SEARCH_V2=0|1). */
+export function searchImprovementsEnabled(): boolean {
+  const value = process.env.MIRU_SEARCH_V2;
+  if (value === "0" || value === "false") {
+    return false;
+  }
+  if (value === "1" || value === "true") {
+    return true;
+  }
+  return true;
+}

package/src/ranking/location.ts

@@ -0,0 +1,241 @@
+import { basename } from "node:path";
+import type { Chunk } from "../types.ts";
+import { chunkKey } from "../types.ts";
+
+const LOCATION_QUERY_RE =
+  /\b(where(?:'s| is)?|entry\s*point|bootstrap|starts?|live[s]?|located|defined|wiring)\b/i;
+
+const ENTRY_POINT_QUERY_RE = /\b(entry\s*point|bootstrap|starts?|wiring|command\s*line)\b/i;
+
+const INTEGRATION_QUERY_RE = /\b(install|uninstall|hook|agent|configure|setup)\b/i;
+
+const INSTALLER_PATH_RE = /(?:^|\/)installer(?:\/|$)/;
+
+const ENTRY_POINT_CONTENT_RE =
+  /#!\/usr\/bin|(?:^|\n)\s*(?:async\s+)?function\s+main\s*\(|(?:^|\n)\s*if\s*\(\s*require\.main\s*===\s*module/;
+
+const PACKAGE_ENTRY_RE = /^\[package entry\]/;
+
+const LOCATION_BOOST_MULTIPLIER = 2.5;
+const INSTALLER_LOCATION_PENALTY = 0.35;
+
+/** Too common as filenames to get exact-stem boosts from incidental query tokens. */
+const IMPLEMENTATION_HINTS = new Set(
+  [
+    "command",
+    "handler",
+    "router",
+    "routing",
+    "middleware",
+    "model",
+    "channel",
+    "request",
+    "response",
+    "dispatch",
+    "pipeline",
+  ].map((w) => w.toLowerCase()),
+);
+
+const GENERIC_STEM_DENY = new Set(
+  [
+    "route",
+    "routes",
+    "router",
+    "routing",
+    "handler",
+    "middleware",
+    "channel",
+    "model",
+    "models",
+    "request",
+    "response",
+    "utils",
+    "util",
+    "server",
+    "client",
+    "application",
+    "dispatch",
+    "core",
+    "lib",
+    "main",
+    "mod",
+    "test",
+    "tests",
+    "schema",
+    "config",
+    "helper",
+    "helpers",
+    "engine",
+    "pipeline",
+    "plug",
+    "plugs",
+    "command",
+    "commands",
+    "index",
+  ].map((w) => w.toLowerCase()),
+);
+
+export function isLocationQuery(query: string): boolean {
+  return LOCATION_QUERY_RE.test(query);
+}
+
+export function isEntryPointQuery(query: string): boolean {
+  return ENTRY_POINT_QUERY_RE.test(query);
+}
+
+function fileStemMatchesQuery(filePath: string, query: string): boolean {
+  const stem = basename(filePath)
+    .replace(/\.[^.]+$/, "")
+    .toLowerCase();
+  const rawTokens = (query.match(/[a-zA-Z_][a-zA-Z0-9_-]*/g) ?? []).map((t) => t.toLowerCase());
+
+  if (rawTokens.includes(stem)) {
+    return true;
+  }
+
+  for (const token of rawTokens) {
+    if (token.includes("-") && token.split("-").includes(stem)) {
+      return false;
+    }
+  }
+
+  const stemNorm = stem.replace(/[-_]/g, "");
+  return rawTokens.some((t) => t.replace(/[-_]/g, "") === stemNorm);
+}
+
+export function isIntegrationQuery(query: string): boolean {
+  return INTEGRATION_QUERY_RE.test(query);
+}
+
+function chunkLooksLikeEntryPoint(chunk: Chunk): boolean {
+  if (PACKAGE_ENTRY_RE.test(chunk.content)) {
+    return true;
+  }
+  return ENTRY_POINT_CONTENT_RE.test(chunk.content);
+}
+
+export function boostLocationSignals(
+  boosted: Map<string, number>,
+  query: string,
+  maxScore: number,
+  allChunks: Chunk[],
+  chunksByKey: Map<string, Chunk>,
+): void {
+  if (!isLocationQuery(query)) {
+    return;
+  }
+
+  const entryPointQuery = isEntryPointQuery(query);
+  const packageBoost = maxScore * (entryPointQuery ? LOCATION_BOOST_MULTIPLIER : 0.75);
+  const codeBoost = maxScore * LOCATION_BOOST_MULTIPLIER;
+
+  for (const chunk of allChunks) {
+    if (!chunkLooksLikeEntryPoint(chunk)) {
+      continue;
+    }
+
+    const isPackageEntry = PACKAGE_ENTRY_RE.test(chunk.content);
+    if (isPackageEntry) {
+      const key = chunkKey(chunk);
+      boosted.set(key, (boosted.get(key) ?? 0) + packageBoost);
+      chunksByKey.set(key, chunk);
+      continue;
+    }
+
+    if (!entryPointQuery && !fileStemMatchesQuery(chunk.file_path, query)) {
+      continue;
+    }
+
+    const key = chunkKey(chunk);
+    boosted.set(key, (boosted.get(key) ?? 0) + codeBoost);
+    chunksByKey.set(key, chunk);
+  }
+}
+
+export function penalizeInstallerForLocation(
+  boosted: Map<string, number>,
+  query: string,
+  chunksByKey: Map<string, Chunk>,
+): void {
+  if (!isLocationQuery(query) || isIntegrationQuery(query)) {
+    return;
+  }
+
+  for (const [key, score] of boosted) {
+    const chunk = chunksByKey.get(key);
+    if (!chunk) {
+      continue;
+    }
+    if (INSTALLER_PATH_RE.test(chunk.file_path.replace(/\\/g, "/"))) {
+      boosted.set(key, score * INSTALLER_LOCATION_PENALTY);
+    }
+  }
+}
+
+function hasSpecificImplementationTarget(
+  query: string,
+  chunksByKey: Map<string, Chunk>,
+): boolean {
+  const lowered = query.toLowerCase();
+  for (const hint of IMPLEMENTATION_HINTS) {
+    if (!lowered.includes(hint)) {
+      continue;
+    }
+    for (const chunk of chunksByKey.values()) {
+      const stem = basename(chunk.file_path)
+        .replace(/\.[^.]+$/, "")
+        .toLowerCase();
+      if (stem === hint) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+export function boostExactStemMatches(
+  boosted: Map<string, number>,
+  query: string,
+  maxScore: number,
+  chunksByKey: Map<string, Chunk>,
+): void {
+  const keywords = new Set(
+    (query.match(/[a-zA-Z_][a-zA-Z0-9_-]*/g) ?? [])
+      .filter((w) => w.length > 2)
+      .map((w) => w.toLowerCase()),
+  );
+  if (keywords.size === 0) {
+    return;
+  }
+
+  const boost = maxScore * 0.75;
+  const preferImplementation = hasSpecificImplementationTarget(query, chunksByKey);
+
+  for (const key of [...boosted.keys()]) {
+    const chunk = chunksByKey.get(key);
+    if (!chunk) {
+      continue;
+    }
+    const stem = basename(chunk.file_path)
+      .replace(/\.[^.]+$/, "")
+      .toLowerCase();
+    const stemNorm = stem.replace(/[-_]/g, "");
+    for (const keyword of keywords) {
+      if (GENERIC_STEM_DENY.has(keyword)) {
+        continue;
+      }
+      if (preferImplementation && stem === keyword && !IMPLEMENTATION_HINTS.has(stem)) {
+        continue;
+      }
+      const keywordNorm = keyword.replace(/[-_]/g, "");
+      if (stem === keyword || stemNorm === keywordNorm) {
+        boosted.set(key, (boosted.get(key) ?? 0) + boost);
+        break;
+      }
+      const parts = keyword.split("-").filter((p) => p.length > 2);
+      if (parts.length > 1 && parts.some((p) => p === stem)) {
+        continue;
+      }
+    }
+  }
+}

package/src/search.ts

@@ -4,6 +4,8 @@ import type { SemanticIndex } from "./index/semantic-index.ts";
 import { selectorToMask } from "./index/sparse.ts";
 import { selectTopKScoreIndices } from "./index/topk.ts";
 import { applyQueryBoost, boostMultiChunkFiles } from "./ranking/boosting.ts";
+import { searchImprovementsEnabled } from "./ranking/features.ts";
+import { isLocationQuery } from "./ranking/location.ts";
 import { rerankTopk } from "./ranking/penalties.ts";
 import { resolveAlpha } from "./ranking/weighting.ts";
 import { tokenize } from "./tokens.ts";
@@ -93,7 +95,8 @@ export async function hybridSearch(options: {
   } = options;
 
   const alphaWeight = resolveAlpha(query, alpha);
-  const candidateCount = topK * 5;
+  const candidateCount =
+    searchImprovementsEnabled() && isLocationQuery(query) ? topK * 10 : topK * 5;
   const chunksByKey = new Map(chunks.map((c) => [chunkKey(c), c]));
 
   const queryVecPromise = embeddings.embedQuery(query);

package/src/snippet.ts

@@ -0,0 +1,154 @@
+import { envOptionalInt } from "./env.ts";
+import { tokenize } from "./tokens.ts";
+import type { Chunk, SearchResult } from "./types.ts";
+
+const SNIPPET_STOPWORDS = new Set(
+  "a an and are as at be by do does for from has have how if in is it not of on or the to was what when where which who why with".split(
+    " ",
+  ),
+);
+
+export interface SnippetMeta {
+  truncated: boolean;
+  anchor_line: number;
+  full_start_line: number;
+  full_end_line: number;
+}
+
+export interface SnippetResult {
+  chunk: Chunk;
+  meta: SnippetMeta;
+}
+
+export function resolveSnippetLines(): number {
+  return envOptionalInt(["MIRU_SNIPPET_LINES"], 3) ?? 15;
+}
+
+export function searchSnippetsEnabled(): boolean {
+  const value = process.env.MIRU_SEARCH_SNIPPETS;
+  if (value === "0" || value === "false") {
+    return false;
+  }
+  if (value === "1" || value === "true") {
+    return true;
+  }
+  return true;
+}
+
+function queryMatchTerms(query: string): Set<string> {
+  const terms = new Set<string>();
+  for (const tok of tokenize(query)) {
+    if (tok.length >= 3 && !SNIPPET_STOPWORDS.has(tok)) {
+      terms.add(tok);
+    }
+  }
+  for (const word of query.match(/[a-zA-Z_][a-zA-Z0-9_-]*/g) ?? []) {
+    const lower = word.toLowerCase();
+    if (lower.length >= 3 && !SNIPPET_STOPWORDS.has(lower)) {
+      terms.add(lower);
+    }
+  }
+  return terms;
+}
+
+function scoreLine(line: string, terms: Set<string>): number {
+  const lower = line.toLowerCase();
+  let score = 0;
+  for (const term of terms) {
+    if (lower.includes(term)) {
+      score++;
+    }
+  }
+  return score;
+}
+
+/** Pick the 0-based line index inside `content` that best matches the query. */
+export function anchorLineOffset(content: string, query: string): number {
+  const lines = content.split("\n");
+  if (lines.length === 0) {
+    return 0;
+  }
+
+  const terms = queryMatchTerms(query);
+  let bestIndex = Math.floor(lines.length / 2);
+  let bestScore = -1;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const score = scoreLine(line, terms);
+    if (score > bestScore) {
+      bestScore = score;
+      bestIndex = i;
+    }
+  }
+
+  return bestIndex;
+}
+
+export function trimChunkToSnippet(
+  chunk: Chunk,
+  query: string,
+  linesEachSide = resolveSnippetLines(),
+): SnippetResult {
+  const lines = chunk.content.split("\n");
+  if (lines.length === 0) {
+    return {
+      chunk,
+      meta: {
+        truncated: false,
+        anchor_line: chunk.start_line,
+        full_start_line: chunk.start_line,
+        full_end_line: chunk.end_line,
+      },
+    };
+  }
+
+  const anchorOffset = anchorLineOffset(chunk.content, query);
+  const startOffset = Math.max(0, anchorOffset - linesEachSide);
+  const endOffset = Math.min(lines.length, anchorOffset + linesEachSide + 1);
+  const truncated = startOffset > 0 || endOffset < lines.length;
+
+  if (!truncated) {
+    return {
+      chunk,
+      meta: {
+        truncated: false,
+        anchor_line: chunk.start_line + anchorOffset,
+        full_start_line: chunk.start_line,
+        full_end_line: chunk.end_line,
+      },
+    };
+  }
+
+  const snippetContent = lines.slice(startOffset, endOffset).join("\n");
+  return {
+    chunk: {
+      ...chunk,
+      content: snippetContent,
+      start_line: chunk.start_line + startOffset,
+      end_line: chunk.start_line + endOffset - 1,
+    },
+    meta: {
+      truncated: true,
+      anchor_line: chunk.start_line + anchorOffset,
+      full_start_line: chunk.start_line,
+      full_end_line: chunk.end_line,
+    },
+  };
+}
+
+export function applySnippetsToResults(
+  results: SearchResult[],
+  query: string,
+  linesEachSide?: number,
+): Array<{ result: SearchResult; meta: SnippetMeta }> {
+  const radius = linesEachSide ?? resolveSnippetLines();
+  return results.map((result) => {
+    const { chunk, meta } = trimChunkToSnippet(result.chunk, query, radius);
+    return { result: { chunk, score: result.score }, meta };
+  });
+}
+
+export function estimateResultTokens(results: SearchResult[]): number {
+  return results.reduce((sum, r) => sum + Math.floor(r.chunk.content.length / 4), 0);
+}