Skip to main content
Glama
repo-index-mcp

repo-index-mcp

by Zhachory1

CodeScry is a local codebase retrieval tool for coding agents. It indexes committed code from local git repos into a local SQLite database, then exposes ranked snippets through a CLI and MCP stdio server.

Why CodeScry

  • Local-first by default: auto-selects local Ollama mxbai-embed-large when available, otherwise falls back to hash embeddings and SQLite storage.

  • Agent-ready: MCP tools for search_code, get_symbol, list_repos, and reindex.

  • Large-index aware: bounded sqlite-vec candidate paths avoid scoring every chunk once vectors are backfilled.

  • Semantic opt-in: Ollama, OpenAI, and sentence-transformers providers are available when quality matters more than default speed.

  • Measured on real repos: public agent-natural evals and ranking/performance findings live in docs/ranking-experiment-findings.md.

Recent private ~/code mxbai eval improved from ~20.7s average query latency to ~1.8s after filtered vector serving optimizations, with Recall@10 stable at 0.800. See docs/performance.md for knobs and diagnostics.

Related MCP server: Semdex

Install

Fast path:

curl -LsSf https://raw.githubusercontent.com/Zhachory1/codescry/main/scripts/install.sh | sh

The installer uses uv tool install codescry when uv is available, otherwise pipx install codescry. If neither uv nor pipx is installed, it bootstraps pipx with python3 -m pip --user.

If you prefer explicit installs:

pipx install codescry
# or, if uv is already installed
uv tool install codescry

Node users can run the npm wrapper after installing uv:

npx codescry doctor

The npm package is a thin wrapper around the Python package. It does not bundle local SQLite index data.

For development:

python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

Check local readiness:

codescry doctor

First success path

For a deterministic five-minute smoke test, see docs/getting-started.md.

Index this repo or another local git repo:

codescry index /path/to/git/repo

Query it:

codescry query "where is request retry handled" -k 5

Lookup a symbol:

codescry get-symbol RepoIndex --repo /path/to/git/repo

Discover and index every git repo under a root:

codescry index-root ~/code

Show indexed repos, stale/dirty state, and CodeScry hook coverage:

codescry status

MCP setup

Run the MCP server over stdio:

codescry serve

The MCP server answers queries only. It is not a file watcher; keep committed-code freshness by running codescry reindex or installing git hooks.

Agent config example:

{
  "mcpServers": {
    "codescry": {
      "type": "stdio",
      "command": "/Users/YOU/.local/bin/codescry",
      "args": ["--db", "/Users/YOU/.codescry/index.sqlite", "serve"],
      "env": {}
    }
  }
}

npm/npx config example:

{
  "mcpServers": {
    "codescry": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "codescry", "--db", "/Users/YOU/.codescry/index.sqlite", "serve"],
      "env": {}
    }
  }
}

Use which codescry to find the absolute command path for your machine when using direct CLI installs.

Freshness hooks

Install hooks for one repo or a repo root:

codescry install-hooks /path/to/git/repo
codescry install-hooks ~/code --recursive

Hooks run best-effort after commit/merge:

codescry --db <db> reindex "$PWD"

They preserve the selected DB path and must not fail git commands.

If hooks are not practical, run an opt-in committed-state watcher:

codescry watch ~/code/my-repo
codescry watch --once --jsonl

The watcher polls git HEAD for indexed repos or a specified repo, then reindexes committed snapshots only when the commit changes.

Docs

  • docs/getting-started.md — install to first useful query.

  • docs/mcp-clients.md — MCP config examples.

  • docs/troubleshooting.md — common setup/query/freshness issues.

  • docs/cli-reference.md — command reference.

  • docs/output-schema.md — JSON fields.

  • docs/evals.md — eval authoring and gate.

  • docs/performance.md — query/index latency knobs, candidate union, batching, and debug telemetry.

  • docs/embedding-providers.md — hash, Ollama, OpenAI, and sentence-transformers embedding providers.

  • docs/pilot.md — 5-engineer pilot measurement plan and local reporting commands.

  • docs/language-support.md — parser/regex/window support matrix.

  • docs/recipes.md — common operations.

  • docs/upgrade-uninstall.md — lifecycle commands.

  • docs/release.md — PyPI-first and npm-wrapper release flow.

  • docs/ranking-experiment-findings.md — retrieval/ranking experiments and eval findings.

Evals

The seed golden set lives in evals/golden.codescry.jsonl.

Run the eval gate:

codescry eval evals/golden.codescry.jsonl . -k 10 --fail-under 0.85

Pilot proof

Pilot task/activation/miss events are recorded in ~/.codescry/usage.jsonl without snippets. Passive query logging is opt-in with CODESCRY_ENABLE_USAGE_LOG=1. Use:

codescry pilot report

See docs/pilot.md for activation, timing, miss capture, and decision gates.

Retrieval behavior

  • Default auto embeddings use local Ollama mxbai-embed-large when available, otherwise local deterministic hash vectors.

  • Optional embedding providers include Ollama, OpenAI, and sentence-transformers. See docs/embedding-providers.md.

  • Changing embedding provider or model requires reindexing because stored vectors are model-specific.

  • Python functions/classes/methods get parser-backed symbol metadata.

  • TS/JS/Go/Java/Rust/C/C++/SQL get Tree-sitter parser-backed symbol metadata.

  • Other common declaration patterns get regex-backed symbol metadata.

  • get_symbol uses stored symbol metadata before search fallback.

  • Search blends vector, lexical, symbol, and path scores.

  • Results include stale/dirty flags.

Data boundary and safety

  • Default auto provider does not use hosted APIs. It uses local Ollama if available, otherwise local hash embeddings.

  • Default configuration does not send source code to hosted external APIs.

  • OpenAI and non-local Ollama embedding endpoints send chunks and queries outside your machine. See SECURITY.md and docs/embedding-providers.md.

  • Index data is local SQLite derived data and can be deleted/rebuilt.

  • Files matching high-confidence secret patterns are skipped and prior chunks for those paths are removed.

  • Secret skipping is a best-effort local guardrail, not a guarantee. See SECURITY.md.

Current limits

  • Python uses stdlib AST parser chunks; TS/JS/Go/Java/Rust/C/C++/SQL use Tree-sitter parser chunks; other languages use regex-backed symbol hints plus line windows.

  • Default auto embeddings prefer local semantic Ollama when available and fall back to hash embeddings otherwise; hosted semantic embeddings are opt-in only.

  • SQLite remains the default local store; large-index serving uses bounded sqlite-vec candidate paths where vector coverage exists.

  • Freshness is committed-code freshness; dirty working-tree edits are reported but not indexed.

Available Tools

4 tools
get_symbolC

Look up a symbol from indexed metadata, falling back to search.

Inputs: name (required), repo. Returns: result

list_reposA

List indexed repos and freshness state.

Inputs: no named parameters. Returns: result

reindexC

Reindex a repo. Path optional only when exactly one repo is indexed.

Inputs: repo_path. Returns: object

search_codeC

Search indexed code and return ranked snippets with file locations.

Inputs: query (required), k, repo, language, +1 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool targets a distinct operation: symbol lookup, repo listing, reindexing, and code search. No overlap in functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (get_symbol, list_repos, reindex, search_code) using snake_case. Naming is predictable.

    Tool Count5/5

    With 4 tools, the server covers the core operations for an indexed code repository without being bloated. Each tool has a clear role.

    Completeness4/5

    The tool set covers symbol lookup, code search, repo listing, and reindexing but lacks tools for adding or removing repos from the index, which is a minor gap.

    Maintenance

    ActivityInactive
    ResponsivenessMixed handling

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      A local-first codebase intelligence tool that enables AI assistants to research codebases using semantic search, multi-hop relationship discovery, and structural parsing. It allows users to extract architectural patterns and institutional knowledge across 30+ programming languages through an MCP-compatible interface.
      2
      741 PyPI
      1,464
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A local MCP server that parses codebases into semantic chunks, indexes them in SQLite with vector embeddings, and exposes MCP tools for LLM agents to query.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      An MCP server that indexes a repository locally and provides keyword, semantic, hybrid, and SQL search tools, enabling coding agents to answer questions about the codebase efficiently without reading files one by one.
      3
      94 npm
      31
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides intelligent code indexing with 15 MCP tools for symbol extraction, hybrid search (FTS5+vector), call graphs, and incremental indexing of local folders and remote repos, enabling token-efficient code retrieval for AI agents.
      3
      MIT