@takara-ai/miru-code 0.1.2 → 0.1.4

package/README.md

@@ -2,9 +2,31 @@
 
 Hybrid code search for AI agents — **TypeScript**, **Bun**, and **Takara embeddings**.
 
-*Miru* means “to see” or “to look” in Japanese — semantic search that helps agents find code by meaning.
+## What is Miru?
 
-Indexes a local directory, combines semantic search with BM25, RRF fusion, and code-tuned reranking.
+*Miru* (見る) means “to see” or “to look” in Japanese. Miru helps coding agents **find code by meaning** instead of guessing file paths or running exhaustive greps.
+
+When an agent asks “where is auth middleware configured?” or “how do we batch embeddings?”, Miru returns the most relevant **chunks** of your codebase — file path, line range, and snippet — so the agent can read only what matters.
+
+### Why hybrid search?
+
+Pure semantic search misses exact symbol matches. Pure keyword search misses paraphrased intent. Miru combines both:
+
+1. **Dense (semantic)** — Takara code embeddings (`ds1-potion-code-16m`) over structurally chunked source files.
+2. **Sparse (BM25)** — keyword scoring with an inverted index; parallelized in Bun workers on large repos.
+3. **RRF fusion** — reciprocal rank fusion merges the two ranked lists.
+4. **Reranking** — code-tuned penalties and boosts (e.g. multi-chunk files, query-term overlap).
+
+Indexes are built on demand, cached on disk, and invalidated when files change. You can search **code**, **docs**, **config**, or **all** content types.
+
+### How agents use Miru
+
+| Mode | Best for | What the agent gets |
+|------|----------|---------------------|
+| **MCP server** | Cursor, Claude Code, VS Code Copilot, Gemini CLI, Kiro, OpenCode | Native `search` and `find_related` tools over the workspace |
+| **CLI sub-agent** | Any agent with shell access | `miru init --agent <id>` writes a specialist agent that runs `miru search` / `miru find-related` via Bash |
+
+Both modes share the same index and cache. Pick MCP when your IDE supports it; use the sub-agent when you want a dedicated exploration agent without MCP wiring.
 
 ## Install
 
@@ -12,7 +34,7 @@ Requires [Bun](https://bun.sh) 1.1+ on your PATH (`curl -fsSL https://bun.sh/ins
 
 ```bash
 # Run once without installing
-bun x @takara-ai/miru-code search "auth middleware" ./src
+bunx @takara-ai/miru-code search "auth middleware" ./src
 
 # Global CLI
 bun add -g @takara-ai/miru-code
@@ -34,7 +56,7 @@ const index = await MiruIndex.fromPath("./src");
 bun install
 ```
 
-Add credentials to `.env.local` (loaded automatically when you run from this repo), or pass them in your MCP config `env` block (recommended for Cursor — MCP does not inherit IDE env vars reliably).
+Add credentials to `.env.local` (loaded automatically when you run from this repo), or pass them in your MCP config `env` block (recommended — MCP does not inherit IDE env vars reliably).
 
 | Variable | Default |
 |----------|---------|
@@ -52,64 +74,153 @@ Parallelism: file reads/chunking, embedding batches (up to concurrency in flight
 
 `OPENAI_*` env aliases are also accepted where noted in the CLI help.
 
-## CLI
+## IDE integration
+
+Miru supports six agent platforms. For each, you can wire the **MCP server** (recommended) and/or install a **CLI sub-agent** with `miru init`.
+
+### Quick reference
+
+| IDE | MCP config file | Sub-agent command | Sub-agent output |
+|-----|-----------------|-------------------|------------------|
+| [Cursor](#cursor) | `~/.cursor/mcp.json` or `.cursor/mcp.json` | `miru init --agent cursor` | `.cursor/agents/miru-code.md` |
+| [Claude Code](#claude-code) | `.mcp.json` (project root) or `~/.claude.json` | `miru init --agent claude` | `.claude/agents/miru-code.md` |
+| [VS Code / Copilot](#vs-code--github-copilot) | `.vscode/mcp.json` or user profile `mcp.json` | `miru init --agent copilot` | `.github/agents/miru-code.md` |
+| [Gemini CLI](#gemini-cli) | `~/.gemini/settings.json` or `.gemini/settings.json` | `miru init --agent gemini` | `.gemini/agents/miru-code.md` |
+| [Kiro](#kiro) | `~/.kiro/settings/mcp.json` or `.kiro/settings/mcp.json` | `miru init --agent kiro` | `.kiro/agents/miru-code.md` |
+| [OpenCode](#opencode) | `~/.config/opencode/opencode.json` or `opencode.json` | `miru init --agent opencode` | `.opencode/agents/miru-code.md` |
+
+Run `miru init --agent <id> --force` to overwrite an existing sub-agent file.
+
+### MCP server
+
+Run with **no arguments** to start the stdio MCP server. It indexes the **current working directory** (most IDEs set this to your workspace). Optional path/ref flags pre-index a different repo.
 
 ```bash
-# Hybrid search (positional, Python-compatible)
-bun run miru search "where are embeddings created" ./src -k 5
+bunx @takara-ai/miru-code
+# or after bun add -g @takara-ai/miru-code:  miru
+```
 
-# Find semantically related chunks
-bun run miru find-related src/embeddings/openai.ts 120 ./src
+**Tools:** `search`, `find_related` — pass `repo` only when querying a different path or git URL.
 
-# Write a miru-code sub-agent for Cursor / Claude / etc.
-bun run miru init --agent cursor
+For MCP configs, use `bunx` as the command (`bun` with `x` in `args` works too — they're equivalent).
 
-# Clear disk cache
-bun run miru clear ./src
+Put the bearer token in `env`; MCP will not read `.env.local` unless those vars are unset.
+
+#### Shared env block
+
+Use this in every MCP config below (adjust the key name if your IDE uses `environment` instead of `env`):
+
+```json
+{
+  "TAKARA_API_KEY": "your-takara-bearer-token",
+  "MIRU_OPENAI_BASE_URL": "https://infer.dev.takara.ai/v1",
+  "MIRU_OPENAI_EMBEDDING_MODEL": "ds1-potion-code-16m",
+  "MIRU_EMBEDDING_DIMENSIONS": "256"
+}
 ```
 
-Indexes are cached under `~/Library/Caches/miru` (macOS) or `~/.cache/miru` (Linux).
+### Cursor
 
-## MCP server
+**MCP** — `~/.cursor/mcp.json` or project `.cursor/mcp.json`:
 
-Run with **no arguments** to start the stdio MCP server. It indexes the **current working directory** (Cursor sets this to your workspace). Optional path/ref flags pre-index a different repo.
+```json
+{
+  "mcpServers": {
+    "miru": {
+      "command": "bunx",
+      "args": ["@takara-ai/miru-code"],
+      "env": {
+        "TAKARA_API_KEY": "your-takara-bearer-token"
+      }
+    }
+  }
+}
+```
+
+After `bun add -g @takara-ai/miru-code`, you can use `"command": "miru"` instead.
+
+**Sub-agent:**
 
 ```bash
-bun /path/to/miru/src/cli.ts
-# or after bun add -g @takara-ai/miru-code:  miru
-# or without installing:           bun x @takara-ai/miru-code
+miru init --agent cursor
 ```
 
-**Tools:** `search`, `find_related` — pass `repo` only when querying a different path or git URL.
+Commit `.cursor/agents/miru-code.md` to share the exploration agent with your team.
 
-Cursor `~/.cursor/mcp.json` (or project `.cursor/mcp.json`):
+### Claude Code
 
-Use **`bun x`** (not `bunx` as the command) so Cursor does not pull the `bun` npm package postinstall, which breaks in MCP sandboxes:
+**MCP** — project `.mcp.json` (check into git) or user scope in `~/.claude.json`:
 
 ```json
 {
   "mcpServers": {
     "miru": {
-      "command": "bun",
-      "args": ["x", "@takara-ai/miru-code"],
+      "type": "stdio",
+      "command": "bunx",
+      "args": ["@takara-ai/miru-code"],
       "env": {
-        "TAKARA_API_KEY": "your-takara-bearer-token",
-        "MIRU_OPENAI_BASE_URL": "https://infer.dev.takara.ai/v1",
-        "MIRU_OPENAI_EMBEDDING_MODEL": "ds1-potion-code-16m",
-        "MIRU_EMBEDDING_DIMENSIONS": "256"
+        "TAKARA_API_KEY": "${TAKARA_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+Claude Code supports `${VAR}` expansion in config files. Restart the session and run `/mcp` to verify the connection.
+
+Or via CLI:
+
+```bash
+claude mcp add miru -s project -- bunx @takara-ai/miru-code
+```
+
+**Sub-agent:**
+
+```bash
+miru init --agent claude
+```
+
+Writes `.claude/agents/miru-code.md` — invoke the `miru-code` agent for semantic exploration tasks.
+
+### VS Code / GitHub Copilot
+
+**MCP** — workspace `.vscode/mcp.json` or user profile (Command Palette: **MCP: Open User Configuration**):
+
+```json
+{
+  "servers": {
+    "miru": {
+      "type": "stdio",
+      "command": "bunx",
+      "args": ["@takara-ai/miru-code"],
+      "env": {
+        "TAKARA_API_KEY": "your-takara-bearer-token"
       }
     }
   }
 }
 ```
 
-Alternatively, after `bun add -g @takara-ai/miru-code`:
+VS Code uses `"servers"` (not `mcpServers`). Use **MCP: List Servers** to start or restart the server after editing the config.
+
+**Sub-agent:**
+
+```bash
+miru init --agent copilot
+```
+
+Writes `.github/agents/miru-code.md` for Copilot’s agent system.
+
+### Gemini CLI
+
+**MCP** — `~/.gemini/settings.json` or project `.gemini/settings.json`:
 
 ```json
 {
   "mcpServers": {
     "miru": {
-      "command": "miru",
+      "command": "bunx",
+      "args": ["@takara-ai/miru-code"],
       "env": {
         "TAKARA_API_KEY": "your-takara-bearer-token"
       }
@@ -118,15 +229,58 @@ Alternatively, after `bun add -g @takara-ai/miru-code`:
 }
 ```
 
-Local development (path to this repo):
+Or add interactively: `gemini mcp add`. Run `/mcp` inside a session to confirm tools are available.
+
+**Sub-agent:**
+
+```bash
+miru init --agent gemini
+```
+
+Writes `.gemini/agents/miru-code.md`.
+
+### Kiro
+
+**MCP** — `~/.kiro/settings/mcp.json` or workspace `.kiro/settings/mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "miru": {
-      "command": "bun",
-      "args": ["/absolute/path/to/miru/src/cli.ts"],
+      "command": "bunx",
+      "args": ["@takara-ai/miru-code"],
       "env": {
+        "TAKARA_API_KEY": "your-takara-bearer-token",
+        "PATH": "/usr/local/bin:/usr/bin:/bin"
+      }
+    }
+  }
+}
+```
+
+Kiro runs with a minimal environment — include `PATH` if Bun is not on the default path. Approve env vars when prompted in the IDE.
+
+**Sub-agent:**
+
+```bash
+miru init --agent kiro
+```
+
+Writes `.kiro/agents/miru-code.md`.
+
+### OpenCode
+
+**MCP** — `~/.config/opencode/opencode.json` or project `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "miru": {
+      "type": "local",
+      "command": ["bunx", "@takara-ai/miru-code"],
+      "enabled": true,
+      "environment": {
         "TAKARA_API_KEY": "your-takara-bearer-token"
       }
     }
@@ -134,7 +288,49 @@ Local development (path to this repo):
 }
 ```
 
-No project path in `args` for `bun x` / global install — Cursor runs the server with `cwd` set to the open workspace, which becomes the default index. Put the bearer token in `env`; MCP will not read `.env.local` unless those vars are unset.
+OpenCode uses the `mcp` key (not `mcpServers`), requires `"type": "local"`, and uses `environment` instead of `env`. Verify with `opencode mcp list`.
+
+**Sub-agent:**
+
+```bash
+miru init --agent opencode
+```
+
+Writes `.opencode/agents/miru-code.md` (subagent mode with bash/read permissions).
+
+### Local development (any IDE)
+
+Point MCP at this repo instead of the published package:
+
+```json
+{
+  "command": "bun",
+  "args": ["/absolute/path/to/miru-code/src/cli.ts"],
+  "env": {
+    "TAKARA_API_KEY": "your-takara-bearer-token"
+  }
+}
+```
+
+Merge into the appropriate wrapper key (`mcpServers`, `servers`, or `mcp`) for your IDE.
+
+## CLI
+
+```bash
+# Hybrid search (positional, Python-compatible)
+bun run miru search "where are embeddings created" ./src -k 5
+
+# Find semantically related chunks
+bun run miru find-related src/embeddings/openai.ts 120 ./src
+
+# Write a miru-code sub-agent for your IDE
+bun run miru init --agent cursor
+
+# Clear disk cache
+bun run miru clear ./src
+```
+
+Indexes are cached under `~/Library/Caches/miru` (macOS) or `~/.cache/miru` (Linux).
 
 ## Library
 

package/package.json

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

package/src/cli.ts

@@ -2,15 +2,18 @@
 import { resolve } from "node:path";
 import { type AgentId, writeAgentFile } from "./agents.ts";
 import { clearCache } from "./cache.ts";
+import { loadStoredCredentials } from "./credentials.ts";
 import { loadEnvFiles } from "./env-files.ts";
 import { serveMcp } from "./mcp/serve.ts";
 import { MiruIndex } from "./miru-index.ts";
+import { ensureCredentials, runClearCredentials, runSetup } from "./setup.ts";
 import type { ContentType } from "./types.ts";
 import { formatResults, isGitUrl, resolveChunk, resolveContent } from "./utils.ts";
 
 loadEnvFiles();
+await loadStoredCredentials();
 
-const CLI_COMMANDS = new Set(["search", "find-related", "init", "clear", "-h", "--help"]);
+const CLI_COMMANDS = new Set(["search", "find-related", "init", "setup", "clear", "-h", "--help"]);
 
 const AGENTS = new Set<AgentId>(["claude", "copilot", "cursor", "gemini", "kiro", "opencode"]);
 
@@ -64,6 +67,7 @@ async function runSearch(
   topK: number,
   content: ContentType[],
 ): Promise<void> {
+  await ensureCredentials();
   const index = await MiruIndex.fromSource(path, content);
   await index.saveToDefaultCache(path);
   const results = await index.search({ query, topK });
@@ -79,6 +83,7 @@ async function runFindRelated(
   topK: number,
   content: ContentType[],
 ): Promise<void> {
+  await ensureCredentials();
   const index = await MiruIndex.fromSource(path, content);
   const chunk = resolveChunk(index.chunks, filePath, line);
   if (!chunk) {
@@ -111,6 +116,7 @@ function printHelp(): void {
 CLI:
   miru search <query> [path] [-k N] [--content code|docs|config|all]
   miru find-related <file_path> <line> [path] [-k N] [--content ...]
+  miru setup [--key KEY] [--force] [--clear]
   miru init [--agent cursor] [--force]
   miru clear [path]
 
@@ -156,6 +162,32 @@ async function runCli(argv: string[]): Promise<void> {
     return;
   }
 
+  if (command === "setup") {
+    let apiKey: string | undefined;
+    let force = false;
+    let clear = false;
+    for (let i = 0; i < rest.length; i++) {
+      const arg = rest[i];
+      if (arg === "--force") {
+        force = true;
+      } else if (arg === "--clear") {
+        clear = true;
+      } else if ((arg === "--key" || arg === "-k") && rest[i + 1]) {
+        apiKey = rest[++i];
+      }
+    }
+    if (clear) {
+      if (apiKey) {
+        console.error("Usage: miru setup --clear cannot be combined with --key.");
+        process.exit(1);
+      }
+      await runClearCredentials();
+      return;
+    }
+    await runSetup({ apiKey, force });
+    return;
+  }
+
   if (command === "clear") {
     const path = resolve(rest[0] ?? process.cwd());
     await runClear(path);
@@ -229,6 +261,11 @@ async function runMcp(argv: string[]): Promise<void> {
   });
 }
 
+async function runMcpWithCredentials(argv: string[]): Promise<void> {
+  await ensureCredentials({ interactive: false });
+  await runMcp(argv);
+}
+
 async function main(): Promise<void> {
   const argv = process.argv.slice(2);
   const first = argv[0];
@@ -236,7 +273,7 @@ async function main(): Promise<void> {
     await runCli(argv);
     return;
   }
-  await runMcp(argv);
+  await runMcpWithCredentials(argv);
 }
 
 main().catch((err) => {

package/src/credentials.ts

@@ -0,0 +1,101 @@
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { EMBEDDING_API_KEY_NAMES, envFirstString } from "./env.ts";
+
+const CREDENTIALS_FILENAME = "credentials.json";
+const CREDENTIALS_VERSION = 1;
+
+interface StoredCredentials {
+  version: number;
+  takara_api_key: string;
+}
+
+export function resolveCredentialsDir(): string {
+  const override = process.env.MIRU_CREDENTIALS_DIR;
+  if (override) {
+    return override;
+  }
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+  if (process.platform === "win32") {
+    const base = process.env.APPDATA ?? join(home, "AppData", "Roaming");
+    return join(base, "miru");
+  }
+  if (process.platform === "darwin") {
+    return join(home, "Library", "Application Support", "miru");
+  }
+  const xdg = process.env.XDG_CONFIG_HOME ?? join(home, ".config");
+  return join(xdg, "miru");
+}
+
+export function resolveCredentialsPath(): string {
+  return join(resolveCredentialsDir(), CREDENTIALS_FILENAME);
+}
+
+export function hasEmbeddingApiKeyInEnv(): boolean {
+  return Boolean(envFirstString([...EMBEDDING_API_KEY_NAMES], ""));
+}
+
+export async function readStoredCredentials(): Promise<StoredCredentials | null> {
+  const path = resolveCredentialsPath();
+  if (!(await Bun.file(path).exists())) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf-8")) as StoredCredentials;
+    if (parsed.version !== CREDENTIALS_VERSION || !parsed.takara_api_key) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/** Set TAKARA_API_KEY from the user credentials file when env is unset. */
+export async function loadStoredCredentials(): Promise<boolean> {
+  if (hasEmbeddingApiKeyInEnv()) {
+    return false;
+  }
+  const stored = await readStoredCredentials();
+  if (!stored) {
+    return false;
+  }
+  process.env.TAKARA_API_KEY = stored.takara_api_key;
+  return true;
+}
+
+export async function saveStoredCredentials(apiKey: string): Promise<string> {
+  const dir = resolveCredentialsDir();
+  const path = resolveCredentialsPath();
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  const payload: StoredCredentials = {
+    version: CREDENTIALS_VERSION,
+    takara_api_key: apiKey,
+  };
+  await writeFile(path, `${JSON.stringify(payload, null, 2)}\n`, {
+    encoding: "utf-8",
+    mode: 0o600,
+  });
+  try {
+    await chmod(path, 0o600);
+  } catch {
+    // Windows may not support Unix mode bits on all filesystems.
+  }
+  return path;
+}
+
+export async function clearStoredCredentials(): Promise<{ cleared: boolean; path: string }> {
+  const path = resolveCredentialsPath();
+  if (!(await Bun.file(path).exists())) {
+    return { cleared: false, path };
+  }
+
+  const stored = await readStoredCredentials();
+  await rm(path, { force: true });
+
+  if (stored && process.env.TAKARA_API_KEY === stored.takara_api_key) {
+    delete process.env.TAKARA_API_KEY;
+  }
+
+  return { cleared: true, path };
+}

package/src/embeddings/openai.ts

@@ -63,14 +63,23 @@ function splitIntoWindows(text: string, maxChars: number): string[] {
   return out;
 }
 
-function sanitizeEmbeddingInput(text: string): string {
+/** Unpaired UTF-16 surrogates are invalid in JSON and break strict API parsers. */
+function stripLoneSurrogates(text: string): string {
+  return text.replace(
+    /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g,
+    "\uFFFD",
+  );
+}
+
+export function sanitizeEmbeddingInput(text: string): string {
+  const out = stripLoneSurrogates(text);
   // Some OpenAI-compatible gateways mis-handle backslash escapes in JSON text
   // payloads. Keep a benchmark fallback mode to forcefully neutralize them.
   const mode = process.env.MIRU_EMBED_ESCAPE_MODE ?? process.env.SEMBLE_EMBED_ESCAPE_MODE ?? "quad";
   if (mode === "strip") {
-    return text.replaceAll("\\", "/");
+    return out.replaceAll("\\", "/");
   }
-  return text.replaceAll("\\", "\\\\\\\\");
+  return out.replaceAll("\\", "\\\\\\\\");
 }
 
 function isPayloadTooLargeError(err: unknown): boolean {

package/src/embeddings/validate.ts

@@ -0,0 +1,94 @@
+import {
+  resolveEmbeddingBaseUrl,
+  resolveEmbeddingDimensions,
+  resolveEmbeddingModel,
+} from "./openai.ts";
+
+export interface ValidateApiKeyResult {
+  valid: boolean;
+  status?: number;
+  message: string;
+}
+
+export async function validateEmbeddingApiKey(options: {
+  apiKey: string;
+  baseUrl?: string;
+  model?: string;
+  dimensions?: number;
+}): Promise<ValidateApiKeyResult> {
+  const baseUrl = (options.baseUrl ?? resolveEmbeddingBaseUrl()).replace(/\/$/, "");
+  const model = options.model ?? resolveEmbeddingModel();
+  const dimensions = options.dimensions ?? resolveEmbeddingDimensions(model);
+  const endpoint = `${baseUrl}/embeddings`;
+
+  const body: Record<string, unknown> = {
+    model,
+    input: "miru setup validation",
+  };
+  if (dimensions != null) {
+    body.dimensions = dimensions;
+  }
+
+  let response: Response;
+  try {
+    response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${options.apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      valid: false,
+      message: `Could not reach embedding API at ${baseUrl}: ${message}`,
+    };
+  }
+
+  if (!response.ok) {
+    const text = await response.text();
+    if (response.status === 401 || response.status === 403) {
+      return {
+        valid: false,
+        status: response.status,
+        message: "Invalid API key (authentication failed).",
+      };
+    }
+    return {
+      valid: false,
+      status: response.status,
+      message: `Embedding API returned ${response.status}: ${text.slice(0, 200)}`,
+    };
+  }
+
+  try {
+    const payload = (await response.json()) as {
+      data?: Array<{ embedding?: number[] }>;
+    };
+    const embedding = payload.data?.[0]?.embedding;
+    if (!embedding || embedding.length === 0) {
+      return {
+        valid: false,
+        status: response.status,
+        message: "Embedding API returned an empty response.",
+      };
+    }
+    if (dimensions != null && embedding.length !== dimensions) {
+      return {
+        valid: false,
+        status: response.status,
+        message: `Expected ${dimensions} embedding dimensions, got ${embedding.length}.`,
+      };
+    }
+  } catch {
+    return {
+      valid: false,
+      status: response.status,
+      message: "Embedding API returned invalid JSON.",
+    };
+  }
+
+  return { valid: true, status: response.status, message: "API key is valid." };
+}

package/src/env.ts

@@ -38,12 +38,14 @@ const EMBEDDING_API_KEY_NAMES = [
   "SEMBLE_OPENAI_API_KEY",
 ] as const;
 
+export { EMBEDDING_API_KEY_NAMES };
+
 export function resolveEmbeddingApiKey(): string {
   const key = envFirstString([...EMBEDDING_API_KEY_NAMES], "");
   if (!key) {
     throw new Error(
-      "Embedding API key required. Set TAKARA_API_KEY, OPENAI_API_KEY, MIRU_OPENAI_API_KEY, or SEMBLE_OPENAI_API_KEY " +
-        "in your MCP server env (Cursor mcp.json) or .env.local.",
+      "Embedding API key required. Run `miru setup`, set TAKARA_API_KEY, OPENAI_API_KEY, " +
+        "MIRU_OPENAI_API_KEY, or SEMBLE_OPENAI_API_KEY in your MCP server env or .env.local.",
     );
   }
   return key;