Skip to main content
Glama
cprepos

fsq-codebase

by cprepos
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

fsq-codebase

Zero-config codebase indexer with FSQ embeddings for fast semantic code search. Why Finite Scalar Quantization to compress? Because nobody has tried it before, that's why. Also FSQ still loosely maintains the shape of the vector and does not need a codebook, in case I ever wanted to round trip the embeddings back to code (for example for previewing purposes, like a jpg thumbnail).

Features

  • Fast semantic search: 10x compression with int8 embeddings, 2.7x faster search

  • Multi-language: Python, JavaScript, TypeScript, Go, Rust, Java, and more

  • Zero-config: Just point at a directory and search

  • MCP server: Claude Code integration via Model Context Protocol

Related MCP server: Claude Context Local

Installation

Work in progress. For now you would need to build the model yourself. ANd

Quick Start

Python API

from fsq_codebase import CodebaseIndex, FSQEmbedder

# Index a codebase
index = CodebaseIndex.create("./my-project")
results = index.query("add rate limiting", top_k=10)
print(results.tree())

# Or use the embedder directly
embedder = FSQEmbedder.from_bundled("codet5plus-96d")
embeddings = embedder.encode(["def hello(): pass", "function greet() {}"])

MCP Server (Claude Code)

# Start the MCP server
fsq-codebase --index ./codebase.index

Configure in Claude Code's .mcp.json:

{
  "mcpServers": {
    "fsq-codebase": {
      "command": "fsq-codebase",
      "args": ["--index", "./codebase.index", "--verbose"]
    }
  }
}

Bundled Models

Model

Encoder

FSQ Dim

Size

codet5plus-96d

CodeT5+ 110M

96

268 KB

unixcoder-96d

UniXcoder

96

652 KB

The encoder (CodeT5+ or UniXcoder) downloads automatically from HuggingFace on first use (~440MB).

Performance

Compared to CodeT5+ baseline on CoIR benchmark:

Model

MRR

Storage

Search Speed

CodeT5+ baseline

0.9699

1024B

0.39ms

fsq-codebase

0.9706

96B

0.14ms

10.7x compression with 2.7x faster search while maintaining accuracy.

License

MIT

Available Tools

3 tools
codeinfuseA

INTERACTIVE code context search. First call (selection=0): Returns numbered list of matches. CRITICAL: After first call, you MUST IMMEDIATELY call AskUserQuestion to let user pick a number - DO NOT skip this step or pick for them. Second call (selection=N): Returns full context for selection N. User selections are logged for training data.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesNatural language description of what you want to do
top_kNoNumber of results to show (default 10)
selectionNoUser's selection (1-N). If 0 or omitted, shows search results list.

TDQS

A4.8/5.0
Behavior5/5

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

With no annotations, the description fully discloses the interactive behavioral traits: the two-phase execution, mandatory user judgment call, and data logging for training purposes. No contradictions with non-existent annotations.

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?

Four essential sentences: states purpose, explains first call, issues a critical warning with mandatory action, describes second call and logging. No wasted words, well front-loaded.

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 tool's interactive complexity and lack of output schema, the description covers the core workflow, mandatory user interaction, and logging. Could elaborate slightly on return format details, but sufficient for effective use.

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?

Schema coverage is 100% with adequate parameter descriptions. The description adds critical context on how the 'selection' parameter controls the two-step flow and that 'query' is a natural language description, but does not introduce new parameter-level meaning beyond the 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 'INTERACTIVE code context search', specifies a two-step interaction (first call returns numbered list, second call returns full context), and distinguishes from siblings like 'search_code' by emphasizing the interactive user-driven selection process.

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

Usage Guidelines5/5

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

Provides explicit step-by-step instructions: first call with selection=0, then MUST call AskUserQuestion, then second call with selection=N. Warns against skipping or picking for the user, ensuring correct usage.

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

extract_code_contextA

Get code context for a specific entity (from search_code results). Returns signatures of function/class with callers and callees. Use entity_id from search_code results for precise targeting.

ParametersJSON Schema
NameRequiredDescriptionDefault
entity_idYesEntity ID from search_code results (REQUIRED)
signatures_onlyNoReturn only signatures (default True, set False for full code)
include_externalsNoInclude external package dependencies

TDQS

A4.2/5.0
Behavior3/5

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

No annotations provided, so description carries full burden. It describes returns (signatures with callers/callees) but does not state non-destructive nature, error behavior, or side effects. Adequate but could be more explicit.

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?

Two sentences, no fluff, front-loaded with main action. Every word earns its place.

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 3-parameter tool with no output schema, the description covers purpose, parameter usage, and return. Could mention error handling or return format details, but is largely sufficient.

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?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that entity_id comes from search_code and that signatures_only=False returns full code, going beyond 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 it gets code context for a specific entity, returns signatures with callers and callees, and explicitly ties usage to search_code results, distinguishing it from siblings.

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?

Specifies that entity_id should come from search_code results, giving clear context. Does not explicitly mention when not to use, but the reference to sibling tools implies it's for post-search targeting.

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

search_codeA

Search codebase for relevant functions/classes. Returns top matches with IDs. ALWAYS use this first to find candidates, then use AskUserQuestion to let user pick. After user selects, use extract_code_context with the entity_id.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesNatural language search query
top_kNoNumber of results (default 10)

TDQS

A3.9/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 burden of behavioral disclosure. It mentions returning top matches with IDs but does not elaborate on any behavioral traits such as rate limits, destructive actions, or authentication needs. The description is minimal on behavioral context.

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 with three sentences. It front-loads the purpose and then provides actionable workflow instructions. No wasted words.

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?

Given there is no output schema, the description should explain the return value more thoroughly. It states 'Returns top matches with IDs' but does not specify the structure or details of matches. For a search tool with complex returns, this is incomplete.

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?

Schema coverage is 100%, so baseline 3. The description adds the workflow context but does not provide additional semantics beyond what the schema already describes for the parameters. Parameters are adequately covered by the 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 it searches the codebase for functions/classes and returns top matches with IDs. It distinguishes from sibling tools by describing a workflow: use this first, then AskUserQuestion, then extract_code_context.

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

Usage Guidelines5/5

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

The description provides explicit usage guidance: 'ALWAYS use this first to find candidates, then use AskUserQuestion to let user pick. After user selects, use extract_code_context with the entity_id.' This clearly indicates when to use this tool and what to do next.

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

A3.7/5.0
Disambiguation2/5

codeinfuse and search_code both return search results and involve user selection, creating overlap and ambiguity about which to use. extract_code_context is distinct but depends on search_code.

Naming Consistency2/5

The tool names are inconsistent: codeinfuse is a single word (camelCase?) while extract_code_context and search_code use snake_case and follow a verb_noun pattern. This inconsistency reduces clarity.

Tool Count4/5

3 tools is a reasonable minimal set for a codebase search and context retrieval server. Each tool serves a distinct step in the workflow, so the count feels appropriate.

Completeness3/5

The tools cover search, user selection, and context extraction, but missing a direct context retrieval by known ID without prior search. This is a minor gap.

Maintenance

ActivityInactive
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

  • AutoDev Codebase MCP Server

    anrgct
    F
    license
    Not graded
    quality
    B
    maintenance
    HTTP-based server that provides semantic code search capabilities to IDEs through the Model Context Protocol, allowing efficient codebase exploration without repeated indexing.
    3
    120

  • Claude Context Local

    FarhanAliRaza
    F
    license
    Not graded
    quality
    D
    maintenance
    Provides semantic code search capabilities that run 100% locally using EmbeddingGemma embeddings. Enables finding code by meaning across 15 file extensions and 9+ programming languages without API costs or sending code to the cloud.
    236

  • CodeGrok MCP

    dondetir
    A
    license
    Not graded
    quality
    F
    maintenance
    Enables semantic code search for AI assistants by indexing codebases with embeddings and Tree-sitter, returning relevant snippets via natural language queries.
    15
    MIT

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/cprepos/codeinfuse'

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