README
¶
RagCode MCP - Make Your Codebase AI-Ready
The privacy-first MCP server that transforms any repository into an AI-ready codebase with semantic search and RAG.
RagCode is a Model Context Protocol (MCP) server that instantly makes your project AI-ready. It enables AI assistants like GitHub Copilot, Cursor, Windsurf, and Claude to understand your entire codebase through semantic vector search, bridging the gap between your code and Large Language Models (LLMs).
Built with the official Model Context Protocol Go SDK, RagCode provides 9 powerful tools to index, search, and analyze code, making it the ultimate solution for AI-ready software development.
⚡ One-Command Installation
No Go, no build tools, no configuration needed. Just Docker.
| Linux (amd64) |
|
| macOS (Apple Silicon) |
|
| macOS (Intel) |
|
| Windows (PowerShell) |
|
That's it! The installer automatically:
- ✅ Downloads and installs the
rag-code-mcpbinary - ✅ Sets up Ollama and Qdrant in Docker containers
- ✅ Downloads required AI models (
phi3:medium,nomic-embed-text) - ✅ Configures your IDE (VS Code, Cursor, Windsurf, Claude Desktop)
- ✅ Adds binaries to your PATH
📖 Full Installation Guide → | Windows WSL Setup →
🎯 Zero-Config Usage
Once installed, you don't need to configure anything:
- Open your project in your IDE (VS Code, Cursor, Windsurf)
- Ask your AI assistant a question about your code
- That's it! RagCode automatically indexes and answers
💬 "How does the authentication system work?"
💬 "Find all API endpoints in this codebase"
💬 "Show me the User model and its relationships"
First query triggers background indexing. Subsequent queries are instant.
📋 Table of Contents
| Section | Description |
|---|---|
| 🔒 Privacy & Security | 100% local, zero cloud dependencies |
| 🚀 Why RagCode? | Performance benefits, comparisons |
| 🛠️ MCP Tools | All 9 tools explained |
| 🌐 Supported Languages | Go, PHP, Python support |
| 💻 IDE Integration | Windsurf, Cursor, VS Code, Claude |
| ⚙️ Configuration | Advanced settings, models, env vars |
| 🐛 Troubleshooting | Common issues and solutions |
| 📚 Documentation | All guides and references |
🔒 Privacy-First: 100% Local AI
Your code never leaves your machine. RagCode runs entirely on your local infrastructure:
- ✅ Local AI Models - Uses Ollama for LLM and embeddings (runs on your hardware)
- ✅ Local Vector Database - Qdrant runs in Docker on your machine
- ✅ Zero Cloud Dependencies - No external API calls, no data transmission
- ✅ No API Costs - Free forever, no usage limits or subscriptions
- ✅ Offline Capable - Works without internet (after initial model download)
Perfect for: Enterprise codebases, proprietary projects, security-conscious teams.
🚀 Why RagCode? Performance Benefits
5-10x Faster Code Understanding
| Task | Without RagCode | With RagCode | Speedup |
|---|---|---|---|
| Find authentication logic | 30-60s (read 10+ files) | 2-3s (semantic search) | 10-20x |
| Understand function signature | 15-30s (grep + read) | 1-2s (direct lookup) | 15x |
| Find all API endpoints | 60-120s (manual search) | 3-5s (hybrid search) | 20-40x |
98% Token Savings
- Without RagCode: AI reads 5-10 files (~15,000 tokens) to find a function
- With RagCode: AI gets exact function + context (~200 tokens)
RagCode vs Cloud-Based Solutions
| Feature | RagCode (Local) | Cloud AI Search |
|---|---|---|
| Privacy | ✅ 100% local | ❌ Code sent to cloud |
| Cost | ✅ $0 forever | ❌ $20-100+/month |
| Offline | ✅ Works offline | ❌ Requires internet |
| Data Control | ✅ You own everything | ❌ Vendor controls data |
RagCode vs Generic RAG
| Aspect | Generic RAG | RagCode |
|---|---|---|
| Chunking | Arbitrary text splits | Semantic units (functions, classes) |
| Metadata | Filename only | Name, type, params, dependencies, lines |
| Results | May return partial code | Always complete, runnable code |
🛠️ 9 Powerful MCP Tools
| Tool | Description | Use When |
|---|---|---|
search_code |
Semantic search by meaning | First choice for exploration |
hybrid_search |
Keyword + semantic for exact matches | Need exact identifiers |
get_function_details |
Complete function source code | Know exact function name |
find_type_definition |
Type/class with fields and methods | Understand data models |
find_implementations |
All usages and callers | Before refactoring |
list_package_exports |
All exported symbols | Explore unfamiliar packages |
search_docs |
Search Markdown documentation | Setup, architecture info |
get_code_context |
Code snippet with context | Have file:line reference |
index_workspace |
Reindex codebase | After major changes |
🌐 Multi-Language Code Intelligence
| Language | Support Level | Features | Docs |
|---|---|---|---|
| Go | ✅ Full | Functions, types, interfaces, methods, AST analysis | 📖 Go Analyzer |
| PHP | ✅ Full | Classes, methods, interfaces, traits, PHPDoc | 📖 PHP Analyzer |
| PHP + Laravel | ✅ Full | Eloquent models, routes, controllers, middleware | 📖 Laravel Analyzer |
| Python | ✅ Full | Classes, functions, decorators, type hints, mixins | 📖 Python Analyzer |
| JavaScript/TypeScript | 🔜 Planned | Coming soon (tree-sitter based) | - |
Multi-Workspace Support
RagCode automatically detects and manages multiple workspaces with isolated indexes.
📖 Workspace Detection → - Auto-detection, stable IDs, caching
💻 IDE Integration
RagCode works with all major AI-powered IDEs:
| IDE | Status | Setup |
|---|---|---|
| Windsurf | ✅ Auto-configured | Just install |
| Cursor | ✅ Auto-configured | Just install |
| VS Code + Copilot | ✅ Auto-configured | Requires VS Code 1.95+ |
| Claude Desktop | ✅ Auto-configured | Just install |
| Antigravity | ✅ Auto-configured | Just install |
📖 Manual IDE Setup → | VS Code + Copilot Guide →
📦 System Requirements
| Component | Minimum | Recommended |
|---|---|---|
| CPU | 4 cores | 8+ cores |
| RAM | 16 GB | 32 GB |
| Disk | 10 GB free | 20 GB SSD |
| GPU | Not required | NVIDIA 8GB+ VRAM (faster) |
| Docker | Required | Required |
📚 Documentation
Getting Started
- Quick Start Guide - Install in 5 minutes
- IDE Setup - Manual IDE configuration
Configuration & Operations
- Configuration Guide - Models, env vars, advanced settings
- Troubleshooting - Common issues and solutions
- Docker Setup - Docker configuration details
Language Analyzers
- Go Analyzer - Functions, types, interfaces, GoDoc
- PHP Analyzer - Classes, traits, PHPDoc
- Laravel Analyzer - Eloquent, routes, controllers
- Python Analyzer - Classes, decorators, type hints
Technical Reference
- Architecture Overview - Technical deep dive
- Tool Schema Reference - Complete API documentation
- Incremental Indexing - How smart indexing works
- Workspace Detection - Multi-workspace support
- VS Code + Copilot - Detailed Copilot setup
External Resources
- Model Context Protocol - Official MCP specification
- Ollama - Local LLM and embedding models
- Qdrant - Vector database
🤝 Contributing
We welcome contributions! Here's how you can help:
- 🐛 Report Bugs
- 💡 Request Features - Share ideas for new tools or languages
- 🔧 Submit PRs - Improve code, docs, or add features
- ⭐ Star the Project - Show your support
Development Setup
git clone https://github.com/doITmagic/rag-code-mcp.git
cd rag-code-mcp
go mod download
go run ./cmd/rag-code-mcp
📄 License
RagCode MCP is open source software licensed under the MIT License.
🏷️ Keywords & Topics
semantic-code-search rag retrieval-augmented-generation mcp-server model-context-protocol ai-code-assistant vector-search code-navigation ollama qdrant github-copilot cursor-ai windsurf go php laravel python django flask fastapi code-intelligence ast-analysis embeddings llm-tools local-ai privacy-first offline-ai self-hosted on-premise zero-cost no-cloud private-code-search enterprise-ai secure-coding-assistant
Built with ❤️ for developers who want smarter AI code assistants
⭐ Star us on GitHub if RagCode helps your workflow!
Questions? Open an Issue • Read the Docs • Join Discussions
Directories