kalpana-context

Local code search for AI coding agents, as an MCP server. Your agent asks a question in plain words or identifiers and gets back only the 1–3 code chunks that matter. It doesn't have to grep and read whole files.

• Fewer tokens, more tasks solved. See the benchmark below.

• Private. Indexing, embeddings and search all run on your machine, so your code never leaves it.

• No API keys. It uses the open-source MiniLM embedder, downloaded once.

• Zero setup per project. It detects the folder you have open and indexes it on first use.

Built on Miru, Takara's open-source hybrid code search (MIT), plus the Kalpana Discrete RIF structural reranker and an adaptive context cutoff.

Requirements

• Node.js 18+ (check with node -v; get it from https://nodejs.org). Bun is installed automatically.

• macOS, Linux or Windows. Development and testing so far have been on macOS.

• About 200 MB of disk for dependencies and the embedding model, plus the index for each project.

• An MCP-capable agent: Antigravity, Claude Code, Claude Desktop, Cursor, VS Code Copilot, Gemini CLI, and others.

Related MCP server: semantic-search-mcp

Quick start (2 minutes)

1. Add the server to your agent's MCP config (see the table below).

2. Restart or refresh your agent's MCP servers. kalpana-context should appear with 3 tools.

3. Open a project folder in your editor.

4. Ask your agent: "Use code_search to find where <something> is implemented."

5. The first search starts indexing the project in the background. The agent is told to use grep for now. After a few minutes searches return in about 1 second.

Install

Add this to your agent's MCP config:

{
  "mcpServers": {
    "kalpana-context": { "command": "npx", "args": ["-y", "kalpana-context"] }
  }
}

You need Node 18 or newer. Bun is installed automatically as a dependency.

Check that it works

From a terminal you can talk to the server directly:

npx -y kalpana-context --project /path/to/your/repo

It prints [kalpana-context] ready ... on stderr and then waits for MCP messages on stdin. Press Ctrl+C to stop. In your agent, call index_status to see the indexing state and the chunk count.

Architecture

flowchart LR
  subgraph Agent["Your AI agent (Antigravity, Claude, Cursor, ...)"]
    LLM["LLM (cloud)"]
    Host["Agent app"]
  end
  subgraph Local["Your machine: kalpana-context (one Bun process)"]
    MCP["MCP server (stdio)"]
    Proj["Project detection: tool arg > --project > MCP roots > cwd"]
    Emb["Local MiniLM embedder (ONNX)"]
    Miru["Miru hybrid search: BM25 + vectors"]
    RIF["Kalpana RIF: tree-sitter roles -> HRR tensors"]
    Cut["Adaptive cutoff: 1-3 chunks"]
    Worker["Index worker (child process)"]
    Store[("~/.kalpana-context/indexes")]
  end
  Repo[("Your repository")]

  LLM <--> Host
  Host <-->|"JSON-RPC over stdin/stdout"| MCP
  MCP --> Proj --> Miru
  Miru --> RIF --> Cut --> MCP
  Miru <--> Emb
  RIF <--> Emb
  Worker -->|"first use / reindex"| Store
  Repo --> Worker
  Store --> Miru
  Worker <--> Emb

Only the 1–3 returned chunks ever reach the agent, and through it the cloud LLM. The repository, the index and the embeddings stay on your machine.

What happens on one search

sequenceDiagram
  participant A as Agent
  participant S as kalpana-context
  participant M as Miru index
  participant K as Kalpana RIF
  A->>S: code_search("where are changesets cast?")
  S->>S: resolve project, re-index changed files if needed
  S->>M: hybrid search (BM25 + MiniLM), top-5
  M-->>S: 5 candidate chunks + scores
  S->>K: tree-sitter (role, identifier) pairs -> tensors -> structural scores
  K-->>S: fused = 0.3 x Miru + 0.7 x Kalpana (min-max normalised)
  S->>S: keep chunk i while fused[i] >= 0.6 x fused[0] (1..3)
  S-->>A: 1-3 chunks with path:start-end and code

How it works

agent ──code_search("where are changesets cast?")──▶ kalpana-context
   1. Miru hybrid search (BM25 + MiniLM vectors) → top-5 candidates
   2. Kalpana RIF: tree-sitter (role, identifier) pairs → HRR tensors → structural score, fused with Miru's
   3. Adaptive cutoff: send 1 chunk when the winner is clear, up to 3 when it isn't
agent ◀── 1–3 chunks with file path + line range

Choosing the project

The server picks the project in this order:

1. the project argument on a tool call

2. --project <dir> or KALPANA_PROJECT

3. the workspace folder the agent reports (MCP roots)

4. the current directory

The first search in a new project starts indexing in the background. That takes a few minutes for a medium repo. After that, changed files are re-indexed incrementally. Indexes are stored in ~/.kalpana-context/, or wherever KALPANA_HOME points.

Tools

Options

--mode rifad|rif|miruad|miru (default rifad), --tau 0.6, --alpha 0.7, --max 3

Evidence (honest version)

Agent benchmark. 40 code-localization tasks on Ecto (Elixir, doc comments stripped), agent model gemini-3.5-flash-lite, 12-step cap. Every arm had the same tools except code_search.

• Against grep-only, the default solved 14 tasks the baseline missed and failed 3 the baseline solved (p = 0.013, sign test).

• Most of the token saving comes from search plus the adaptive cutoff. RIF's extra over Miru + cutoff was small (6 tasks won, 4 lost) and is not statistically significant on 40 tasks.

• Retrieval benchmarks (from the Miru_Discrete_RIF research repo): RIF raised Chunk@3 from 54.8% to 59.8% on kubernetes/client-go (500 queries, p = 0.0001).

• Limits: one repo, one model, localization tasks only. Tau was tuned on the same corpus.

Parity. The TypeScript RIF in this package reproduces the original Python implementation exactly: identical rankings and adaptive cutoffs on 228 of 228 benchmark queries.

Troubleshooting

Run from source

git clone https://github.com/maduperera/Kalpana_MCP && cd Kalpana_MCP
npm install
node bin/kalpana-context.mjs --project /path/to/repo           # run the server
node test/smoke.mjs /path/to/repo "what you are looking for"   # end-to-end test as an MCP client

In an agent config, point command at node and args at the absolute path of bin/kalpana-context.mjs.

Uninstall

Remove the kalpana-context entry from your agent's MCP config and delete ~/.kalpana-context/ (the indexes).

Credits and licence

MIT © Madusha Perera. Miru is © Takara (MIT) and is used unmodified as a dependency; see NOTICE.md. This project is not affiliated with Takara and does not use Takara's DS1 model or API.