codebase-qa-mcp 0.1.0__tar.gz

codebase_qa_mcp-0.1.0/.dockerignore

@@ -0,0 +1,6 @@
+.git
+.venv
+__pycache__
+*.egg-info
+.mypy_cache
+.pytest_cache

codebase_qa_mcp-0.1.0/Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.12-slim
+
+# Git is needed for incremental updates (git diff, git rev-parse)
+RUN apt-get update && apt-get install -y --no-install-recommends git \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Copy project files
+COPY pyproject.toml README.md ./
+COPY src/ src/
+
+# Install the package
+RUN pip install --no-cache-dir .
+
+# Pre-download the embedding model so first run is instant
+RUN python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')"
+
+# ChromaDB data will be stored here — mount a volume for persistence
+ENV CODEBASE_QA_CHROMA_PATH=/data/chroma_db
+
+ENTRYPOINT ["codebase-qa-mcp"]

codebase_qa_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: codebase-qa-mcp
+Version: 0.1.0
+Summary: MCP server for codebase Q&A powered by RAG — index any git repo and ask questions about the code
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: chromadb
+Requires-Dist: langchain-text-splitters
+Requires-Dist: mcp[cli]
+Requires-Dist: sentence-transformers
+Description-Content-Type: text/markdown
+
+# Codebase Q&A MCP Server
+
+An MCP server that lets AI assistants answer questions about any codebase using RAG (Retrieval-Augmented Generation). Index any git repository locally, then ask natural-language questions — answers are grounded in actual source code.
+
+Built with [FastMCP](https://github.com/jlowin/fastmcp), [ChromaDB](https://www.trychroma.com/), and [sentence-transformers](https://www.sbert.net/).
+
+## How It Works
+
+```
+┌─────────────┐     ┌──────────────────────────────────────────────┐
+│  AI Client   │     │         Codebase Q&A MCP Server              │
+│ (Claude Code,│ MCP │                                              │
+│  Claude      │◄───►│  ┌─────────┐  ┌──────────┐  ┌───────────┐  │
+│  Desktop,    │     │  │  Load &  │─►│ Embed    │─►│ ChromaDB  │  │
+│  Cursor)     │     │  │  Chunk   │  │(MiniLM)  │  │ (persist) │  │
+│              │     │  └─────────┘  └──────────┘  └───────────┘  │
+└─────────────┘     └──────────────────────────────────────────────┘
+```
+
+1. **Index** — Point the server at a git repo. It reads all source files, splits them into chunks, generates embeddings with `all-MiniLM-L6-v2`, and stores them in a persistent ChromaDB instance.
+2. **Query** — Ask a natural-language question. The server finds the most relevant code chunks via semantic similarity and returns them with file paths and metadata.
+3. **Update** — After new commits, run an incremental update that only re-indexes changed files (using `git diff`).
+
+## Features
+
+- **7 MCP tools** for full codebase Q&A workflow
+- **Local embeddings** — no API keys needed (runs `all-MiniLM-L6-v2` on your machine)
+- **Persistent storage** — ChromaDB persists indexes across sessions
+- **Incremental updates** — only re-index files that changed since last commit
+- **Multi-project support** — index multiple repos and switch between them
+- **File filtering** — narrow queries to specific paths (e.g. only `auth`-related files)
+- **30+ file types** supported (Python, JS/TS, Go, Rust, Java, C/C++, Markdown, YAML, SQL, and more)
+
+## Installation
+
+### Option 1: uvx (recommended)
+
+```bash
+uvx codebase-qa-mcp
+```
+
+### Option 2: pip
+
+```bash
+pip install codebase-qa-mcp
+```
+
+### Option 3: From source
+
+```bash
+git clone https://github.com/gokul-viswanathan/codebase-qa-mcp.git
+cd codebase-qa-mcp
+pip install -e .
+```
+
+### Option 4: agentregistry
+
+```bash
+# Install arctl
+curl -fsSL https://raw.githubusercontent.com/agentregistry-dev/agentregistry/main/scripts/get-arctl | bash
+
+# Deploy the server
+arctl deploy codebase-qa-mcp
+
+# Auto-configure your IDE
+arctl configure claude-desktop
+```
+
+## Quick Start
+
+### 1. Add to Claude Code
+
+```bash
+claude mcp add codebase-qa-mcp -- codebase-qa-mcp
+```
+
+Or if running from source:
+
+```bash
+claude mcp add codebase-qa-mcp -- /path/to/codebase-qa-mcp/.venv/bin/python -m codebase_qa_mcp.server
+```
+
+### 2. Add to Claude Desktop
+
+Add this to your Claude Desktop config (`~/.config/claude-desktop/config.json`):
+
+```json
+{
+  "mcpServers": {
+    "codebase-qa-mcp": {
+      "command": "codebase-qa-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+Or from source:
+
+```json
+{
+  "mcpServers": {
+    "codebase-qa-mcp": {
+      "command": "/path/to/codebase-qa-mcp/.venv/bin/python",
+      "args": ["-m", "codebase_qa_mcp.server"]
+    }
+  }
+}
+```
+
+### 3. Use it
+
+Once connected, your AI assistant can use these tools:
+
+```
+You: "Index the repo at /home/user/my-project"
+AI:  → calls index_repository("/home/user/my-project")
+     ✓ Indexed 42 files → 380 chunks
+
+You: "How does authentication work in this codebase?"
+AI:  → calls query_codebase("how does authentication work")
+     Returns relevant code chunks from auth-related files
+
+You: "What files handle database migrations?"
+AI:  → calls query_codebase("database migrations", file_filter="migrations")
+     Returns chunks specifically from migration files
+```
+
+## MCP Tools Reference
+
+| Tool | Description |
+|------|-------------|
+| `index_repository` | Full-index a git repo into ChromaDB. Reads all source files, chunks, embeds, and stores them. |
+| `update_index` | Incrementally update using `git diff`. Only re-indexes changed files. |
+| `query_codebase` | Semantic search for code chunks relevant to a natural-language question. |
+| `switch_project` | Switch to a previously indexed repo without re-indexing. |
+| `list_indexed_files` | List all file paths in the current project's index. |
+| `get_index_stats` | Get stats: total chunks, total files, last indexed commit. |
+| `list_projects` | List all previously indexed repositories. |
+
+## Configuration
+
+The server uses sensible defaults but you can customize via environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CODEBASE_QA_CHROMA_PATH` | `~/.local/share/codebase-qa-mcp/chroma_db` | Where ChromaDB stores its data |
+
+Built-in defaults:
+- **Chunk size:** 500 characters with 50-character overlap
+- **Embedding model:** `all-MiniLM-L6-v2` (384-dimensional, runs locally)
+- **Top-K results:** 5
+
+## Project Structure
+
+```
+codebase-qa-mcp/
+├── pyproject.toml                  # Package config, deps, entry point
+├── Dockerfile                      # Container build for agentregistry
+└── src/codebase_qa_mcp/
+    ├── __init__.py
+    ├── config.py                   # Constants (chunk size, model, extensions)
+    ├── indexer.py                  # Load → chunk → embed → store + incremental updates
+    ├── retriever.py                # Query, list files, stats, list projects
+    └── server.py                   # FastMCP server with 7 tools
+```
+
+## How RAG Works Here
+
+**Retrieval-Augmented Generation (RAG)** grounds AI responses in actual source code rather than relying on the model's training data:
+
+1. **Chunking** — Source files are split into ~500-character chunks using `RecursiveCharacterTextSplitter` from LangChain, which respects code boundaries.
+2. **Embedding** — Each chunk is converted to a 384-dimensional vector using `all-MiniLM-L6-v2`, a fast sentence-transformer model that runs entirely on your machine.
+3. **Storage** — Vectors are stored in ChromaDB with metadata (file path, chunk index, language). The database persists to disk so indexes survive restarts.
+4. **Retrieval** — When you ask a question, it's embedded with the same model and compared against stored chunks via cosine similarity. The top-K most relevant chunks are returned.
+5. **Generation** — The AI client (Claude, etc.) receives the relevant code chunks and uses them to generate an accurate, grounded answer.
+
+## License
+
+MIT

codebase_qa_mcp-0.1.0/README.md

@@ -0,0 +1,180 @@
+# Codebase Q&A MCP Server
+
+An MCP server that lets AI assistants answer questions about any codebase using RAG (Retrieval-Augmented Generation). Index any git repository locally, then ask natural-language questions — answers are grounded in actual source code.
+
+Built with [FastMCP](https://github.com/jlowin/fastmcp), [ChromaDB](https://www.trychroma.com/), and [sentence-transformers](https://www.sbert.net/).
+
+## How It Works
+
+```
+┌─────────────┐     ┌──────────────────────────────────────────────┐
+│  AI Client   │     │         Codebase Q&A MCP Server              │
+│ (Claude Code,│ MCP │                                              │
+│  Claude      │◄───►│  ┌─────────┐  ┌──────────┐  ┌───────────┐  │
+│  Desktop,    │     │  │  Load &  │─►│ Embed    │─►│ ChromaDB  │  │
+│  Cursor)     │     │  │  Chunk   │  │(MiniLM)  │  │ (persist) │  │
+│              │     │  └─────────┘  └──────────┘  └───────────┘  │
+└─────────────┘     └──────────────────────────────────────────────┘
+```
+
+1. **Index** — Point the server at a git repo. It reads all source files, splits them into chunks, generates embeddings with `all-MiniLM-L6-v2`, and stores them in a persistent ChromaDB instance.
+2. **Query** — Ask a natural-language question. The server finds the most relevant code chunks via semantic similarity and returns them with file paths and metadata.
+3. **Update** — After new commits, run an incremental update that only re-indexes changed files (using `git diff`).
+
+## Features
+
+- **7 MCP tools** for full codebase Q&A workflow
+- **Local embeddings** — no API keys needed (runs `all-MiniLM-L6-v2` on your machine)
+- **Persistent storage** — ChromaDB persists indexes across sessions
+- **Incremental updates** — only re-index files that changed since last commit
+- **Multi-project support** — index multiple repos and switch between them
+- **File filtering** — narrow queries to specific paths (e.g. only `auth`-related files)
+- **30+ file types** supported (Python, JS/TS, Go, Rust, Java, C/C++, Markdown, YAML, SQL, and more)
+
+## Installation
+
+### Option 1: uvx (recommended)
+
+```bash
+uvx codebase-qa-mcp
+```
+
+### Option 2: pip
+
+```bash
+pip install codebase-qa-mcp
+```
+
+### Option 3: From source
+
+```bash
+git clone https://github.com/gokul-viswanathan/codebase-qa-mcp.git
+cd codebase-qa-mcp
+pip install -e .
+```
+
+### Option 4: agentregistry
+
+```bash
+# Install arctl
+curl -fsSL https://raw.githubusercontent.com/agentregistry-dev/agentregistry/main/scripts/get-arctl | bash
+
+# Deploy the server
+arctl deploy codebase-qa-mcp
+
+# Auto-configure your IDE
+arctl configure claude-desktop
+```
+
+## Quick Start
+
+### 1. Add to Claude Code
+
+```bash
+claude mcp add codebase-qa-mcp -- codebase-qa-mcp
+```
+
+Or if running from source:
+
+```bash
+claude mcp add codebase-qa-mcp -- /path/to/codebase-qa-mcp/.venv/bin/python -m codebase_qa_mcp.server
+```
+
+### 2. Add to Claude Desktop
+
+Add this to your Claude Desktop config (`~/.config/claude-desktop/config.json`):
+
+```json
+{
+  "mcpServers": {
+    "codebase-qa-mcp": {
+      "command": "codebase-qa-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+Or from source:
+
+```json
+{
+  "mcpServers": {
+    "codebase-qa-mcp": {
+      "command": "/path/to/codebase-qa-mcp/.venv/bin/python",
+      "args": ["-m", "codebase_qa_mcp.server"]
+    }
+  }
+}
+```
+
+### 3. Use it
+
+Once connected, your AI assistant can use these tools:
+
+```
+You: "Index the repo at /home/user/my-project"
+AI:  → calls index_repository("/home/user/my-project")
+     ✓ Indexed 42 files → 380 chunks
+
+You: "How does authentication work in this codebase?"
+AI:  → calls query_codebase("how does authentication work")
+     Returns relevant code chunks from auth-related files
+
+You: "What files handle database migrations?"
+AI:  → calls query_codebase("database migrations", file_filter="migrations")
+     Returns chunks specifically from migration files
+```
+
+## MCP Tools Reference
+
+| Tool | Description |
+|------|-------------|
+| `index_repository` | Full-index a git repo into ChromaDB. Reads all source files, chunks, embeds, and stores them. |
+| `update_index` | Incrementally update using `git diff`. Only re-indexes changed files. |
+| `query_codebase` | Semantic search for code chunks relevant to a natural-language question. |
+| `switch_project` | Switch to a previously indexed repo without re-indexing. |
+| `list_indexed_files` | List all file paths in the current project's index. |
+| `get_index_stats` | Get stats: total chunks, total files, last indexed commit. |
+| `list_projects` | List all previously indexed repositories. |
+
+## Configuration
+
+The server uses sensible defaults but you can customize via environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CODEBASE_QA_CHROMA_PATH` | `~/.local/share/codebase-qa-mcp/chroma_db` | Where ChromaDB stores its data |
+
+Built-in defaults:
+- **Chunk size:** 500 characters with 50-character overlap
+- **Embedding model:** `all-MiniLM-L6-v2` (384-dimensional, runs locally)
+- **Top-K results:** 5
+
+## Project Structure
+
+```
+codebase-qa-mcp/
+├── pyproject.toml                  # Package config, deps, entry point
+├── Dockerfile                      # Container build for agentregistry
+└── src/codebase_qa_mcp/
+    ├── __init__.py
+    ├── config.py                   # Constants (chunk size, model, extensions)
+    ├── indexer.py                  # Load → chunk → embed → store + incremental updates
+    ├── retriever.py                # Query, list files, stats, list projects
+    └── server.py                   # FastMCP server with 7 tools
+```
+
+## How RAG Works Here
+
+**Retrieval-Augmented Generation (RAG)** grounds AI responses in actual source code rather than relying on the model's training data:
+
+1. **Chunking** — Source files are split into ~500-character chunks using `RecursiveCharacterTextSplitter` from LangChain, which respects code boundaries.
+2. **Embedding** — Each chunk is converted to a 384-dimensional vector using `all-MiniLM-L6-v2`, a fast sentence-transformer model that runs entirely on your machine.
+3. **Storage** — Vectors are stored in ChromaDB with metadata (file path, chunk index, language). The database persists to disk so indexes survive restarts.
+4. **Retrieval** — When you ask a question, it's embedded with the same model and compared against stored chunks via cosine similarity. The top-K most relevant chunks are returned.
+5. **Generation** — The AI client (Claude, etc.) receives the relevant code chunks and uses them to generate an accurate, grounded answer.
+
+## License
+
+MIT

codebase_qa_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "codebase-qa-mcp"
+version = "0.1.0"
+description = "MCP server for codebase Q&A powered by RAG — index any git repo and ask questions about the code"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+    "mcp[cli]",
+    "chromadb",
+    "sentence-transformers",
+    "langchain-text-splitters",
+]
+
+[project.scripts]
+codebase-qa-mcp = "codebase_qa_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

codebase_qa_mcp-0.1.0/src/codebase_qa_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Codebase Q&A MCP Server — ask questions about any codebase using RAG."""
+
+__version__ = "0.1.0"

codebase_qa_mcp-0.1.0/src/codebase_qa_mcp/config.py

@@ -0,0 +1,39 @@
+"""Configuration constants for the Codebase Q&A MCP server."""
+
+import os
+from pathlib import Path
+
+# Chunking
+CHUNK_SIZE = 500
+CHUNK_OVERLAP = 50
+
+# Embedding model (runs locally, no API key needed)
+EMBEDDING_MODEL = "all-MiniLM-L6-v2"
+
+# Retrieval
+TOP_K = 5
+
+# File types to index
+SUPPORTED_EXTENSIONS = {
+    ".py", ".js", ".ts", ".tsx", ".jsx",
+    ".md", ".txt", ".rst",
+    ".java", ".go", ".rs", ".c", ".cpp", ".h", ".hpp",
+    ".yaml", ".yml", ".json", ".toml",
+    ".sh", ".bash", ".zsh",
+    ".html", ".css", ".scss",
+    ".sql",
+    ".dockerfile",
+}
+
+# Directories to skip during indexing
+IGNORED_DIRS = {
+    ".git", "node_modules", "__pycache__", ".venv", "venv",
+    "dist", "build", ".tox", ".mypy_cache", ".pytest_cache",
+    ".next", ".nuxt", "target", "vendor", ".eggs", "*.egg-info",
+}
+
+# ChromaDB storage (user-level, not inside any repo)
+CHROMA_DB_PATH = os.environ.get(
+    "CODEBASE_QA_CHROMA_PATH",
+    str(Path.home() / ".local" / "share" / "codebase-qa-mcp" / "chroma_db"),
+)

codebase_qa_mcp-0.1.0/src/codebase_qa_mcp/indexer.py

@@ -0,0 +1,354 @@
+"""Codebase ingestion: load files, chunk, embed, store in ChromaDB."""
+
+import json
+import os
+import re
+import subprocess
+from pathlib import Path
+
+import chromadb
+from chromadb.utils.embedding_functions import SentenceTransformerEmbeddingFunction
+from langchain_text_splitters import Language, RecursiveCharacterTextSplitter
+
+from . import config
+
+# Map file extensions to language names
+EXTENSION_TO_LANGUAGE = {
+    ".py": "python", ".js": "javascript", ".ts": "typescript",
+    ".tsx": "typescript", ".jsx": "javascript", ".java": "java",
+    ".go": "go", ".rs": "rust", ".c": "c", ".cpp": "cpp",
+    ".h": "c", ".hpp": "cpp", ".html": "html", ".css": "css",
+    ".scss": "css", ".sql": "sql", ".sh": "bash", ".bash": "bash",
+    ".zsh": "bash", ".md": "markdown", ".txt": "text", ".rst": "text",
+    ".yaml": "yaml", ".yml": "yaml", ".json": "json", ".toml": "toml",
+    ".dockerfile": "dockerfile",
+}
+
+# Map our language names to LangChain Language enums for code-aware splitting
+_LANGUAGE_TO_LANGCHAIN = {
+    "python": Language.PYTHON,
+    "javascript": Language.JS,
+    "typescript": Language.TS,
+    "java": Language.JAVA,
+    "go": Language.GO,
+    "rust": Language.RUST,
+    "c": Language.C,
+    "cpp": Language.CPP,
+    "html": Language.HTML,
+    "markdown": Language.MARKDOWN,
+}
+
+
+def _get_collection_name(repo_path: str) -> str:
+    """Derive a ChromaDB collection name from a repo path."""
+    name = Path(repo_path).resolve().name
+    # ChromaDB collection names: 3-63 chars, alphanumeric/underscores/hyphens
+    name = re.sub(r"[^a-zA-Z0-9_-]", "-", name).strip("-")
+    if len(name) < 3:
+        name = name + "-repo"
+    return name[:63]
+
+
+def _get_chroma_client() -> chromadb.ClientAPI:
+    """Return a persistent ChromaDB client."""
+    db_path = config.CHROMA_DB_PATH
+    os.makedirs(db_path, exist_ok=True)
+    return chromadb.PersistentClient(path=db_path)
+
+
+def _get_embedding_function() -> SentenceTransformerEmbeddingFunction:
+    """Return the embedding function used for all collections."""
+    return SentenceTransformerEmbeddingFunction(model_name=config.EMBEDDING_MODEL)
+
+
+def _get_state_file(collection_name: str) -> Path:
+    """Path to the index state file for a collection."""
+    return Path(config.CHROMA_DB_PATH) / f".state_{collection_name}.json"
+
+
+def _read_state(collection_name: str) -> dict:
+    """Read the persisted index state (last commit SHA, repo path)."""
+    state_file = _get_state_file(collection_name)
+    if state_file.exists():
+        return json.loads(state_file.read_text())
+    return {}
+
+
+def _write_state(collection_name: str, state: dict) -> None:
+    """Persist index state."""
+    state_file = _get_state_file(collection_name)
+    state_file.write_text(json.dumps(state, indent=2))
+
+
+def _get_head_sha(repo_path: str) -> str | None:
+    """Get the current HEAD commit SHA of a git repo."""
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            cwd=repo_path, capture_output=True, text=True, check=True,
+        )
+        return result.stdout.strip()
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return None
+
+
+def _should_skip_dir(dir_name: str) -> bool:
+    """Check if a directory should be skipped."""
+    return dir_name in config.IGNORED_DIRS or dir_name.endswith(".egg-info")
+
+
+def load_files(repo_path: str) -> list[dict]:
+    """Walk a directory and load all supported files."""
+    repo = Path(repo_path).resolve()
+    files = []
+
+    for root, dirs, filenames in os.walk(repo):
+        # Prune ignored directories in-place
+        dirs[:] = [d for d in dirs if not _should_skip_dir(d)]
+
+        for filename in filenames:
+            filepath = Path(root) / filename
+            ext = filepath.suffix.lower()
+
+            if ext not in config.SUPPORTED_EXTENSIONS:
+                continue
+
+            try:
+                content = filepath.read_text(encoding="utf-8", errors="ignore")
+            except (OSError, PermissionError):
+                continue
+
+            if not content.strip():
+                continue
+
+            rel_path = str(filepath.relative_to(repo))
+            files.append({
+                "path": rel_path,
+                "content": content,
+                "language": EXTENSION_TO_LANGUAGE.get(ext, "text"),
+            })
+
+    return files
+
+
+def chunk_file(file_dict: dict) -> list[dict]:
+    """Split a file's content into chunks with metadata.
+
+    Uses language-aware splitting when possible (splits on function/class
+    boundaries) and falls back to generic recursive splitting for unsupported
+    languages.
+    """
+    lang_enum = _LANGUAGE_TO_LANGCHAIN.get(file_dict["language"])
+
+    if lang_enum is not None:
+        splitter = RecursiveCharacterTextSplitter.from_language(
+            language=lang_enum,
+            chunk_size=config.CHUNK_SIZE,
+            chunk_overlap=config.CHUNK_OVERLAP,
+        )
+    else:
+        splitter = RecursiveCharacterTextSplitter(
+            chunk_size=config.CHUNK_SIZE,
+            chunk_overlap=config.CHUNK_OVERLAP,
+            length_function=len,
+        )
+
+    texts = splitter.split_text(file_dict["content"])
+
+    return [
+        {
+            "text": text,
+            "metadata": {
+                "file_path": file_dict["path"],
+                "chunk_index": i,
+                "language": file_dict["language"],
+            },
+        }
+        for i, text in enumerate(texts)
+    ]
+
+
+def index_repository(repo_path: str) -> dict:
+    """Full-index a codebase into ChromaDB. Replaces any existing index."""
+    repo_path = str(Path(repo_path).resolve())
+    collection_name = _get_collection_name(repo_path)
+    client = _get_chroma_client()
+    embed_fn = _get_embedding_function()
+
+    # Delete existing collection if it exists, then create fresh
+    try:
+        client.delete_collection(collection_name)
+    except (ValueError, Exception):
+        pass  # Collection doesn't exist yet, that's fine
+    collection = client.get_or_create_collection(
+        name=collection_name,
+        embedding_function=embed_fn,
+    )
+
+    # Load and chunk all files
+    files = load_files(repo_path)
+    all_chunks = []
+    for f in files:
+        all_chunks.extend(chunk_file(f))
+
+    if not all_chunks:
+        return {
+            "collection": collection_name,
+            "repo_path": repo_path,
+            "files_indexed": 0,
+            "chunks_created": 0,
+        }
+
+    # Add chunks to ChromaDB in batches (ChromaDB limit is ~41666 per add)
+    batch_size = 5000
+    for i in range(0, len(all_chunks), batch_size):
+        batch = all_chunks[i:i + batch_size]
+        collection.add(
+            ids=[f"{c['metadata']['file_path']}::{c['metadata']['chunk_index']}" for c in batch],
+            documents=[c["text"] for c in batch],
+            metadatas=[c["metadata"] for c in batch],
+        )
+
+    # Save state
+    head_sha = _get_head_sha(repo_path)
+    _write_state(collection_name, {
+        "repo_path": repo_path,
+        "last_commit_sha": head_sha,
+        "collection_name": collection_name,
+    })
+
+    return {
+        "collection": collection_name,
+        "repo_path": repo_path,
+        "files_indexed": len(files),
+        "chunks_created": len(all_chunks),
+        "commit_sha": head_sha,
+    }
+
+
+def get_changed_files(repo_path: str, last_sha: str) -> dict:
+    """Get files changed between last indexed commit and HEAD."""
+    try:
+        result = subprocess.run(
+            ["git", "diff", "--name-status", f"{last_sha}..HEAD"],
+            cwd=repo_path, capture_output=True, text=True, check=True,
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return {"added": [], "modified": [], "deleted": []}
+
+    changes = {"added": [], "modified": [], "deleted": []}
+    for line in result.stdout.strip().splitlines():
+        if not line:
+            continue
+        parts = line.split("\t", 1)
+        if len(parts) != 2:
+            continue
+        status, filepath = parts[0], parts[1]
+
+        if status.startswith("A"):
+            changes["added"].append(filepath)
+        elif status.startswith("M"):
+            changes["modified"].append(filepath)
+        elif status.startswith("D"):
+            changes["deleted"].append(filepath)
+        elif status.startswith("R"):
+            # Renamed: old\tnew
+            rename_parts = filepath.split("\t")
+            changes["deleted"].append(rename_parts[0])
+            if len(rename_parts) > 1:
+                changes["added"].append(rename_parts[1])
+
+    return changes
+
+
+def update_index(repo_path: str) -> dict:
+    """Incrementally update the index using git diff."""
+    repo_path = str(Path(repo_path).resolve())
+    collection_name = _get_collection_name(repo_path)
+    state = _read_state(collection_name)
+
+    if not state or not state.get("last_commit_sha"):
+        # No previous index — do a full index
+        return index_repository(repo_path)
+
+    last_sha = state["last_commit_sha"]
+    head_sha = _get_head_sha(repo_path)
+
+    if head_sha == last_sha:
+        return {
+            "collection": collection_name,
+            "status": "already_up_to_date",
+            "commit_sha": head_sha,
+        }
+
+    changes = get_changed_files(repo_path, last_sha)
+    files_to_remove = changes["deleted"] + changes["modified"]
+    files_to_add = changes["added"] + changes["modified"]
+
+    client = _get_chroma_client()
+    embed_fn = _get_embedding_function()
+    collection = client.get_or_create_collection(
+        name=collection_name,
+        embedding_function=embed_fn,
+    )
+
+    chunks_removed = 0
+    chunks_added = 0
+
+    # Remove chunks for deleted/modified files
+    for filepath in files_to_remove:
+        existing = collection.get(where={"file_path": filepath})
+        if existing["ids"]:
+            collection.delete(ids=existing["ids"])
+            chunks_removed += len(existing["ids"])
+
+    # Add chunks for added/modified files
+    repo = Path(repo_path).resolve()
+    for filepath in files_to_add:
+        full_path = repo / filepath
+        if not full_path.exists():
+            continue
+
+        ext = full_path.suffix.lower()
+        if ext not in config.SUPPORTED_EXTENSIONS:
+            continue
+
+        try:
+            content = full_path.read_text(encoding="utf-8", errors="ignore")
+        except (OSError, PermissionError):
+            continue
+
+        if not content.strip():
+            continue
+
+        file_dict = {
+            "path": filepath,
+            "content": content,
+            "language": EXTENSION_TO_LANGUAGE.get(ext, "text"),
+        }
+        chunks = chunk_file(file_dict)
+
+        if chunks:
+            collection.add(
+                ids=[f"{c['metadata']['file_path']}::{c['metadata']['chunk_index']}" for c in chunks],
+                documents=[c["text"] for c in chunks],
+                metadatas=[c["metadata"] for c in chunks],
+            )
+            chunks_added += len(chunks)
+
+    # Update state
+    _write_state(collection_name, {
+        "repo_path": repo_path,
+        "last_commit_sha": head_sha,
+        "collection_name": collection_name,
+    })
+
+    return {
+        "collection": collection_name,
+        "files_updated": len(changes["modified"]),
+        "files_added": len(changes["added"]),
+        "files_deleted": len(changes["deleted"]),
+        "chunks_removed": chunks_removed,
+        "chunks_added": chunks_added,
+        "commit_sha": head_sha,
+    }

codebase_qa_mcp-0.1.0/src/codebase_qa_mcp/retriever.py

@@ -0,0 +1,125 @@
+"""Query engine: search ChromaDB for relevant code chunks."""
+
+from chromadb.utils.embedding_functions import SentenceTransformerEmbeddingFunction
+
+from . import config
+from .indexer import _get_chroma_client, _get_collection_name, _get_embedding_function, _read_state
+
+
+def query_codebase(
+    repo_path: str,
+    question: str,
+    top_k: int = config.TOP_K,
+    file_filter: str | None = None,
+) -> list[dict]:
+    """Search the indexed codebase for chunks relevant to a question."""
+    collection_name = _get_collection_name(repo_path)
+    client = _get_chroma_client()
+    embed_fn = _get_embedding_function()
+
+    try:
+        collection = client.get_collection(
+            name=collection_name,
+            embedding_function=embed_fn,
+        )
+    except ValueError:
+        return []
+
+    where_filter = None
+    if file_filter:
+        where_filter = {"file_path": {"$contains": file_filter}}
+
+    results = collection.query(
+        query_texts=[question],
+        n_results=min(top_k, collection.count()),
+        where=where_filter,
+    )
+
+    if not results["documents"] or not results["documents"][0]:
+        return []
+
+    chunks = []
+    for i, doc in enumerate(results["documents"][0]):
+        chunks.append({
+            "content": doc,
+            "file_path": results["metadatas"][0][i].get("file_path", "unknown"),
+            "chunk_index": results["metadatas"][0][i].get("chunk_index", 0),
+            "language": results["metadatas"][0][i].get("language", "text"),
+            "distance": results["distances"][0][i] if results["distances"] else None,
+        })
+
+    return chunks
+
+
+def list_indexed_files(repo_path: str) -> list[str]:
+    """Get all unique file paths in the index for a repo."""
+    collection_name = _get_collection_name(repo_path)
+    client = _get_chroma_client()
+    embed_fn = _get_embedding_function()
+
+    try:
+        collection = client.get_collection(
+            name=collection_name,
+            embedding_function=embed_fn,
+        )
+    except ValueError:
+        return []
+
+    all_items = collection.get(include=["metadatas"])
+    file_paths = set()
+    for meta in all_items["metadatas"]:
+        if "file_path" in meta:
+            file_paths.add(meta["file_path"])
+
+    return sorted(file_paths)
+
+
+def get_index_stats(repo_path: str) -> dict:
+    """Get statistics about the index for a repo."""
+    collection_name = _get_collection_name(repo_path)
+    client = _get_chroma_client()
+    embed_fn = _get_embedding_function()
+
+    state = _read_state(collection_name)
+
+    try:
+        collection = client.get_collection(
+            name=collection_name,
+            embedding_function=embed_fn,
+        )
+    except ValueError:
+        return {
+            "collection": collection_name,
+            "status": "not_indexed",
+        }
+
+    all_items = collection.get(include=["metadatas"])
+    file_paths = set()
+    for meta in all_items["metadatas"]:
+        if "file_path" in meta:
+            file_paths.add(meta["file_path"])
+
+    return {
+        "collection": collection_name,
+        "repo_path": state.get("repo_path", repo_path),
+        "total_chunks": collection.count(),
+        "total_files": len(file_paths),
+        "last_indexed_commit": state.get("last_commit_sha"),
+    }
+
+
+def list_projects() -> list[dict]:
+    """List all indexed projects."""
+    client = _get_chroma_client()
+    collections = client.list_collections()
+
+    projects = []
+    for col in collections:
+        state = _read_state(col.name)
+        projects.append({
+            "collection": col.name,
+            "repo_path": state.get("repo_path", "unknown"),
+            "last_commit": state.get("last_commit_sha"),
+        })
+
+    return projects

codebase_qa_mcp-0.1.0/src/codebase_qa_mcp/server.py

@@ -0,0 +1,131 @@
+"""MCP server exposing codebase Q&A tools."""
+
+from mcp.server.fastmcp import FastMCP
+
+from . import indexer, retriever
+
+mcp = FastMCP("Codebase Q&A")
+
+# Track the active project so queries know which collection to search
+_active_repo_path: str | None = None
+
+
+@mcp.tool()
+def index_repository(repo_path: str) -> dict:
+    """Full-index a git repository into the vector store.
+
+    Reads all supported source files, splits them into chunks,
+    generates embeddings, and stores them in ChromaDB.
+    This replaces any existing index for the same repo.
+    Sets this repo as the active project for queries.
+
+    Args:
+        repo_path: Absolute path to the git repository to index.
+    """
+    global _active_repo_path
+    _active_repo_path = repo_path
+    return indexer.index_repository(repo_path)
+
+
+@mcp.tool()
+def update_index(repo_path: str) -> dict:
+    """Incrementally update the index using git diff.
+
+    Only re-indexes files that changed since the last index.
+    Much faster than a full re-index for large repos.
+    Falls back to full index if no previous index exists.
+
+    Args:
+        repo_path: Absolute path to the git repository.
+    """
+    global _active_repo_path
+    _active_repo_path = repo_path
+    return indexer.update_index(repo_path)
+
+
+@mcp.tool()
+def query_codebase(
+    question: str, top_k: int = 5, file_filter: str | None = None
+) -> list[dict]:
+    """Search the indexed codebase for code chunks relevant to a question.
+
+    Returns the most relevant source code chunks with file paths,
+    ordered by similarity. Use this to find code related to a topic,
+    understand how something is implemented, or locate specific functionality.
+
+    Args:
+        question: Natural language question about the codebase.
+        top_k: Number of results to return (default 5).
+        file_filter: Optional substring to filter by file path (e.g. "auth" to only search auth-related files).
+    """
+    if not _active_repo_path:
+        return [
+            {
+                "error": "No active project. Call index_repository or switch_project first."
+            }
+        ]
+    return retriever.query_codebase(_active_repo_path, question, top_k, file_filter)
+
+
+@mcp.tool()
+def switch_project(repo_path: str) -> dict:
+    """Switch the active project without re-indexing.
+
+    Use this when you want to query a previously indexed repo.
+    The repo must have been indexed before with index_repository.
+
+    Args:
+        repo_path: Absolute path to a previously indexed repository.
+    """
+    global _active_repo_path
+    stats = retriever.get_index_stats(repo_path)
+    if stats.get("status") == "not_indexed":
+        return {
+            "error": f"Repository not indexed. Run index_repository('{repo_path}') first."
+        }
+    _active_repo_path = repo_path
+    return {"active_project": repo_path, **stats}
+
+
+@mcp.tool()
+def list_indexed_files() -> list[str]:
+    """List all file paths currently indexed in the active project.
+
+    Useful for understanding what's in the index and verifying
+    that the right files were captured.
+    """
+    if not _active_repo_path:
+        return ["No active project. Call index_repository or switch_project first."]
+    return retriever.list_indexed_files(_active_repo_path)
+
+
+@mcp.tool()
+def get_index_stats() -> dict:
+    """Get statistics about the active project's index.
+
+    Returns total chunks, total files, last indexed commit, etc.
+    """
+    if not _active_repo_path:
+        return {
+            "error": "No active project. Call index_repository or switch_project first."
+        }
+    return retriever.get_index_stats(_active_repo_path)
+
+
+@mcp.tool()
+def list_projects() -> list[dict]:
+    """List all previously indexed projects.
+
+    Shows all repos that have been indexed, with their paths
+    and last indexed commit. Use switch_project to activate one.
+    """
+    return retriever.list_projects()
+
+
+def main():
+    """Entry point for the MCP server."""
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()