artk0de/tearags-mcp

TeaRAGs 🦖🍵

Codebase Intelligence layer for AI coding agents Trajectory Enrichment-Aware RAG · served over MCP · 100% local

---

Your coding agent copies the first code it finds — not the right one.

TeaRAGs is a Codebase Intelligence layer your agent queries over MCP. It indexes the repository on your machine into five layers — three that read the code and two that judge its interfaces:

• 🔍 What it does — semantic and hybrid search over AST-aware chunks
• 🕸️ How it is connected — callers, callees, fan-in, transitive impact
• 🧬 How it has lived — churn, bug-fix rate, ownership, age
• 🏛️ Whether it is laid out right — dependency direction, leaking facades, files that change together with no edge between them
• 🔤 What the project calls things — the naming vocabulary, inferred from the call graph, and a verdict on every new name

The first three layers and why an agent needs all of them at once are laid out in Codebase Intelligence для агента (Habr, in Russian).

TeaRAGs also ships agent skills that know which layer a task needs. The agent stops guessing which code is safe to copy, what is critical, and what a change will break — it reads the dossier instead.

📖 Documentation · 🏁 15-minute quickstart · 🧠 Core concepts

👀 See It

Three questions an agent asks before touching code, answered by TeaRAGs on its own repository. Every number below is a real response, trimmed.

1. “Find retry logic I can reuse”

semantic_search { query: "retry a failed request with exponential backoff", rerank: "hotspots" }

Similarity alone puts OllamaEmbeddings#retryWithBackoff first. The dossiers of the top two candidates tell different stories:

The closest match keeps getting fixed. The agent copies the quiet helper’s shape — or learns why the first one keeps breaking before it repeats the mistake.

2. “What is risky to touch around vector writes?”

semantic_search { query: "write points to the vector database in batches", rerank: "dangerous" }

Similarity alone ranks PointsAccumulator#flushBatch, QdrantPointStore#addPointsOptimized and QdrantPointStore#addPoints first. The dangerous preset reorders by risk and says why:

3. “Who calls it before I change it?”

get_callers { symbolId: "QdrantManager#addPointsWithSparse" }

Ten exact call sites across eight files — method fan-in 10 · central, file transitive impact 47 · regional:

ChunkPipeline#createBatchHandler          ingest/pipeline/chunk-pipeline.ts
createQdrantPipeline                      ingest/pipeline/pipeline-manager.ts
storeIndexingMarker (2 sites)             ingest/pipeline/indexing-marker.ts
DocumentOps#add                           api/internal/ops/document-ops.ts
SchemaManager#storeSchemaMetadata         adapters/qdrant/schema-manager.ts
EmbeddingModelGuard#readOrCreateMarker    adapters/qdrant/embedding-model-guard.ts
IndexStoreAdapter#storeSchemaVersion      maintenance/migration/adapters/index-store-adapter.ts
SparseStoreAdapter#rebuildSparseVectors   maintenance/migration/adapters/sparse-store-adapter.ts
SparseStoreAdapter#storeSparseVersion     maintenance/migration/adapters/sparse-store-adapter.ts

Need the whole chain from an entry point to this call? trace_path enumerates every A→B path and, with a rerank preset, sorts them by how dangerous each step is.

❓ What It Answers

Ask in plain language. The plugin picks the skill, tools and rerank presets for every question automatically — it ships a decision table that maps intent to the right call, so nobody has to know a preset name. Other MCP clients get the same routing guide as an MCP resource (tea-rags://schema/search-guide).

One question per layer, most distinctive first. Every number is a real response on TeaRAGs’ own repository.

1. 🏛️ “Is this codebase laid out correctly?”

/tea-rags:architecture-diagnostics → get_architecture_report

Four detectors judge the borders between modules, not the risk of touching them. Each violation carries the file edges or commits that prove it, grouped into root causes:

A component is a module with a facade, or a plain directory when there is none. The facade-adoption and coupling-strength cut-offs are derived from the repository itself (Otsu), so the same report reads a small library and a monolith without tuning.

2. 🔤 “Do the names in my diff speak the project’s language?”

review_changes { changes: { base: "main" }, sections: ["naming"] } — also step D8 of /tea-rags:mr-review and the last check of /tea-rags:data-driven-generation

The project’s vocabulary is read from its call graph: how values of each type are named, which role word each directory gives its types, which word the project already uses for a concept. Only declarations on added lines are judged, and the changed files are left out of the evidence, so a diff never confirms itself:

Verdicts are CONFORMS, MISFIT with a suggestion, NEW_TERM with the project’s closest terms, and COLLISION for a name already taken elsewhere. The rules are checked against the project’s own history: every type rename a commit message records is a case the tool must flag. get_ontology_report audits the whole vocabulary — synonyms, homonyms, outliers.

3. 🧬 “We have four payment-gateway retries. Which one should I copy?”

semantic_search with proven — /tea-rags:data-driven-generation runs it as its template step

Similarity finds all four; history decides. proven ranks long-lived, low-bug-rate, multi-author code first, and every result carries its dossier — commits, bug-fix share, age, owners — labelled against this repository’s own percentiles. The closest match by text is often the one fixed every sprint; see See It → 1 for a real pair.

4. 🕸️ “How does a request get from the API to the card charge, and which step is riskiest?”

trace_path with dangerous — get_callers for a single hop

Every call path between the two symbols, resolved from the call graph rather than guessed from names, with each step ranked by how risky it is to touch. An ambiguous call is reported as ambiguous, never picked at random. See See It → 3 for the ten call sites of a real write path.

5. 🔍 “Where do we charge a bill with a saved card?” — when the code says invoice

hybrid_search — dense vectors for the meaning, BM25 for exact names

The code is chunked on AST boundaries, so a result is a whole method with its class, not a window of N lines. Search by meaning crosses the vocabulary gap between the question and the code; BM25 still pins an exact identifier when the question names one.

✨ Features

• 📈 Git- and codegraph-aware ranking — 23 rerank presets blend churn, bug-fix rate, ownership and age with fan-in, PageRank and transitive impact (proven, hotspots, techDebt, blastRadius, criticalPath, …), plus 12 filter presets
• 🕸️ Call graph — callers, callees, cycles and A→B paths (get_callers, get_callees, find_cycles, trace_path) for TypeScript, JavaScript, Ruby, Swift and Python at a high tier
• 🏛️ Architecture report — Stable Dependencies at component level, imports that leak past an adopted facade, files that change together with no edge between them, and distance from the main sequence (get_architecture_report)
• 🔎 Change review — one call over a working-tree change or a branch: names off the project vocabulary, co-change partners the change left untouched, per-file cohesion, and new edges that break architecture boundaries (review_changes)
• 🔤 Naming review — the project’s vocabulary inferred from the call graph: verdicts on value and type names, the project’s own word for a synonym, a review of every name a diff declares (review_changes), and a whole-code audit of synonyms, homonyms and outliers (get_ontology_report)
• 🧠 Agent skills — the plugin routes every question to the right tools and presets on its own; 15 ready-made workflows (explore, bug-hunt, risk-assessment, data-driven-generation, mr-review, …) plus dinopowers, 10 wrappers that feed index signals into superpowers
• 🔒 100% local — embedded Qdrant and DuckDB, no Docker; embeddings through Ollama — on the laptop or on any machine in your network, with the laptop as an automatic fallback (see Embedding providers) — with OpenAI, Cohere and Voyage optional
• 🔄 Always fresh — incremental reindex, auto-update on a target branch, per-worktree index clones, and a drift report that names the exact command to run
• 🏢 Built for enterprise monorepos — AST chunking for 9 languages, parallel pipelines, validated on a 3.5M-line production monolith

📦 Installation

💻 System requirements

Disk taken by real indexes (turbo quantization, dense + sparse vectors):

The call graph grows with the code; the vector index much less — a codebase five times smaller still takes 1.2 GB.

Pull the code-embedding model:

ollama pull unclemusclez/jina-embeddings-v2-base-code:latest

Claude Code — plugins plus a setup wizard that detects your hardware and tunes the pipeline:

/plugin marketplace add artk0de/TeaRAGs-MCP
/plugin install tea-rags-setup@tea-rags
/tea-rags-setup:install
/plugin install tea-rags@tea-rags

Any MCP client (Cursor, Roo Code, Continue, …):

npm install -g tea-rags

{
  "mcpServers": {
    "tea-rags": {
      "command": "tea-rags",
      "args": ["server"]
    }
  }
}

Qdrant downloads and starts on first use. Cloud embeddings (OpenAI, Cohere, Voyage), an external Qdrant, and the built-in ONNX provider (beta) are covered in the installation guide.

🕸️ The call graph

The call graph is on by default. To index a project without it, set CODEGRAPH_ENABLED=false for that run, or pin it on an indexed project:

tea-rags projects set-env --name  CODEGRAPH_ENABLED=false

The flag is recorded per project, so later runs from the CLI, the MCP server or auto-update keep each project’s choice. Projects indexed while the call graph was opt-in keep the state they were indexed with; turn it on for one with CODEGRAPH_ENABLED=true in the same command. Details: Codegraph Enrichments.

🚀 Quick Start

tea-rags index-codebase /path/to/repo --name myrepo   # first index: register + index
tea-rags prime /path/to/repo                          # index state, drift, signal thresholds

In Claude Code, /tea-rags:index does the same. Then ask your agent:

• “How does auth work in this project?”
• “Find stable examples of retry logic I can copy.”
• “What breaks if I change the payment module?”

🤔 Why TeaRAGs?

🆚 Compared to other tools

TeaRAGs is not a coding agent. It is the context layer an agent queries, so the closest comparisons are the tools that hand a codebase to an LLM. Every competitor cell links to that product’s own documentation, checked on 2026-09-23; “—” means the capability is not in those docs.

Two names that usually come up here changed shape. Cody Free and Cody Pro shut down on 2025-07-23 (Sourcegraph); Cody Enterprise continues and uses Sourcegraph Search as its context source, which is why it shares the Sourcegraph row. GitHub ended the Copilot Workspace technical preview on 2025-05-30 (GitHub Next).

A wider table against other MCP code-search servers (claude-context, serena, grepai, …) lives in the comparison guide.

⚙️ How It Works

%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#fdf8e7", "primaryTextColor": "#2d2d2d", "primaryBorderColor": "#d4af37", "lineColor": "#c4941f", "secondaryColor": "#f5f5dc", "tertiaryColor": "#fafafa", "mainBkg": "#fdf8e7", "secondBkg": "#f5f5dc", "nodeBorder": "#d4af37", "clusterBkg": "#fffdf6", "clusterBorder": "#d4af37", "titleColor": "#2d2d2d", "edgeLabelBackground": "#ffffff", "fontSize": "15px"}}}%%
flowchart LR
    User([👤 You])
    Agent[🤖 Coding agent+ TeaRAGs skills]

    subgraph pkg["🍵 tea-rags"]
        MCP[🔌 MCP server28 tools]
        CLI[⌨️ CLIindex · prime · projects · auto-update]
        Core[⚙️ Corechunk · enrich · search · rerank]
        MCP --> Core
        CLI --> Core
    end

    subgraph storage["💻 Local storage"]
        Qdrant[(🗄️ Qdrantembedded · vectors + signals)]
        DuckDB[(🦆 DuckDBembedded · call graph)]
    end

    Embeddings[✨ EmbeddingsOllama · OpenAI · Cohere · Voyage]
    Repo[📁 Your repocode + git history]

    User  Agent
    Agent  MCP
    User --> CLI
    Core  Qdrant
    Core  DuckDB
    Core --> Embeddings
    Core --> Repo

Your agent calls TeaRAGs over MCP; you run the CLI to index and maintain. Both drive one core: it chunks code on AST boundaries, embeds each chunk, attaches git and call-graph signals, and ranks results by the preset the task asks for. Qdrant and DuckDB run embedded under ~/.tea-rags — no Docker, no servers to manage.

⚡ Indexing Speed

Measured on a production monolith — 3.3M lines of Ruby and TypeScript, tests included, plus 162K lines of docs in ~34k files — and on TeaRAGs itself. Search is available as soon as the embeddings are stored; git and call-graph enrichment keep filling in behind it.

¹ Ollama on a LAN mini-PC with an AMD RX 7800M eGPU (ROCm), measured 2026-09-27. Ollama 0.34.4 (auto-updated from 0.24.0 that day) embeds one chunk per GPU pass through a single llama-server slot, which keeps the GPU about 55% busy — expect roughly a quarter to a third faster once that is fixed. Direct support for the llama.cpp server, as an alternative to Ollama, is coming soon.

For scale: in January 2026, on the smaller monolith of the time, the server TeaRAGs was forked from needed 4–10 hours for a full index and 40+ minutes to catch up on 100 commits.

Why it is fast. Every stage runs in parallel: 50 files in flight, tree-sitter parser and git-blame worker pools, GPU batches of up to 512 chunks, and the call graph in its own DuckDB process under a hard 2 GB memory cap, with SCC and PageRank computed as streams. Embeddings dominate a full rebuild, so a change to git or call-graph signals is recomputed with --force-enrichments without re-embedding a single chunk — minutes instead of a full reindex. Each run picks its embedding batch size and concurrency itself — backing off when the server fails on a batch, climbing toward the fastest measured size, remembering the result per endpoint — within bounds that tea-rags tune measures for your hardware in about 90 seconds; details in Performance Tuning.

📏 Measured

Call-graph quality is checked against independent oracles, not eyeballed.

¹ About two thirds of the TypeScript gap is callbacks passed through props and dependency injection — the type checker names a function type there, not an implementation, so no static resolver can pin those edges.

The Python oracle harness ships in the repo (scripts/py-codegraph-jedi-oracle.ts), so those numbers can be reproduced on your own corpus.

Languages Compatibilities

MCP clients

Every language above works the same way in every client — the client only decides how much of the tooling on top of the MCP server you get.

Embedding providers

Set EMBEDDING_PROVIDER; EMBEDDING_MODEL overrides the default model.

Throughput per provider and how to choose: Embedding Providers.

Ollama on another machine, the laptop as the fallback. Ollama does not have to run where the agent does. Put it on any computer in your local network — a desktop GPU, a home server, a spare Mac — and keep the laptop’s own GPU or Apple chip as the fallback. TeaRAGs switches to the fallback when the primary stops answering or fails three embed calls in a row, and switches back once the primary is healthy again. Your code and index stay on the laptop; only chunk text crosses your own network.

EMBEDDING_BASE_URL=http://gpu-box:11434        # primary: any machine on your LAN
EMBEDDING_FALLBACK_URL=http://localhost:11434  # fallback: the laptop itself

Details: Ollama provider.

Embedding model comparison

Measured on one GPU host and three code corpora (TypeScript, two Ruby); quality is dense MRR on 200 identifier-free natural-language queries per corpus.

Models of 1.5B–7B parameters gain mostly at R@1 and run 15–110× slower: every model finds the target in the top 10 on 99–100% of the TypeScript queries, and an agent reads the whole top-10 page. Which model to pick: Embedding model choice; the method and all tables: Embedding model comparison.

⌨️ CLI

🙋 FAQ

How is this different from Aider or Copilot? Those are coding agents; TeaRAGs is what an agent asks before it writes. It indexes the repository once, keeps the index fresh, and answers over MCP with code plus its history and call graph. Any agent that speaks MCP can use it. See Compared to other tools.

Does it need the cloud? No. Qdrant and DuckDB run embedded under ~/.tea-rags, and the default embeddings come from a local Ollama (or the built-in ONNX runtime), so code never leaves your machine. The network is used to download the Qdrant binary on first run and for a cached npm version check in tea-rags prime. OpenAI, Cohere and Voyage are opt-in.

How big a repository can it handle? The largest measured index is a production monolith of 3.3M lines of Ruby and TypeScript, tests included: ~34k files, 175k chunks, 2.0 GB of vectors and ~460 MB of call graph (see System requirements). After the first run, reindexing is incremental — only changed files are re-embedded.

Which languages are supported? Nine languages get AST chunking and a call graph of varying depth: TypeScript, JavaScript, Ruby, Python, Swift, Go, Java, Rust and Bash. Markdown is chunked by heading; SQL and JSON fall back to plain character chunks. Per-language depth is in Languages Compatibilities.

How accurate are the git signals? They are read from your real history; the one heuristic is bug-fix detection. A commit counts as a bug fix when its message says so (fix:, [Bug], TICKET-123 Fix …, fixes #123) or it arrived through a merged fix/, hotfix/ or bugfix/ branch; “fix typo”, “fix lint” and similar are excluded. Chunk-level history follows each chunk’s lines through diff hunks and looks back 6 months by default (12 for file level); files over 5,000 lines get file-level signals only. Labels such as high or concerning are percentiles of your own repository, and signals backed by only a few commits are dampened before they affect ranking.

📚 Documentation

📝 From the Blog

Engineering notes behind the releases, each with the corpus it was measured on — all posts · RSS.

• Why this blog exists — 2026-08-19

⭐ Star History

🤝 Contributing

See CONTRIBUTING.md for workflow and conventions.

🙏 Acknowledgments

Started as a fork of mhalder/qdrant-mcp-server — clean architecture, solid tests, open-source spirit — and its ancestor qdrant/mcp-server-qdrant. Code vectorization inspired by claude-context (Zilliz).

Feel free to fork this fork. It’s forks all the way down. 🐢

⚖️ License

MIT — see LICENSE. Brand policy in BRAND.md.