Originally published on tamiz.pro.
Introduction Modern monorepos contain hundreds of thousands of files spanning multiple services, libraries, and configurations.
Traditional code search—whether ripgrep, Sourcegraph, or IDE search—struggles with semantic queries like "how do we handle payment retries?" or "find all places where user permissions are checked".
A RAG-assisted Model Context Protocol (MCP) server can turn your local codebase into a queryable knowledge base, giving LLMs and CLI tools accurate, context-rich answers.
This tutorial shows you how to build a production-grade version of tools like repowise for your own monorepo.
Table of Contents
1.
Architecture Overview
2.
Prerequisites
3.
Project Setup
4.
Indexing Pipeline
5.
MCP Server Implementation
6.
Client Integration
7.
Production Hardening
8.
Frequently Asked Questions
1.
Architecture Overview We'll build three components: Indexer: Splits code into AST-aware chunks, embeds them, and stores them in a local vector database.
MCP Server: Exposes a standardized interface (tools, resources, prompts) that any MCP-compatible client can consume.
Retriever: Combines vector similarity with BM25 lexical search and AST context for precise retrieval.
2.
Prerequisites Node.js 20+ and pnpm/npm Python 3.11+ (for embedding server) A running Qdrant instance (local or remote) A monorepo with a manageable file count (< 1M files for this tutorial) Basic familiarity with TypeScript and Python
3.
Project Setup Initialize the project structure: 3.1 Shared Types Create a shared package for common types:
4.
Indexing Pipeline 4.1 AST-Aware Chunking We use for language-agnostic parsing.
This preserves semantic boundaries (functions, classes) instead of arbitrary character splits. 4.2 Embedding Generation Run a local embedding server using for privacy and zero API cost. 4.3 Indexing Orchestrator Watch for file changes and update the vector store incrementally.
5.
MCP Server Implementation We'll use FastMCP (TypeScript SDK) to expose three tools: , , and .
6.
Client Integration 6.1 Claude Desktop Add to your : 6.2 Cursor IDE In Cursor settings, add the MCP server as a custom tool:
7.
Production Hardening 7.1 Incremental Indexing with Git Hooks Instead of filesystem watching (which misses renames, churn), use and hooks: 7.2 Hybrid Search with Qdrant Enable Qdrant's built-in sparse vectors (BM25) for better lexical recall: Then during search, use Qdrant's with and fuse scores. 7.3 Security & Privacy Run all components locally; never ship code to external APIs unless encrypted.
Use filesystem permissions to restrict access.
Sanitize file paths to prevent path traversal.
Add rate limiting to the embedding server.
8.
Frequently Asked Questions Q: How large a monorepo can this handle?
A: With local embeddings and Qdrant, we've tested repos up to 2M files (~50GB).
The bottleneck is initial indexing time, not query latency.
Q: Can I use this with non-TypeScript languages?
A: Yes. supports 100+ languages.
Update the array and use the corresponding grammar.
Q: How does this compare to GitHub Copilot Workspace?
A: Copilot is cloud-hosted and proprietary.
This tool runs entirely in your infrastructure, supports custom retrieval logic, and integrates with any MCP client (Claude, Cursor, custom IDEs).
Ready to ship?
Start with the indexer package and iterate on chunking strategies.
For production deployments, consider adding a lightweight job queue (BullMQ) for indexing and a reverse proxy for the embedding server.
Production Considerations For production deployments, consider adding a lightweight job queue (BullMQ) for indexing and a reverse proxy for the embedding server.
Below is a minimal BullMQ integration for the indexer package.
Reverse Proxy for Embedding Server The embedding server should sit behind a reverse proxy that handles TLS termination, request buffering, and connection pooling.
Here's an Nginx configuration: Monitoring and Observability A codebase intelligence tool generates significant op