Provides tools for indexing and searching code using OpenAI-compatible embedding endpoints, enabling semantic code search on local repositories.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@turbovec-mcp find where we parse the CSV file"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Local semantic code search over MCP, backed by turbovec (Google's TurboQuant: ~16x vector compression, fast on Apple Silicon). Bring your own OpenAI-compatible embeddings endpoint - nothing leaves your machine.
code -> chunker -> [your embeddings endpoint] -> turbovec index -> searchembedder: any OpenAI-compatible /v1/embeddings (a llama.cpp server, etc).
Dimension is auto-detected.
store: turbovec IdMapIndex, persisted per-repo under .turbovec/.
orchestrator: this MCP server (chunk, embed, index, search).
uvx turbovec-mcp # run directly, no install (recommended)
# or
pipx install turbovec-mcpRequires a running embeddings endpoint. Example with llama.cpp:
llama-server -m nomic-embed-text-v1.5.Q8_0.gguf --embedding --pooling mean --port 8081Related MCP server: semantic-search-mcp
var | default | meaning |
|
| OpenAI-compatible base URL |
|
| model name sent in the request |
|
| bearer token (unused locally, must be non-empty) |
| auto | prefix for documents; auto = |
| auto | prefix for queries; auto = |
|
| embedding inputs per request |
|
| embedding request timeout (seconds) |
|
| hard char cap per embedded input |
|
| turbovec quantization bits (2 or 4) |
|
| lines per chunk |
|
| overlap between chunks |
|
| skip files larger than this |
| "" | comma list of extra extensions to index |
| "" | comma list of extra dirs to skip |
With the default nomic model the prefixes auto-resolve, so a bare setup needs no env exports at all. Set the env vars (or pass another model) only for a non-nomic embedder.
With the default nomic embedder this is the whole flow - no config editing, no env exports:
# (a) run the embeddings endpoint
llama-server -m nomic-embed-text-v1.5.Q8_0.gguf --embedding --pooling mean --port 8081
# (b) register + seed file selection (writes .mcp.json AND opencode.jsonc)
turbovec-mcp init .
# (c) build the index
turbovec-mcp index .
# (d) restart your agent so it picks up the new MCP serverinit registers the turbovec MCP server into both project-local configs
automatically:
<repo>/.mcp.json (Claude Code) - merged in, other servers preserved.
<repo>/opencode.jsonc - created if absent, surgically merged if it's plain
JSON. Only an existing opencode.jsonc that contains comments is left
untouched; in that one case init prints a snippet to paste under its "mcp"
key. Your global ~/.config/opencode config is never touched.
The registered command is the absolute path to the installed turbovec-mcp
(reliable today); once published to PyPI you can use uvx turbovec-mcp instead.
Pass --no-register to seed config.json only and skip writing both config
files.
AST-aware via tree-sitter. Each function / class / method that fits the embedder becomes one chunk on clean boundaries; a god-class too large to embed whole is split into its methods; any lines not covered by a definition (imports, top-level code, a giant leaf function) are line-windowed, so coverage is total. Unsupported languages / parse failures fall back to plain line-window chunking - nothing is skipped.
Supported out of the box: Python, JS/TS/TSX, Go, Rust, Java, Kotlin, Scala,
Swift, C/C++, C#, Ruby, PHP, Lua, Perl, R, Julia, Bash, Fortran (f90/f95).
Add more file extensions with TURBOVEC_EXTRA_EXTENSIONS.
Workflow is two steps: tv_search for terse triage, then tv_fetch to read
the locations you picked.
tv_search(query, k=10, path=".") - semantic search. Terse: each hit is
score + location (path:start-end) + the chunk's signature line. No source
bodies.
tv_fetch(locations, path=".") - full source for a list of "path:start-end"
locations (the ones tv_search returned).
tv_index(path=".") - (re)build the index for a repo. Run once before
searching, and after large changes.
tv_status(path=".") - whether a repo is indexed + basic stats.
The index lives in <repo>/.turbovec/ - add it to .gitignore.
<repo>/.turbovec/config.json is the source of truth for which files get
indexed: its include / exclude glob lists decide everything. Seed it with:
turbovec-mcp init [path] # seed config + register both agents (-f to rewrite)init does two things:
Seeds <repo>/.turbovec/config.json, filling exclude from the default skip
dirs plus any nested .gitignores in the tree.
Registers the turbovec MCP server into project-local <repo>/.mcp.json
(Claude Code) and <repo>/opencode.jsonc (opencode). Both preserve any
other servers and are idempotent; pass -f to rewrite the entry. The
registered command is the absolute path to the installed turbovec-mcp.
opencode.jsonc is created if absent and surgically merged if it's plain JSON;
an existing comment-bearing opencode.jsonc is left alone and a paste-snippet
is printed instead. The global ~/.config/opencode config is never touched.
Pass --no-register to seed config.json only and skip writing both config
files.
Edit the globs, then run turbovec-mcp index.
For testing from the terminal:
turbovec-mcp init [path] # seed config + register .mcp.json + opencode.jsonc; --no-register to skip
turbovec-mcp index <path> # build/rebuild the index
turbovec-mcp status <path>
turbovec-mcp search <path> <query> [-k N] # terse: score path:lines signature
turbovec-mcp fetch <path> <location>... # full source for path:start-endBSD-3-Clause
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Versioned documentation registry and semantic search for AI tools and coding assistants.
Project memory, semantic code search, and grounded agent context.
Shared memory for coding agents. Stop re-explaining your codebase every session.
