@takara-ai/miru-code 1.8.2 → 1.9.0

package/README.md

@@ -38,6 +38,23 @@ Restart Claude Code (or reload plugins) when prompted. Update: `/plugin marketpl
 
 **Any other IDE, or if marketplace install isn't available:** use the CLI install below.
 
+### What you get from a plugin install vs the CLI
+
+Plugin installs don't carry full CLI parity — what each one gives you depends on the IDE's own plugin capabilities, not just Miru's packaging:
+
+| | Claude Code | Codex | Cursor |
+|---|---|---|---|
+| MCP tools (`search`, `locate`, `expand`, `find_related`) | ✅ | ✅ | ❌ *(plugin ships skills + rules only — no MCP entry yet)* |
+| `miru` / Caveman / STE skills | ✅ | ✅ | ✅ |
+| Dedicated sub-agent (`miru:miru-code`) | ✅ | — | — |
+| Benchmark mode toggle (`/plugin configure`) | ✅ | — | — |
+| Search hooks | — | — | — |
+| Credentials | own plugin-scoped dir | own plugin-scoped dir | n/a |
+
+`—` means the IDE's plugin schema has no equivalent mechanism to port these to (not a packaging gap we can close): Codex's and Cursor's plugin manifests have no `agents` or `userConfig` fields, so the dedicated sub-agent and the benchmark toggle are Claude-Code-only. Search hooks aren't shipped to any plugin — they're slated for removal from Miru entirely (tracked internally), so not worth packaging.
+
+**Credentials are plugin-scoped, not shared with your CLI install.** Claude Code and Codex plugins each store auth in their own IDE-managed data directory (survives plugin updates, removed on uninstall). This means `miru setup` done via the CLI does **not** carry over to a plugin install, or vice versa — each authenticates independently on first use (interactive device-code login bootstraps automatically). If you use both the CLI and a plugin, you'll sign in twice.
+
 ## Install (CLI)
 
 ```bash
@@ -105,10 +122,8 @@ miru uninstall   # remove miru config
 
 ### Plugin packaging
 
-This repo now includes plugin packaging for:
-
-- Codex: `.codex-plugin/plugin.json` and `.agents/plugins/marketplace.json`
-- Claude Code: `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json`
+- Codex: `.codex-plugin/plugin.json`, `.agents/plugins/marketplace.json`, shares the root `mcp.json`
+- Claude Code: `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, its own `.claude-plugin/mcp.json` (needed for the `userConfig` benchmark toggle — see [What you get from a plugin install vs the CLI](#what-you-get-from-a-plugin-install-vs-the-cli))
 - Cursor: `plugin.json` and `.cursor/rules/miru-code-search.mdc`
 
 Current limitation:
@@ -285,7 +300,7 @@ bun add @takara-ai/miru-code
 import { MiruIndex } from "@takara-ai/miru-code";
 
 const index = await MiruIndex.fromPath("./src");
-const results = await index.search({ query: "BM25 tokenize", topK: 10 });
+const results = await index.search({ query: "BM25 tokenize" });
 ```
 
 ## Environment
@@ -353,7 +368,8 @@ Override with `MIRU_BENCHMARK_HISTORY_PATH`. Append-only JSONL of compact token
 | ---------------- | -------- | --------------------------------------- |
 | `query`          | yes      | Natural language or code query          |
 | `repo`           | yes      | Project root or git URL                 |
-| `top_k`          | no       | Results to return (default 3, max 10)   |
+| `include`        | no       | Gitignore-style glob patterns; only matching files are searched (same as `locate.include`) |
+| `exclude`        | no       | Gitignore-style glob patterns; matching files are skipped (same as `locate.exclude`) |
 | `dedupe_by_file` | no       | Keep best hit per file (default `true`) |
 
 
@@ -364,6 +380,8 @@ Override with `MIRU_BENCHMARK_HISTORY_PATH`. Append-only JSONL of compact token
 | ------------- | -------- | ----------------------------------------------------------------------------------- |
 | `literal`     | yes      | Exact substring to find                                                             |
 | `repo`        | yes      | Project root or git URL                                                             |
+| `include`     | no       | Gitignore-style glob patterns; only matching files are searched                    |
+| `exclude`     | no       | Gitignore-style glob patterns; matching files are skipped                          |
 | `mode`        | no       | `count` · `locations` · `lines` (default). Prefer `count`/`locations` when possible |
 | `limit`       | no       | Cap returned hits. Omit to return all matches                                       |
 | `ignore_case` | no       | Case-insensitive match (default `false`)                                            |
@@ -388,7 +406,6 @@ Override with `MIRU_BENCHMARK_HISTORY_PATH`. Append-only JSONL of compact token
 | `file_path`   | yes      | From a search hit                            |
 | `anchor_line` | yes      | From the search hit                          |
 | `repo`        | yes      | Same repo as the search                      |
-| `top_k`       | no       | Related chunks to return (default 3, max 10) |
 
 
 `**read_benchmark**` *(benchmark mode only)*

package/package.json

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

package/src/cli.ts

@@ -56,6 +56,7 @@ import {
   resolveChunk,
   resolveContent,
   resolveSearchPath,
+  SEARCH_RESULT_COUNT,
 } from "./utils.ts";
 import { maybeNotifyUpdate, miruVersion } from "./version.ts";
 
@@ -132,25 +133,6 @@ function parseContentArgv(argv: string[]): { content: ContentType[]; rest: strin
   return { content: resolveContent(content), rest };
 }
 
-function parseTopK(argv: string[]): { topK: number; rest: string[] } {
-  const rest: string[] = [];
-  let topK = 5;
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === "-k" || arg === "--top-k") {
-      const raw = argv[++i];
-      if (raw) {
-        topK = Number(raw);
-      }
-      continue;
-    }
-    if (arg !== undefined) {
-      rest.push(arg);
-    }
-  }
-  return { topK: Number.isFinite(topK) && topK >= 1 ? Math.floor(topK) : 5, rest };
-}
-
 function emitSearchOutput(
   query: string,
   results: SearchResult[],
@@ -177,7 +159,6 @@ function emitSearchOutput(
 async function runSearch(
   path: string,
   query: string,
-  topK: number,
   content: ContentType[],
   jsonFlag: boolean,
 ): Promise<void> {
@@ -186,7 +167,7 @@ async function runSearch(
   const index = await withSpinner("Indexing and searching", async () => {
     const built = await MiruIndex.fromSource(path, content);
     await built.saveToCache(path);
-    const results = await built.search({ query, topK });
+    const results = await built.search({ query, topK: SEARCH_RESULT_COUNT });
     return { index: built, results };
   });
 
@@ -245,7 +226,6 @@ async function runFindRelated(
   path: string,
   filePath: string,
   line: number,
-  topK: number,
   content: ContentType[],
   jsonFlag: boolean,
 ): Promise<void> {
@@ -257,7 +237,7 @@ async function runFindRelated(
     if (!chunk) {
       throw new RelatedChunkNotFoundError(filePath, line);
     }
-    const hits = await built.findRelated(chunk, topK);
+    const hits = await built.findRelated(chunk, SEARCH_RESULT_COUNT);
     await built.saveToCache(path);
     return {
       results: hits,
@@ -552,21 +532,28 @@ async function runCli(argv: string[]): Promise<void> {
 
   const { present: jsonFlag, rest: jsonRest } = parseFlagArgv(rest, "--json");
   const { content, rest: contentRest } = parseContentArgv(jsonRest);
-  const { topK, rest: sizedRest } = parseTopK(contentRest);
+
+  if (
+    (command === "search" || command === "find-related") &&
+    contentRest.some((arg) => arg === "-k" || arg === "--top-k")
+  ) {
+    fail("The -k/--top-k option has been removed; Miru returns a fixed number of results.");
+    process.exit(1);
+  }
 
   if (command === "search") {
-    const query = sizedRest[0];
+    const query = contentRest[0];
     if (!query) {
       printCommandHelp("search");
       process.exit(1);
     }
-    const path = resolveSearchPath(sizedRest[1] ?? process.cwd());
-    await runSearch(path, query, topK, content, jsonFlag);
+    const path = resolveSearchPath(contentRest[1] ?? process.cwd());
+    await runSearch(path, query, content, jsonFlag);
     return;
   }
 
   if (command === "locate") {
-    const literal = sizedRest[0];
+    const literal = contentRest[0];
     if (!literal) {
       printCommandHelp("locate");
       process.exit(1);
@@ -585,10 +572,10 @@ async function runCli(argv: string[]): Promise<void> {
       }
       return Math.floor(n);
     };
-    for (let i = 1; i < sizedRest.length; i++) {
-      const arg = sizedRest[i];
-      if (arg === "--mode" && sizedRest[i + 1]) {
-        const value = sizedRest[++i];
+    for (let i = 1; i < contentRest.length; i++) {
+      const arg = contentRest[i];
+      if (arg === "--mode" && contentRest[i + 1]) {
+        const value = contentRest[++i];
         if (value !== "count" && value !== "locations" && value !== "lines") {
           fail(`Unknown locate mode "${value}". Use count, locations, or lines.`);
           process.exit(1);
@@ -596,8 +583,8 @@ async function runCli(argv: string[]): Promise<void> {
         options.mode = value as LiteralMode;
         continue;
       }
-      if (arg === "--limit" && sizedRest[i + 1]) {
-        options.limit = positiveInt("--limit", sizedRest[++i], 1);
+      if (arg === "--limit" && contentRest[i + 1]) {
+        options.limit = positiveInt("--limit", contentRest[++i], 1);
         continue;
       }
       if (arg === "--ignore-case") {
@@ -608,16 +595,16 @@ async function runCli(argv: string[]): Promise<void> {
         options.match_variants = true;
         continue;
       }
-      if (arg === "--include" && sizedRest[i + 1]) {
-        include.push(sizedRest[++i] as string);
+      if (arg === "--include" && contentRest[i + 1]) {
+        include.push(contentRest[++i] as string);
         continue;
       }
-      if (arg === "--exclude" && sizedRest[i + 1]) {
-        exclude.push(sizedRest[++i] as string);
+      if (arg === "--exclude" && contentRest[i + 1]) {
+        exclude.push(contentRest[++i] as string);
         continue;
       }
-      if (arg === "--context" && sizedRest[i + 1]) {
-        options.context_lines = positiveInt("--context", sizedRest[++i], 0);
+      if (arg === "--context" && contentRest[i + 1]) {
+        options.context_lines = positiveInt("--context", contentRest[++i], 0);
         continue;
       }
       if (arg !== undefined) {
@@ -636,22 +623,22 @@ async function runCli(argv: string[]): Promise<void> {
   }
 
   if (command === "expand") {
-    const filePath = sizedRest[0];
-    const lineRaw = sizedRest[1];
+    const filePath = contentRest[0];
+    const lineRaw = contentRest[1];
     if (!filePath || !lineRaw) {
       printCommandHelp("expand");
       process.exit(1);
     }
     const line = Number(lineRaw);
-    const path = resolveSearchPath(sizedRest[2] ?? process.cwd());
+    const path = resolveSearchPath(contentRest[2] ?? process.cwd());
     let before = DEFAULT_EXPAND_BEFORE;
     let after = DEFAULT_EXPAND_AFTER;
-    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]);
+    for (let i = 3; i < contentRest.length; i++) {
+      const arg = contentRest[i];
+      if (arg === "--before" && contentRest[i + 1]) {
+        before = Number(contentRest[++i]);
+      } else if (arg === "--after" && contentRest[i + 1]) {
+        after = Number(contentRest[++i]);
       }
     }
     await runExpand(path, filePath, line, before, after, content, jsonFlag);
@@ -659,15 +646,15 @@ async function runCli(argv: string[]): Promise<void> {
   }
 
   if (command === "find-related") {
-    const filePath = sizedRest[0];
-    const lineRaw = sizedRest[1];
+    const filePath = contentRest[0];
+    const lineRaw = contentRest[1];
     if (!filePath || !lineRaw) {
       printCommandHelp("find-related");
       process.exit(1);
     }
     const line = Number(lineRaw);
-    const path = resolveSearchPath(sizedRest[2] ?? process.cwd());
-    await runFindRelated(path, filePath, line, topK, content, jsonFlag);
+    const path = resolveSearchPath(contentRest[2] ?? process.cwd());
+    await runFindRelated(path, filePath, line, content, jsonFlag);
     return;
   }
 
@@ -687,6 +674,10 @@ async function runMcp(argv: string[]): Promise<void> {
       benchmark = true;
       continue;
     }
+    if (arg === "--benchmark=true" || arg === "--benchmark=false") {
+      benchmark = arg === "--benchmark=true";
+      continue;
+    }
     if (arg === "--ref" && argv[i + 1]) {
       ref = argv[++i] ?? null;
       continue;

package/src/credentials.ts

@@ -20,9 +20,14 @@ export function setStoredCredentialsEnvToken(token: string): void {
   process.env.TAKARA_API_KEY = token;
 }
 
+/** True for an unresolved `${...}` placeholder — a plugin host that didn't substitute it. */
+function isUnsubstitutedPlaceholder(value: string): boolean {
+  return value.startsWith("${") && value.endsWith("}");
+}
+
 export function resolveCredentialsDir(): string {
   const override = process.env.MIRU_CREDENTIALS_DIR;
-  if (override) {
+  if (override && !isUnsubstitutedPlaceholder(override)) {
     return override;
   }
   const home = process.env.HOME ?? process.env.USERPROFILE ?? "";

package/src/help.ts

@@ -108,11 +108,10 @@ export function printCommandHelp(command: string): void {
       section("Usage");
       writeStdout("  miru search <query> [path] [options]");
       section("Options");
-      writeStdout("  -k, --top-k N       Number of results (default: 5)");
       writeStdout("  --content TYPE      code | docs | config | all (default: code config)");
       writeStdout("  --json              JSON output (default when piped)");
       section("Example");
-      writeStdout('  miru search "where is auth" ./src -k 10 --content code docs');
+      writeStdout('  miru search "where is auth" ./src --content code docs');
       writeStdout("");
       return;
     case "locate":
@@ -149,7 +148,7 @@ export function printCommandHelp(command: string): void {
       section("Usage");
       writeStdout("  miru find-related <file> <line> [path] [options]");
       section("Example");
-      writeStdout("  miru find-related src/auth.ts 42 . -k 8");
+      writeStdout("  miru find-related src/auth.ts 42 .");
       writeStdout("");
       return;
     case "setup":

package/src/index/chunk-selector.ts

@@ -4,14 +4,16 @@ export type ChunkIndexMappings = {
 };
 
 /**
- * Union of chunk indices matching language and/or path filters.
+ * Union of chunk indices matching language and/or path filters. Path filters
+ * match an exact indexed file path or every file below a directory prefix.
  *
  * Filters combine with OR semantics: a chunk is included if it matches any
  * requested language or path. Returns `undefined` when no filters are given
- * (search all chunks) or when no chunks match.
+ * (search all chunks), and an empty array when filters match no chunks.
  *
- * Single-filter queries return the prebuilt map array directly (read-only for
- * callers). Multi-filter queries allocate a deduped index list.
+ * Exact-file and single-language queries return the prebuilt map array
+ * directly (read-only for callers). Directory and multi-filter queries
+ * allocate an index list.
  */
 export function buildChunkSelector(
   mappings: ChunkIndexMappings,
@@ -28,19 +30,28 @@ export function buildChunkSelector(
   if (langCount === 1 && pathCount === 0) {
     const lang = filterLanguages?.[0];
     if (!lang) {
-      return undefined;
+      return [];
     }
     const indices = mappings.languageMapping.get(lang);
-    return indices && indices.length > 0 ? indices : undefined;
+    return indices && indices.length > 0 ? indices : [];
   }
 
   if (pathCount === 1 && langCount === 0) {
     const fp = filterPaths?.[0];
     if (!fp) {
-      return undefined;
+      return [];
     }
-    const indices = mappings.fileMapping.get(fp);
-    return indices && indices.length > 0 ? indices : undefined;
+    const normalized = normalizePathFilter(fp);
+    const exact = [...mappings.fileMapping.entries()].find(
+      ([filePath]) => filePath.replace(/\\/g, "/") === normalized,
+    )?.[1];
+    if (exact) {
+      return exact;
+    }
+    const prefix = `${normalized}/`;
+    return [...mappings.fileMapping.entries()]
+      .filter(([filePath]) => filePath.replace(/\\/g, "/").startsWith(prefix))
+      .flatMap(([, indices]) => indices);
   }
 
   const selector: number[] = [];
@@ -48,10 +59,27 @@ export function buildChunkSelector(
     selector.push(...(mappings.languageMapping.get(lang) ?? []));
   }
   for (const fp of filterPaths ?? []) {
-    selector.push(...(mappings.fileMapping.get(fp) ?? []));
+    const normalized = normalizePathFilter(fp);
+    const exact = [...mappings.fileMapping.entries()].find(
+      ([filePath]) => filePath.replace(/\\/g, "/") === normalized,
+    )?.[1];
+    if (exact) {
+      selector.push(...exact);
+      continue;
+    }
+    const prefix = `${normalized}/`;
+    for (const [filePath, indices] of mappings.fileMapping) {
+      if (filePath.replace(/\\/g, "/").startsWith(prefix)) {
+        selector.push(...indices);
+      }
+    }
   }
   if (selector.length === 0) {
-    return undefined;
+    return [];
   }
   return [...new Set(selector)];
 }
+
+function normalizePathFilter(filePath: string): string {
+  return filePath.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/$/, "");
+}

package/src/installer/search-policy.ts

@@ -30,13 +30,13 @@ ${SNIPPET_GUIDANCE}
 
 Use Miru MCP tools:
 - \`locate\` — exact substring (env var, symbol, error code); prefer \`mode=count\` or \`locations\`
-- \`search\` — one call per conceptual question; pass project root as \`repo\`
+- \`search\` — one call per conceptual question; pass project root as \`repo\`; use \`include\` / \`exclude\` Gitignore-style globs to scope files (same syntax as \`locate\`)
 - \`expand\` — more context in the same file when \`truncated: true\` (\`file_path\` + \`anchor_line\`)
 - \`find_related\` — similar code in other files (hits may also be snippets; use \`expand\` if truncated)
 
 Call shapes:
 - \`locate(literal="<exact substring>", repo="<project root>")\` — prefer \`mode="locations"\`/\`"count"\`
-- \`search(query="<natural language>", repo="<project root>")\`
+- \`search(query="<natural language>", repo="<project root>", include=["src/auth/**"])\` — use the same \`include\` / \`exclude\` globs on \`locate\` when scoping an exact-string search
 
 Stop rules:
 - Literal in the request → \`locate\`, not \`search\`
@@ -134,7 +134,7 @@ export const MCP_BENCHMARK_SERVER_INSTRUCTIONS =
 
 export const MCP_SEARCH_TOOL_DESCRIPTION =
   "Your default search for all code search queries in this indexed repo — the best, fastest, and cheapest way to find code; better than any other tool. " +
-  "Returns compact snippets (~±15 lines). One call per question. " +
+  "Returns up to 5 compact snippets (~±15 lines). One call per question. Use `include` / `exclude` Gitignore-style globs to scope files; these work the same way on `locate`. " +
   "Exact literal (env var, symbol, error code, quoted text)? Use `locate` instead. " +
   "On `truncated: true`, call `expand` — only if the snippet doesn't already answer the question.";
 
@@ -155,7 +155,7 @@ export const MCP_EXPAND_TOOL_DESCRIPTION =
   "Use only if `truncated: true` and the snippet doesn't already answer the question — not for similar code elsewhere (use find_related).";
 
 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`. " +
+  "Find up to 5 chunks 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.";
 
 export const MCP_READ_BENCHMARK_TOOL_DESCRIPTION =

package/src/mcp/server.ts

@@ -24,17 +24,15 @@ import {
 import { formatLiteralLocate } from "../literal.ts";
 import type { Chunk, ContentType, SearchResult } from "../types.ts";
 import {
-  clampMcpTopK,
   DEFAULT_EXPAND_AFTER,
   DEFAULT_EXPAND_BEFORE,
-  DEFAULT_MCP_TOP_K,
   dedupeResultsByFile,
   expandChunksAtLine,
   formatExpandResults,
   formatResults,
   localRepoRoot,
-  MAX_MCP_TOP_K,
   resolveChunk,
+  SEARCH_RESULT_COUNT,
 } from "../utils.ts";
 import { registerAuthTool, toolErrorText } from "./auth-tool.ts";
 import {
@@ -52,6 +50,8 @@ const REPO_DESCRIPTION =
 
 const BENCHMARK_SKIP_NOTES = {
   local_repo_only: "Benchmark comparisons require a local repo path; git URL repos are skipped.",
+  filtered_search:
+    "Benchmark comparisons are skipped when search is restricted by include/exclude patterns.",
   limited_locate:
     "Benchmark comparison skipped: locate.limit is global, while rg/grep limits are per file. Omit limit for a valid token and recall comparison.",
   incompatible_literal_baseline:
@@ -147,27 +147,35 @@ export function createMcpServer(
             "Natural language or code query — your default for all code search in this repo.",
           ),
         repo: z.string().describe(REPO_DESCRIPTION),
-        top_k: z
-          .number()
-          .int()
+        include: z
+          .array(z.string().min(1))
+          .min(1)
+          .optional()
+          .describe(
+            'Gitignore-style glob patterns; only matching files are searched (e.g. ["src/auth/**", "docs/**/*.md"]). Same semantics as `locate.include`.',
+          ),
+        exclude: z
+          .array(z.string().min(1))
           .min(1)
-          .max(MAX_MCP_TOP_K)
           .optional()
-          .describe(`Number of results (default ${DEFAULT_MCP_TOP_K}, max ${MAX_MCP_TOP_K}).`),
+          .describe(
+            "Gitignore-style glob patterns; matching files are skipped. Same semantics as `locate.exclude`.",
+          ),
         dedupe_by_file: z
           .boolean()
           .optional()
           .describe("Keep only the best hit per file (default true)."),
       },
     },
-    async ({ query, repo, top_k: topK, dedupe_by_file: dedupeByFile }) => {
+    async ({ query, repo, include, exclude, dedupe_by_file: dedupeByFile }) => {
       try {
         const index = await getIndexForRepo(repo, cache);
         const repoRoot = localRepoRoot(repo);
-        const k = clampMcpTopK(topK);
-
+        const k = SEARCH_RESULT_COUNT;
         let skip: BenchmarkSkipReason | undefined;
-        if (benchmark && repoRoot) {
+        if (benchmark && (include || exclude)) {
+          skip = "filtered_search";
+        } else if (benchmark && repoRoot) {
           const comparison = await withGrepTimeoutFallback(() =>
             benchmarkSearchComparison({
               query,
@@ -199,7 +207,7 @@ export function createMcpServer(
           skip = "local_repo_only";
         }
 
-        let results = await index.search({ query, topK: k });
+        let results = await index.search({ query, topK: k, include, exclude });
         if (dedupeByFile !== false) {
           results = dedupeResultsByFile(results);
         }
@@ -397,18 +405,9 @@ export function createMcpServer(
           .int()
           .describe("Line from the search hit (`anchor_line` when truncated, else `start_line`)."),
         repo: z.string().describe(REPO_DESCRIPTION),
-        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, anchor_line: anchorLine, repo, top_k: topK }) => {
+    async ({ file_path: filePath, anchor_line: anchorLine, repo }) => {
       try {
         const index = await getIndexForRepo(repo, cache);
         const repoRoot = localRepoRoot(repo);
@@ -418,7 +417,7 @@ export function createMcpServer(
             `No chunk found at ${filePath}:${anchorLine}. Make sure the file is indexed and the line number is within a known chunk.`,
           );
         }
-        const results = await index.findRelated(chunk, clampMcpTopK(topK));
+        const results = await index.findRelated(chunk, SEARCH_RESULT_COUNT);
         if (results.length === 0) {
           return toolText(`No related chunks found for ${filePath}:${anchorLine}.`);
         }

package/src/miru-index.ts

@@ -14,7 +14,12 @@ import { createIndexFromPath } from "./index/create.ts";
 import { applyIncrementalFileChanges, normalizeRelativePath } from "./index/incremental.ts";
 import { persistencePaths, saveIndexBundle } from "./index/persistence.ts";
 import type { SemanticIndex } from "./index/semantic-index.ts";
-import { type LiteralLocateOptions, type LiteralLocateResult, locateLiteral } from "./literal.ts";
+import {
+  filterChunksByGlob,
+  type LiteralLocateOptions,
+  type LiteralLocateResult,
+  locateLiteral,
+} from "./literal.ts";
 import { hybridSearch, searchSemanticOnly } from "./search.ts";
 import type { Chunk, ContentType, SearchResult } from "./types.ts";
 import { chunkKey, chunkToDict, defaultContentTypes } from "./types.ts";
@@ -407,11 +412,19 @@ export class MiruIndex {
     );
   }
 
+  private getPathSelector(include?: string[], exclude?: string[]): readonly number[] | undefined {
+    if (!include?.length && !exclude?.length) {
+      return undefined;
+    }
+    const included = new Set(filterChunksByGlob(this.chunks, include, exclude).map(chunkKey));
+    return this.chunks.flatMap((chunk, index) => (included.has(chunkKey(chunk)) ? [index] : []));
+  }
+
   /**
    * Hybrid BM25 + semantic search over indexed chunks.
    *
    * `alpha` blends keyword vs vector scores (default depends on content type).
-   * `filterLanguages` / `filterPaths` restrict candidates before ranking.
+   * `include` / `exclude` glob patterns restrict candidate files before ranking.
    * `rerank` defaults to on for code indexes (cross-encoder style reranking).
    */
   async search(options: {
@@ -422,15 +435,34 @@ export class MiruIndex {
     alpha?: number | null;
     filterLanguages?: string[];
     filterPaths?: string[];
+    include?: string[];
+    exclude?: string[];
     rerank?: boolean;
   }): Promise<SearchResult[]> {
-    const { query, queryVector, topK = 10, alpha, filterLanguages, filterPaths, rerank } = options;
+    const {
+      query,
+      queryVector,
+      topK = 10,
+      alpha,
+      filterLanguages,
+      filterPaths,
+      include,
+      exclude,
+      rerank,
+    } = options;
 
     if (!this.chunks.length || !query.trim()) {
       return [];
     }
 
     const resolvedRerank = rerank ?? this.content.includes("code");
+    const selector = this.getSelector(filterLanguages, filterPaths);
+    const pathSelector = this.getPathSelector(include, exclude);
+    let effectiveSelector = pathSelector ?? selector;
+    if (selector && pathSelector) {
+      const allowedIndices = new Set(selector);
+      effectiveSelector = pathSelector.filter((index) => allowedIndices.has(index));
+    }
 
     return hybridSearch({
       query,
@@ -441,7 +473,7 @@ export class MiruIndex {
       chunks: this.chunks,
       topK,
       alpha,
-      selector: this.getSelector(filterLanguages, filterPaths),
+      selector: effectiveSelector,
       rerank: resolvedRerank,
     });
   }

package/src/search.ts

@@ -96,6 +96,10 @@ export async function hybridSearch(options: {
     rerank = true,
   } = options;
 
+  if (selector?.length === 0) {
+    return [];
+  }
+
   const alphaWeight = resolveAlpha(query, alpha);
   const tuning = rankingConfig();
   const candidateCount =

package/src/utils.ts

@@ -100,22 +100,12 @@ export type ExpandResults = {
   chunks: Record<string, unknown>[];
 };
 
-export const DEFAULT_MCP_TOP_K = 3;
-export const MAX_MCP_TOP_K = 10;
+export const SEARCH_RESULT_COUNT = 5;
 
 /** Extra chunks before/after the expand anchor — MCP `expand` tool defaults. */
 export const DEFAULT_EXPAND_BEFORE = 1;
 export const DEFAULT_EXPAND_AFTER = 1;
 
-/** 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);
   if (!repoRoot) {