Repofind MCP Server

repofind

Finding code in a repository you have never opened usually starts with a guess: a word to grep, a filename to try. repofind replaces the guessing with an index. Point it at a local directory and it walks the tree — skipping .git, node_modules, files over a megabyte, and anything outside a source-and-text extension allowlist — splits each file into consecutive 40-line chunks, and ranks those chunks against your question. One call returns the five best places to look, each with its file, line range, the chunk text, and a score.

Ranking is hybrid. A pinned BM25 scorer (k1 = 1.2, b = 0.75) over the chunk texts always runs. When a TAKARA_API_KEY is present in the environment, an embeddings step joins in: the query and the chunks are embedded through an OpenAI-compatible endpoint and each chunk's final score becomes bm25 + 10 * max(0, cosine). Without a key — or if the embedder fails — the result says so plainly in its notes and ranks by keyword alone. By default only the best hit per file is kept, so five hits mean five different files to open.

The other tools cover the rest of the exploration loop. locate finds an exact substring — an env var, a symbol, an error code — and reports it as a count, a file list, bare locations, or full lines. expand takes a hit you already have and returns its chunk plus the neighbouring chunks in the same file. find_related takes the same anchor and ranks chunks from every other file against it. read_benchmark rolls up saved benchmark-mode queries into a token-savings total. The original product's auth tool is not part of this rebuild: its interactive device login and AWS-profile validation cannot be reproduced from the published spec, so the surface here is five of the six tools.

CLI

npx @reneturcios/repofind search '{"query": "retry backoff logic", "repo": "."}'
npx @reneturcios/repofind locate '{"literal": "DATABASE_URL", "mode": "locations"}'
npx @reneturcios/repofind expand '{"file_path": "src/client.ts", "anchor_line": 83}'
npx @reneturcios/repofind find_related '{"file_path": "src/client.ts", "anchor_line": 83}'
npx @reneturcios/repofind read_benchmark '{}'
npx @reneturcios/repofind --version

Each tool subcommand takes the tool's arguments as one JSON string and prints the result as JSON. Exit codes: 0 on success, 1 on a runtime error, 2 on a usage error.

Environment variables: TAKARA_API_KEY enables the semantic half; MIRU_OPENAI_BASE_URL (default https://infer.takara.ai/v1) and MIRU_OPENAI_EMBEDDING_MODEL (default ds1-miru-int8) configure the embeddings endpoint; MIRU_MAX_INDEX_FILES caps the index (default 10000); MIRU_BENCHMARK_HISTORY_PATH overrides the benchmark history location.

MCP server

npx -y @reneturcios/repofind mcp

MCP client config:

{
  "mcpServers": {
    "repofind": {
      "command": "npx",
      "args": ["-y", "@reneturcios/repofind", "mcp"]
    }
  }
}

Tools

• search — Hybrid semantic + keyword search over an indexed local codebase. Default for code exploration — one call per question.

  • query (string, required) — natural language or code query
  • repo (string, optional) — local directory to index; defaults to the working directory
  • include / exclude (string arrays, optional) — gitignore-style glob patterns against repo-relative paths
  • dedupe_by_file (boolean, default true) — keep the best hit per file

  Returns {hits, ranking, notes} with at most 5 hits; each hit is {file_path, absolute_path, start_line, end_line, anchor_line, truncated, snippet, score} with the score rounded to 4 decimals.

• locate — Find exact substrings (env vars, symbols, error codes) in an indexed local codebase.

  • literal (string, required); mode one of count, files, locations, lines (default lines); limit caps locations/lines; ignore_case (default false); repo, include, exclude as in search.

• expand — Return more context in the same file around a search hit: the anchor chunk plus neighbouring chunks.

  • file_path and anchor_line (required); before / after chunk counts (default 1 each).

• find_related — Find similar code in other files, from a hit's file_path and anchor_line. Returns the same {hits, ranking, notes} shape as search, with the source file excluded.

• read_benchmark — Cumulative token-savings rollup from saved benchmark-mode queries. Returns {queries, total_tokens_saved, average_tokens_saved}; a missing history file is a zero rollup, not an error.

Docker

docker run -i ghcr.io/cloudcorprecords/repofind
docker run --rm ghcr.io/cloudcorprecords/repofind locate '{"literal": "TODO"}'

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (temp fixture repos, fake embedder, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios