Skip to main content
Glama
azraf122312

CodeRAG

by azraf122312
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

RepoSage — agentic code-Q&A over a codebase

Ask a repository questions in natural language — "where is auth handled?", "what breaks if I change this function?", "show every caller of X" — and get answers grounded in real source, with file:line citations.

RepoSage exists because generic RAG ("chat with your PDF") fails on code: fixed token-window chunking cuts functions in half, and pure vector search ignores the call graph that actually connects code. RepoSage treats retrieval quality as the engineering problem and is exposed as an MCP server, so it plugs straight into Claude Code / Cursor.

Retrieval pipeline

repo ─► AST-aware chunking ─► hybrid index ─► fusion ─► cross-encoder ─► graph ─► cited
        (function/class/        (dense +       (dense +   rerank         expand    answer
         method units,           BM25)          BM25)     (top pool)     (1-hop)
         calls + imports)

  • AST-aware chunking — one chunk per function / method / class (never a half-function), plus the calls and imports each definition makes. Zero-dependency (ast stdlib); tree-sitter multi-language is a v2 backend.

  • Hybrid retrieval — dense embeddings + BM25 lexical, min-max normalized and fused with a tunable alpha. Beats either alone on code.

  • Cross-encoder rerank — retrieve a wide pool via fusion, then reorder it with a (query, code) cross-encoder for precision (the standard "retrieve wide, rerank precise" second stage). Toggleable; see the eval for its measured, honest effect.

  • Call-graph expansion — after search finds the best definition, walk one hop along the call graph to pull in what it calls / what calls it. This is the signal generic RAG cannot provide, and it's what makes impact questions answerable.

  • Graceful degradation — if sentence-transformers isn't installed, dense retrieval falls back to a deterministic hashed embedding so the whole system still runs end-to-end on a fresh machine.

Related MCP server: OpenCodeHub MCP Server

MCP tools

Tool

Purpose

index_repo(path)

AST-ingest a repo and build/persist the hybrid index

status()

Index size + active embedding backend

search_code(query, k, hybrid)

Ranked definitions with per-signal scores

get_context(query, k, expand_graph)

Cited context bundle for answering

impact_radius(chunk_id)

Blast radius — who calls this definition

Quickstart

uv venv --python 3.12 .venv           # standard CPython (not free-threaded)
uv pip install -e .                    # core: mcp + rank-bm25 + numpy
uv pip install -e ".[embeddings]"      # optional: real semantic embeddings

Register with Claude Code (from this directory):

claude mcp add reposage -- .venv/Scripts/python.exe -m reposage.server

Then in Claude Code: "index this repo with reposage, then ask where auth is handled."

Evaluation

The differentiator is eval/ — labeled, auditable question sets with an ablation that shows what each layer buys. Two corpora: Flask (pallets/flask, 404 chunks, external — the fair test) and this repo's own src/ (53 chunks, dogfood). Every gold label and call edge is verified against the actual source, not guessed.

# Flask (clone once, then run):
git clone --depth 1 https://github.com/pallets/flask .corpora/flask
python -m eval.run --dataset flask

python -m eval.run                    # dogfood on ./src
python -m eval.run --repo PATH        # any repo (with a matching dataset)

Primary result — Flask (19 questions, 404 chunks, equal 8-result budget)

Config

hit@8

MRR

vector-only

0.79

0.563

+ BM25 fusion

0.89

0.576

+ cross-encoder rerank

1.00

0.680

+ graph expansion

0.84

0.568

By category (hit@8):

Category

vector

+ BM25

+ rerank

+ graph

semantic

0.88

0.88

1.00

0.75

keyword (exact identifiers)

1.00

1.00

1.00

1.00

impact

0.40

0.80

1.00

0.80

What the numbers actually say (the honest read, not a rigged monotonic table):

  • The cross-encoder reranker is the big win — on a real corpus. It lifts hit@8 from 0.89 → 1.00 and MRR +0.10, helping both semantic (0.88→1.00) and impact (0.80→1.00). Crucially, the same reranker was a wash on the 53-chunk dogfood corpus (see below) — because a tiny corpus has too few distractors for reranking to matter. The lesson: you cannot fairly evaluate a reranker on a toy corpus. Running both corpora is what surfaced that.

  • BM25 fusion pays off on the queries it should — it takes impact queries from 0.40 → 0.80 (exact symbol names) and lifts overall hit to 0.89. Dense handles paraphrase; BM25 handles literal identifiers; fusion gets both.

  • Graph expansion does not improve ranking — it slightly hurts it (0.89 → 0.84, semantic 0.88 → 0.75), and that's reported rather than hidden. Fusing graph neighbors into the ranked list displaces real hits. The call graph is a context-enrichment / impact-analysis feature, not a ranking-fusion layer — so it's evaluated on its own job instead:

Call-graph quality (Flask) — 8 hand-verified in-repo call edges:

Metric

Value

caller-recall

1.00

avg callers/node (noise proxy)

3.12

The AST-derived graph recovers every labeled caller edge — which is what makes impact_radius trustworthy on real code.

Secondary — dogfood on own src/ (18 questions, 53 chunks)

Config

hit@8

MRR

note

vector-only

0.78

0.452

+ BM25 fusion

0.89

0.615

+ cross-encoder rerank

0.89

0.618

flat — corpus too small to test rerank

+ graph expansion

0.94

0.622

Kept deliberately: the contrast between "rerank is a wash" here and "rerank wins" on Flask is the finding. Small-corpus metrics are also saturated, so treat them as directional only.

Raw metrics: eval/results_flask.json, eval/results.json.

Status

v0.1 — pipeline + MCP server working end-to-end; real embeddings (all-MiniLM-L6-v2) + cross-encoder rerank (ms-marco-MiniLM-L-6-v2) wired; 4-stage eval ablation on two corpora (Flask + dogfood) with call-graph metrics; 9 pipeline tests passing. On Flask the reranker reaches hit@8 = 1.00. Next: a code-domain reranker, smarter graph-aware context assembly, and tree-sitter for non-Python repos.

Available Tools

5 tools
get_contextA

Retrieve a ready-to-cite context bundle for answering a question.

Returns the source of the top matches (reranked by a cross-encoder when rerank=True, plus one-hop call-graph neighbors when expand_graph=True) with file:line citations, so the client model can answer grounded and cite spans.

ParametersJSON Schema
NameRequiredDescriptionDefault
kNo
queryYes
rerankNo
expand_graphNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden and does an excellent job. It discloses the return format (source of top matches, file:line citations), and explains the effects of rerank=True and expand_graph=True, offering rich behavioral insight beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise at two sentences, front-loads the purpose, and then efficiently explains return behavior and flag effects. No filler or redundant information is present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value details need not be over-explained. The description covers purpose, key flags, and citation output, but omits k semantics and any usage prerequisites, leaving minor gaps for a no-annotation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, so the description must compensate. It explains the semantics of rerank and expand_graph, but leaves k and query largely implicit. With four parameters, the coverage is partial, not complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Retrieve' and identifies a distinct resource: a 'ready-to-cite context bundle' for answering a question. It mentions file:line citations and reranking, which clearly differentiates it from siblings like search_code or status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states the tool is for answering a question and producing grounded, citable spans, which gives clear context for when to use it. However, it does not explicitly name alternative tools or state when not to use it, so no exclusions are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

impact_radiusA

Given a chunk id (from search results), list callers — the blast radius.

Args: chunk_id: id like 'pkg/mod.py::ClassA.method' (the qualname shown in results).

ParametersJSON Schema
NameRequiredDescriptionDefault
chunk_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It states the primary action (list callers) but does not disclose important traits such as whether callers are direct or transitive, whether results are limited to the indexed repo, or potential performance implications. This ambiguity leaves the agent guessing about blast radius scope.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is exceptionally concise: two sentences plus a one-line args annotation. It fronts the purpose and adds necessary parameter context without any fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with an output schema, the description covers invoking it correctly. It could be improved by clarifying the semantics of 'callers' (direct vs transitive), but overall it is sufficiently complete for basic use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description thoroughly explains the only parameter chunk_id, including an example format ('pkg/mod.py::ClassA.method') and its source ('from search results'). This adds significant meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: given a chunk id, list callers (the blast radius). This is a specific verb+resource that distinguishes it from sibling tools like search_code or get_context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description indicates usage context: 'from search results' and references 'the qualname shown in results', guiding when the tool is appropriate. It does not explicitly name alternatives or exclusion cases, but context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

index_repoA

Ingest a repository and build the hybrid (dense + BM25) index.

Args: path: absolute path to the repo root to index.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It states the action but does not disclose side effects, idempotency, persistence, required permissions, or whether the operation is synchronous. The mutation of the repository index is implied but not elaborated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise and front-loaded. The first sentence states the purpose, and the second documents the parameter. No unnecessary words or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (one parameter) and has an output schema, so return value documentation is not necessary. However, the description lacks guidance on when to use the tool relative to siblings, does not explain the indexing behavior (e.g., overwriting vs incremental), and omits any potential side effects or requirements. It is minimally viable but leaves gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides only the parameter name and type, but the description adds meaningful context: 'absolute path to the repo root to index.' This clarifies the expected format and purpose of the path parameter, compensating for the lack of schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function with a specific verb ('ingest') and resource ('a repository'), and specifies the output ('build the hybrid (dense + BM25) index'). This distinguishes it from sibling tools like search_code, which are for search operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies that indexing should happen before searching (given the sibling tool search_code), but it does not explicitly state when to use this tool versus alternatives. There is no direct guidance on prerequisites or ordering.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_codeA

Search the indexed codebase and return the top matching definitions.

Args: query: natural-language or keyword query. k: number of results. hybrid: True = dense + BM25 fusion; False = dense only. rerank: True = retrieve a wide pool and reorder with a cross-encoder (higher precision, slower; needs the [embeddings] extra).

ParametersJSON Schema
NameRequiredDescriptionDefault
kNo
queryYes
hybridNo
rerankNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It provides useful context on parameter behavior (hybrid mode, rerank trade-offs) and even discloses that rerank is slower and requires the '[embeddings] extra'. It does not, however, mention any side effects, permissions, or limitations beyond those parameter-specific notes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured as a docstring with a one-sentence purpose followed by a concise Args section. Every sentence earns its place, explaining each parameter without redundancy or fluff, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema, the description appropriately focuses on input parameters and behavioral specifics like speed/dependency. It covers the core functionality and parameter semantics well, but it lacks explicit prerequisites (e.g., 'repo must be indexed first') or typical error scenarios, leaving a small gap in contextual completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 0% schema description coverage, the description compensates fully by explaining every parameter: query (natural-language or keyword), k (number of results), hybrid (dense vs dense+BM25 fusion), and rerank (wide pool reordering with cross-encoder, with precision/speed trade-off and dependency). This adds significant meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Search') with a defined resource ('the indexed codebase') and a clear outcome ('return the top matching definitions'). This clearly distinguishes it from sibling tools like index_repo (indexing), status (status checks), get_context (retrieval), and impact_radius (analysis).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when you need to search code, but it does not explicitly state when to use this tool versus alternatives like get_context or impact_radius. There are no exclusions or alternative tool references, so it falls short of providing clear usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

statusA

Report index size and the active embedding backend.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. The verb 'Report' strongly implies a read-only, non-destructive operation, but it does not explicitly state side-effect-free behavior. For a simple status tool, this is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, direct sentence that front-loads the purpose. No unnecessary words or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters and an output schema available, the description fully covers the tool's purpose. The one-sentence description is complete for a status tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline is 4. There is nothing for the description to add regarding parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Report' and identifies the exact resources ('index size' and 'active embedding backend'). This clearly distinguishes it from sibling tools like 'search_code' or 'index_repo'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

While no explicit 'when to use' is stated, the description clearly implies the tool is for status checks. Given the tool name 'status' and the nature of the report, the context is clear enough, though no alternatives are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
Disambiguation5/5

Each tool targets a distinct phase of the RAG workflow: indexing, status, searching, context retrieval, and impact analysis. search_code and get_context both retrieve code, but get_context explicitly adds citations and call-graph expansion, so they are clearly separated.

Naming Consistency4/5

All names use snake_case and follow a command-like style. However, status is a bare noun rather than verb_noun, and impact_radius is a noun phrase while others start with verbs (index, search, get). Minor deviations but overall predictable.

Tool Count5/5

Five tools is well-scoped for a code RAG server: one tool to build the index, one for health/size, one for basic search, one for context-rich retrieval, and one for dependency impact. No unnecessary tools.

Completeness4/5

The core lifecycle is covered: index creation, search, context extraction, and impact analysis. Missing explicit delete/re-index or list available repositories, but these are minor gaps for a focused RAG use case.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/azraf122312/RepoSage'

If you have feedback or need assistance with the MCP directory API, please join our Discord server