PocketDex MCP

A tiny local code index for AI agents, served over MCP. One Python file, no dependencies, no background server, no vectors — just SQLite FTS5.

Ask an agent "where are badge rules calculated?" and it gets a file path, a line range, and a short highlighted snippet instead of opening five files.

Why

An agent exploring a repo opens file after file, and every file costs context. PocketDex indexes the folder once, then answers search with the passage the agent needs.

Measured on a 34-file Flask app:

Index time: 0.06 s. Index size: ~0.5 MB. Query latency: 8–29 ms. (Token counts are characters / 4, an approximation.)

Related MCP server: anyindex-mcp

Why it is different

The important design choice is isolation. Each project gets its own database inside PocketDex's folder:

PocketDex/
├── pocketdex.py
├── data/projects/
│   ├── my-app-3f2a1b9c.db
│   └── other-api-7d1e0c44.db
├── tests/
└── ARCHITECTURE.md

• Nothing is written into the project being indexed.

• Two projects never share a database, so results cannot leak across them.

• Deleting a .db file removes that project's index completely.

• There is no central registry that can drift out of sync.

Override the location with --data-dir or POCKETDEX_DATA. Run from a clone, data stays in data/projects/ (gitignored). Installed as a package, it falls back to ~/.local/share/pocketdex/projects/ because site-packages is not writable.

rg is still the right tool for one known symbol. PocketDex is for exploring an unfamiliar repo without paying for whole files.

Install

There is nothing to install. Clone the repo and run it:

git clone https://github.com/sujalkumar1029-gif/pocketdex-mcp.git
cd pocketdex-mcp
python3 pocketdex.py --help

Or run it straight from Git with uv:

uvx --from git+https://github.com/sujalkumar1029-gif/pocketdex-mcp pocketdex index ~/Projects/my-app

Requirements: Python 3.10+ and SQLite built with FTS5 (standard in CPython builds).

Docker

Build the stdio server into a small image:

docker build -t pocketdex-mcp .
docker run --rm -i pocketdex-mcp

The index lives under /app/data inside the container. To keep it between runs, use a named volume:

docker run --rm -i -v pocketdex-data:/app/data pocketdex-mcp

Quick start

# index or refresh a project (incremental)
python3 pocketdex.py index ~/Projects/my-app

# search
python3 pocketdex.py search "parse_amount_cents"
python3 pocketdex.py search "badge rules" --limit 5
python3 pocketdex.py search "connect" --path-prefix src/db

# inspect every project's separate index
python3 pocketdex.py stats

# MCP server (what the agent runs)
python3 pocketdex.py serve

search without --project uses the most recently indexed project. Pass --project ~/Projects/other when several are indexed.

MCP configuration

Add this to your MCP client's config (for example ~/.gemini/config/mcp_config.json for Antigravity):

{
  "mcpServers": {
    "pocketdex": {
      "command": "python3",
      "args": ["/absolute/path/to/pocketdex.py", "serve"]
    }
  }
}

Tools exposed:

Reproduce the numbers

python3 benchmark.py ~/Projects/my-app

It indexes the folder, prints index time and database size, then measures the approximate token cost of a few queries against the total source size.

How it works

• Walks the folder, skipping .git, node_modules, .venv, dist, build output, lockfiles, hidden folders, files over 512 KB, and binaries.

• Splits files into 40-line chunks with 12 lines of overlap.

• Stores chunks in SQLite FTS5 with _ as a token character, so parse_amount_cents stays one searchable token.

• BM25 ranking, at most two results per file, snippets capped at 12 tokens of context.

• Re-indexing compares mtime_ns and size; unchanged files are skipped.

ARCHITECTURE.md explains the data model, indexing pipeline, ranking, MCP lifecycle, failure modes, and extension points.

Limits (on purpose)

• No embeddings / vector search. Keyword + prefix matching only. Code search is dominated by exact identifiers.

• No regex tool. Add one only if a real need appears.

• Small-to-medium projects. A 20–500 file range is the target; a multi-GB monorepo belongs on a dedicated search service.

• No file watching. Call index_project after large edits; unchanged files are cheap to skip.

• Plaintext index. Treat the data folder with the same care as the source it indexes.

Tests

python3 -m pip install pytest
python3 -m pytest -q

11 tests: indexing, ignored dirs, binary skip, incremental re-index, deletion, path filters, stats, per-project isolation, latest-project selection, and a real MCP stdio handshake (initialize → tools/list → tools/call).

Status

Early (0.x). The MCP contract and CLI are stable; internals may change. Issues and pull requests are welcome.

If PocketDex saves you tokens, a star helps other agent builders find it.

License

MIT — see LICENSE.