SRC (Structured Repo Context)

Transform your codebase into AI-ready context — MCP server + CLI for semantic code search that makes your code truly understandable for AI assistants

SRC is both:

• 🔌 An MCP Server — Integrates with Claude Desktop, Cursor, and any MCP-compatible AI assistant
• 💻 A Standalone CLI — Use directly from your terminal for indexing and searching

---

Table of Contents

1. Overview
2. Quick Start
3. Installation
4. MCP Tools Reference
5. CLI Reference
6. Configuration
7. Supported Languages
8. How It Works
9. Comparison
10. Troubleshooting
11. Links

---

Overview

The Problem

AI assistants struggle to understand your entire codebase:

• They only see small snippets of code at a time
• Manual copy-pasting of context is tedious and error-prone
• Keyword search misses semantic relationships between code
• Code changes get lost in conversation history

The Solution

SRC indexes your codebase into semantic, searchable chunks that LLMs actually understand:

Feature	Description
Hybrid Search	Vector + BM25 + RRF fusion for optimal results
Call Graph	Shows who calls what and what calls who
Cross-file Context	Resolves imports and path aliases automatically
Incremental Updates	SHA-256 hash detection for fast updates
50+ Languages	18 with full AST support via Tree-sitter

Use Cases

Scenario	Example Query
Code Review	"Show me all error handling in the payment module"
Debugging	"Find where user sessions are created"
Documentation	"Explain the authentication flow"
Refactoring	"List all deprecated API usages"
Onboarding	"How does the routing system work?"
Security Audit	"Find all database query locations"

---

Quick Start

1. Install Ollama

SRC requires Ollama for embeddings:

# Install from https://ollama.com, then:
ollama pull nomic-embed-text

2. Install SRC

Global installation:

npm install -g src-mcp

Or use npx:

npx -y src-mcp serve

3. Use as MCP Server (with AI Assistants)

Add to your MCP client configuration (e.g., Claude Desktop):

With global installation:

{
  "mcpServers": {
    "src-mcp": {
      "command": "src-mcp",
      "args": ["serve"]
    }
  }
}

With npx:

{
  "mcpServers": {
    "src-mcp": {
      "command": "npx",
      "args": ["-y", "src-mcp", "serve"]
    }
  }
}

The server automatically indexes the current directory if no index exists, and watches for file changes.

Then in your AI assistant:

"Search for authentication logic"
"Find error handling code with limit 20"
"Search for UserService in fts mode"

4. Use as CLI (Standalone)

# Start server (auto-indexes if needed)
src-mcp serve

# Search for code
src-mcp search_code --query "authentication"
src-mcp search_code --query "error handling" --limit 20
src-mcp search_code --query "UserService" --mode fts

# Check index status
src-mcp get_index_status

Key Arguments

Tool	Argument	Default	Description
search_code	--limit	10	Max results
search_code	--mode	hybrid	hybrid / vector / fts
index_codebase	--concurrency	4	Parallel workers
index_codebase	--force	false	Re-index if exists

---

Installation

Global Installation

npm install -g src-mcp

Then use directly:

src-mcp serve
src-mcp search_code --query "authentication"
src-mcp help

npx (No Installation)

npx -y src-mcp serve
npx -y src-mcp search_code --query "authentication"

Local Development

git clone https://github.com/kvnpetit/structured-repo-context-mcp.git
cd structured-repo-context-mcp
npm install
npm run dev

---

MCP Tools Reference

SRC exposes 5 MCP tools that AI assistants can call:

index_codebase

Index a directory with semantic chunking, AST enrichment, and embeddings.

Parameter	Type	Required	Default	Description
directory	string	No	.	Path to directory to index
force	boolean	No	false	Force re-indexing if index exists
exclude	string[]	No	[]	Additional glob patterns to exclude
concurrency	number	No	4	Parallel file processing workers

Example:

"Index the project at /home/user/myapp with concurrency 8"

Returns:

{
  "filesIndexed": 150,
  "chunksCreated": 892,
  "languages": { "typescript": 500, "javascript": 200, "json": 192 }
}

---

search_code

Hybrid search with vector similarity, BM25 keyword matching, and RRF fusion.

Parameter	Type	Required	Default	Description
query	string	Yes	—	Natural language search query
directory	string	No	.	Path to indexed directory
limit	number	No	10	Maximum results to return
threshold	number	No	—	Distance threshold (0-2, vector mode only)
mode	enum	No	hybrid	Search mode: hybrid, vector, or fts
includeCallContext	boolean	No	true	Include caller/callee information

Search Modes:

Mode	Description	Best For
hybrid	Vector + BM25 + RRF fusion	General queries (default)
vector	Semantic similarity only	Conceptual searches
fts	Full-text keyword only	Exact identifiers

Example:

"Search for 'user authentication' with limit 20"

Returns:

{
  "results": [
    {
      "content": "export async function authenticateUser(credentials)...",
      "filePath": "src/auth/login.ts",
      "startLine": 45,
      "endLine": 78,
      "symbolName": "authenticateUser",
      "symbolType": "function",
      "score": 0.92,
      "callers": [{ "name": "handleLogin", "filePath": "src/routes/auth.ts", "line": 23 }],
      "callees": [{ "name": "validatePassword", "filePath": "src/auth/crypto.ts", "line": 12 }]
    }
  ]
}

---

update_index

Incrementally update the index by detecting changed files via SHA-256 hash comparison.

Parameter	Type	Required	Default	Description
directory	string	No	.	Path to indexed directory
dryRun	boolean	No	false	Preview changes without updating
force	boolean	No	false	Force re-index all files

Example:

"Update the index with dry run to see what changed"

Returns:

{
  "added": ["src/new-file.ts"],
  "modified": ["src/auth/login.ts"],
  "deleted": ["src/old-file.ts"],
  "unchanged": 148
}

---

get_index_status

Get status of the embedding index for a directory.

Parameter	Type	Required	Default	Description
directory	string	No	.	Path to directory

Example:

"Get the index status for current directory"

Returns:

{
  "exists": true,
  "indexPath": "/home/user/myapp/.src-index",
  "totalFiles": 150,
  "totalChunks": 892,
  "languages": { "typescript": 500, "javascript": 200 }
}

---

get_server_info

Get server version, capabilities, and configuration.

Parameter	Type	Required	Default	Description
format	enum	No	text	Output format: text or json

Returns:

{
  "name": "src-mcp",
  "version": "1.0.0",
  "capabilities": ["indexing", "search", "incremental-update"]
}

---

CLI Reference

Every MCP tool is also a CLI command. You can use SRC from your terminal without any AI assistant.

General Usage

src-mcp <command> [options]
src-mcp help                    # Show all commands
src-mcp <command> --help        # Show command options

Or with npx:

npx -y src-mcp <command> [options]

Commands

# Start MCP server (auto-indexes if needed, watches for changes)
src-mcp serve
src-mcp serve --no-watch        # Disable file watcher

# Index a codebase manually
src-mcp index_codebase
src-mcp index_codebase --concurrency 8
src-mcp index_codebase --force   # Re-index even if index exists

# Search indexed code
src-mcp search_code --query "authentication"
src-mcp search_code --query "error handling" --limit 20 --mode hybrid
src-mcp search_code --query "UserService" --mode fts  # Exact keyword search

# Update index incrementally
src-mcp update_index
src-mcp update_index --dryRun   # Preview changes only

# Check index status
src-mcp get_index_status

# Server information
src-mcp get_server_info --format json

---

Configuration

Environment Variables

All settings can be configured via environment variables:

Variable	Description	Default
OLLAMA_BASE_URL	Ollama API endpoint	http://localhost:11434
EMBEDDING_MODEL	Model for embeddings	nomic-embed-text
EMBEDDING_DIMENSIONS	Vector dimensions	768
CHUNK_SIZE	Characters per chunk	1000
CHUNK_OVERLAP	Overlap between chunks	200
EMBEDDING_BATCH_SIZE	Batch size for embedding	10
LOG_LEVEL	Log verbosity	info

Example:

OLLAMA_BASE_URL=http://192.168.1.100:11434 src-mcp serve

MCP Client Configuration

Claude Desktop (claude_desktop_config.json):

With global installation:

{
  "mcpServers": {
    "src-mcp": {
      "command": "src-mcp",
      "args": ["serve"]
    }
  }
}

With npx:

{
  "mcpServers": {
    "src-mcp": {
      "command": "npx",
      "args": ["-y", "src-mcp", "serve"]
    }
  }
}

With environment variables:

{
  "mcpServers": {
    "src-mcp": {
      "command": "src-mcp",
      "args": ["serve"],
      "env": {
        "OLLAMA_BASE_URL": "http://192.168.1.100:11434"
      }
    }
  }
}

Index Storage

Indexes are stored in .src-index/ directory within each indexed project:

my-project/
├── src/
├── .src-index/              # Created by SRC
│   ├── lancedb/             # Vector database
│   ├── callgraph.json       # Call graph cache
│   └── .src-index-hashes.json  # File hash cache
└── ...

Add .src-index/ to your .gitignore:

.src-index/

---

Supported Languages

Full AST Support (18 languages)

These languages have complete support: symbol extraction, semantic chunking at function/class boundaries, call graph analysis, and import resolution.

Category	Language	Extensions
Web	JavaScript	.js .jsx .mjs .cjs
	TypeScript	.ts
	TSX	.tsx
	HTML	.html .htm
	Svelte	.svelte
Systems	C	.c .h
	C++	.cpp .hpp .cc .cxx
	Rust	.rs
	Go	.go
Enterprise	Java	.java
	C#	.cs
	Kotlin	.kt .kts
	Scala	.scala .sc
Scripting	Python	.py .pyi .pyw
	Ruby	.rb .rake .gemspec
	PHP	.php .phtml
Functional	OCaml	.ml .mli
	Swift	.swift

LangChain Fallback (16 languages)

These languages use intelligent text splitting with language-aware rules:

Language	Extensions
Markdown	.md .mdx
LaTeX	.tex .latex
reStructuredText	.rst
Solidity	.sol
Protocol Buffers	.proto
Lua	.lua
Haskell	.hs .lhs
Elixir	.ex .exs
PowerShell	.ps1 .psm1
Perl	.pl .pm
Cobol	.cob .cbl
Visual Basic	.vb .vbs
FORTRAN	.f .f90 .f95
Assembly	.asm .s

Generic Support (30+ file types)

All other text files use configurable chunking:

Category	Extensions
Config	.json .yaml .yml .toml .ini .env .xml
Shell	.sh .bash .zsh .fish .bat .cmd
Styles	.css .scss .sass .less
Data	.sql .graphql .gql
DevOps	Dockerfile Makefile .tf .hcl
Other	.zig .nim .dart .vue .elm .clj

Auto-excluded Files

Binary files and lock files are automatically excluded:

• Binaries: .exe .dll .so .png .jpg .mp3 .zip .wasm
• Lock files: package-lock.json yarn.lock pnpm-lock.yaml
• Build outputs: .pyc .class .o dist/ node_modules/

---

How It Works

Indexing Pipeline

Source Files → Semantic Chunking → AST Enrichment → Cross-file Context → Embeddings → LanceDB
                    ↓                    ↓                  ↓                 ↓
              Split at symbol      Extract symbols    Resolve imports    nomic-embed-text
              boundaries           and metadata       and aliases        768 dimensions

Steps:

1. Scan — Find all supported files (respects .gitignore)
2. Chunk — Split code at function/class boundaries (1000 chars, 200 overlap)
3. Enrich — Add AST metadata (symbols, imports, exports)
4. Resolve — Resolve cross-file imports and TypeScript path aliases
5. Embed — Generate vectors via Ollama (nomic-embed-text)
6. Store — Save to LanceDB with vector and full-text indices
7. Cache — Store file hashes for incremental updates

Search Pipeline

Query → Embed Query → Vector Search ─┐
                                     ├→ RRF Fusion → Add Call Context → Results
Query → Tokenize ───→ BM25 Search ───┘

Steps:

1. Embed — Convert query to vector using same model
2. Vector Search — Find semantically similar chunks (cosine similarity)
3. BM25 Search — Find keyword matches (term frequency)
4. RRF Fusion — Combine rankings with Reciprocal Rank Fusion (k=60)
5. Call Context — Add caller/callee information from call graph
6. Return — Ranked results with full context

Technical Specifications

Component	Specification
Embedding Model	nomic-embed-text (137M params)
Vector Dimensions	768
Chunk Size	1000 characters
Chunk Overlap	200 characters
Batch Size	10 embeddings per request
RRF Constant	k=60
Vector Database	LanceDB (embedded)

---

Comparison

SRC vs Basic Code Search MCPs

Feature	SRC	Basic MCPs
Search Method	Hybrid (Vector + BM25 + RRF)	Keyword only or basic embedding
Call Graph	Full caller/callee context	None
Cross-file Context	Resolves imports & path aliases	None
Incremental Updates	SHA-256 hash detection	Full re-index required
AST Languages	18 with Tree-sitter WASM	Few or none
Total Languages	50+	Limited

Key Advantages

1. Hybrid Search — Combines semantic understanding with keyword precision
2. Call Graph — Understand code relationships, not just content
3. Cross-file Resolution — Follows imports to provide complete context
4. Incremental Updates — Only re-index what changed
5. Semantic Chunking — Splits at symbol boundaries, not arbitrary lines

---

Troubleshooting

Ollama Connection Failed

Error: Ollama is not available

Solution:

1. Ensure Ollama is running: ollama serve
2. Check the URL: curl http://localhost:11434/api/tags
3. If using remote Ollama: set OLLAMA_BASE_URL

Model Not Found

Error: model 'nomic-embed-text' not found

Solution:

ollama pull nomic-embed-text

Index Already Exists

Error: Index already exists. Use force=true to re-index.

Solution:

• Use force: true parameter to re-index
• Or use update_index for incremental updates

No Results Found

Possible causes:

1. Query too specific — try broader terms
2. Wrong directory — check directory parameter
3. Files excluded — check .gitignore patterns

Slow Indexing

Solutions:

1. Increase concurrency: --concurrency 8
2. Exclude large directories: --exclude node_modules --exclude dist
3. Use faster storage (SSD)

---

Links

Project

• GitHub Repository
• npm Package
• Report Issues
• Changelog
• Architecture Guide

External

• MCP Specification
• Ollama
• LanceDB
• Tree-sitter

---

License

MIT © 2026 kvnpetit

---

<div align="center">

Ready to supercharge your AI coding experience?

npm install -g src-mcp && src-mcp serve
# or
npx -y src-mcp serve

Report Bug · Request Feature

</div>