rag-code-mcp

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.

🔒 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
• ✅ Complete Privacy - Your proprietary code stays private and secure
• ✅ Offline Capable - Works without internet connection (after initial model download)
• ✅ Full Control - You own the data, models, and infrastructure

Perfect for: Enterprise codebases, proprietary projects, security-conscious teams, and developers who value privacy.

🎯 Key Features

• 🔍 Semantic Code Search - Find code by meaning, not just keywords
• 🚀 5-10x Faster - Instant results vs. reading entire files
• 💰 98% Token Savings - Reduce AI context usage dramatically
• 🌐 Multi-Language - Go, PHP (Laravel), Python, JavaScript support
• 🏢 Multi-Workspace - Handle multiple projects simultaneously
• 🤖 AI-Ready - Works with Copilot, Cursor, Windsurf, Claude, Antigravity

🛠️ Technology Stack

100% Local Stack: Ollama (local LLM + embeddings) + Qdrant (local vector database) + Docker + MCP Protocol

💻 Compatible IDEs & AI Assistants

Windsurf • Cursor • Antigravity • Claude Desktop • VS Code + GitHub Copilot • MCP Inspector

---

🚀 Why RagCode? Performance Benefits

5-10x Faster Code Understanding

Without RagCode, AI assistants must:

• 📄 Read entire files to find relevant code
• 🔍 Search through thousands of lines manually
• 💭 Use precious context window tokens on irrelevant code
• ⏱️ Wait for multiple file reads and searches

With RagCode:

• ⚡ Instant semantic search - finds relevant code in milliseconds
• 🎯 Pinpoint accuracy - returns only the exact functions/types you need
• 💰 90% less context usage - AI sees only relevant code, not entire files
• 🧠 Smarter responses - AI has more tokens for actual reasoning

Real-World Impact

Task	Without RagCode	With RagCode	Speedup
Find authentication logic	30-60s (read 10+ files)	2-3s (semantic search)	10-20x faster
Understand function signature	15-30s (grep + read file)	1-2s (direct lookup)	15x faster
Find all API endpoints	60-120s (manual search)	3-5s (hybrid search)	20-40x faster
Navigate type hierarchy	45-90s (multiple files)	2-4s (type definition)	20x faster

Token Efficiency

Example: Finding a function in a 50,000 line codebase

• Without RagCode: AI reads 5-10 files (~15,000 tokens) to find the function
• With RagCode: AI gets exact function + context (~200 tokens)
• Savings: 98% fewer tokens = faster responses + lower costs

🆚 RagCode vs Cloud-Based Solutions

Feature	RagCode (Local)	Cloud-Based AI Code Search
Privacy	✅ 100% local, code never leaves machine	❌ Code sent to cloud servers
Cost	✅ $0 - Free forever	❌ $20-100+/month subscriptions
API Limits	✅ Unlimited usage	❌ Rate limits, token caps
Offline	✅ Works without internet	❌ Requires constant connection
Data Control	✅ You own everything	❌ Vendor controls your data
Enterprise Ready	✅ No compliance issues	⚠️ May violate security policies
Setup	⚠️ Requires local resources	✅ Instant cloud access
Performance	✅ Fast (local hardware)	⚠️ Depends on network latency

Bottom Line: RagCode gives you enterprise-grade AI code search with zero privacy concerns and zero ongoing costs.

---

✨ Core Features & Capabilities

🔧 9 Powerful MCP Tools for AI Code Assistants

1. search_code - Semantic vector search across your entire codebase
2. hybrid_search - Combined semantic + keyword search for maximum accuracy
3. get_function_details - Complete function signatures, parameters, and implementation
4. find_type_definition - Locate class, struct, and interface definitions instantly
5. find_implementations - Discover all usages and implementations of any symbol
6. list_package_exports - Browse all exported symbols from any package/module
7. search_docs - Semantic search through project documentation (Markdown)
8. get_code_context - Extract code snippets with surrounding context
9. index_workspace - Automated workspace indexing with language detection

🌐 Multi-Language Code Intelligence

• Go - ≈82% coverage with full AST analysis
• PHP - ≈84% coverage + Laravel framework support
• Python - Coming soon with full type hint support
• JavaScript/TypeScript - Planned for future releases

🏗️ Advanced Architecture

• Multi-Workspace Detection - Automatically detects project boundaries (git, go.mod, composer.json, package.json)
• Per-Language Collections - Separate vector databases for each language (ragcode-{workspace}-go, ragcode-{workspace}-php)
• Automatic Indexing - Background indexing on first use, no manual intervention needed
• Incremental Indexing - Smart re-indexing that only processes changed files, saving time and resources
• Vector Embeddings - Uses Ollama's nomic-embed-text for high-quality semantic embeddings
• Hybrid Search Engine - Combines vector similarity with BM25 lexical matching
• Direct File Access - Read code without indexing for quick lookups
• Smart Caching - Efficient re-indexing only for changed files

---

📦 System Requirements

Minimum Requirements

Component	Requirement	Notes
CPU	4 cores	For running Ollama models
RAM	16 GB	8 GB for phi3:medium, 4 GB for nomic-embed-text, 4 GB system
Disk	10 GB free	~8 GB for models + 2 GB for data
OS	Linux, macOS, Windows	Docker required for Qdrant

Recommended Requirements

Component	Requirement	Notes
CPU	8+ cores	Better performance for concurrent operations
RAM	32 GB	Allows comfortable multi‑workspace indexing
GPU	NVIDIA GPU with 8 GB+ VRAM	Significantly speeds up Ollama inference (optional)
Disk	20 GB free SSD	Faster indexing and search

Model Sizes

• nomic-embed-text: ~274 MB (embeddings model)
• phi3:medium: ~7.9 GB (LLM for code analysis)
• Total: ~8.2 GB for models

---

⚡ Quick Start

One-Command Installation

Linux (amd64):

curl -L https://github.com/doITmagic/rag-code-mcp/releases/latest/download/rag-code-mcp_linux_amd64.tar.gz | tar xz
./ragcode-installer -ollama=docker -qdrant=docker

macOS (Apple Silicon):

curl -L https://github.com/doITmagic/rag-code-mcp/releases/latest/download/rag-code-mcp_darwin_arm64.tar.gz | tar xz
./ragcode-installer -ollama=docker -qdrant=docker

macOS (Intel):

curl -L https://github.com/doITmagic/rag-code-mcp/releases/latest/download/rag-code-mcp_darwin_amd64.tar.gz | tar xz
./ragcode-installer -ollama=docker -qdrant=docker

Windows (PowerShell – in progress):

Invoke-WebRequest -Uri "https://github.com/doITmagic/rag-code-mcp/releases/latest/download/rag-code-mcp_windows_amd64.zip" -OutFile "rag-code-mcp.zip"
Expand-Archive rag-code-mcp.zip -DestinationPath .
.\ragcode-installer.exe -ollama docker -qdrant docker

⚠️ Windows support is still being finalized. Use WSL/Linux/macOS if you hit issues.

What the installer does:

1. ✅ Downloads and installs the rag-code-mcp binary
2. ✅ Sets up Ollama and Qdrant (Docker or local, your choice)
3. ✅ Downloads required AI models (phi3:medium, nomic-embed-text)
4. ✅ Configures your IDE (VS Code, Claude, Cursor, Windsurf)
5. ✅ Adds binaries to your PATH

Zero-Config Usage

Once installed, you don't need to configure anything.

1. Open your project in your IDE (VS Code, Cursor, Windsurf).
2. Ask your AI assistant a question about your code (e.g., "How does the authentication system work?").
3. That's it! RagCode automatically detects your workspace, creates the index in the background, and answers your question.
   • First query might take a moment while indexing starts.
   • Subsequent queries are instant.
   • File changes are automatically detected and re-indexed incrementally.

Installation Options

The installer runs both Ollama and Qdrant inside Docker by default. Popular scenarios:

# Recommended (everything inside Docker)
./ragcode-installer -ollama=docker -qdrant=docker

# Use an existing local Ollama but keep Qdrant in Docker
./ragcode-installer -ollama=local -qdrant=docker

# Point to remote services you already manage
./ragcode-installer -ollama=local -qdrant=remote --skip-build

# Enable GPU acceleration for the Ollama container
./ragcode-installer -ollama=docker -qdrant=docker -gpu

# Mount a custom directory with Ollama models when running in Docker
./ragcode-installer -ollama=docker -models-dir=$HOME/.ollama

Key flags:

• -ollama: docker (default) or local
• -qdrant: docker (default) or remote
• -models-dir: host path to mount as /root/.ollama
• -gpu: passes --gpus=all to the Ollama container
• -skip-build: reuse existing binaries instead of rebuilding

See QUICKSTART.md for detailed installation and usage instructions.

Manual Build (for developers)

git clone https://github.com/doITmagic/rag-code-mcp.git
cd rag-code-mcp
go run ./cmd/install

---

📋 Step‑by‑Step Setup

1. Install Prerequisites

Docker (for Qdrant)

# Ubuntu/Debian
sudo apt update && sudo apt install docker.io
sudo systemctl start docker
sudo usermod -aG docker $USER   # log out / log in again

# macOS
brew install docker

Ollama (for AI models)

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# macOS
brew install ollama

2. Run the Installer

# Linux (amd64)
curl -L https://github.com/doITmagic/rag-code-mcp/releases/latest/download/rag-code-mcp_linux_amd64.tar.gz | tar xz
./ragcode-installer -ollama=docker -qdrant=docker

Installation takes 5‑10 minutes (downloading the Ollama models is the long pole).

3. Verify Installation

# Check the binary
~/.local/share/ragcode/bin/rag-code-mcp --version

# Verify services are running
docker ps | grep qdrant
ollama list

4. Health check (services start automatically)

~/.local/share/ragcode/bin/rag-code-mcp --health
docker ps | grep ragcode-qdrant
docker ps | grep ragcode-ollama

---

🎯 Using RagCode in Your IDE

After installation, RagCode is automatically available in supported IDEs. No additional configuration is required.

Supported IDEs

• Windsurf - Full MCP support
• Cursor - Full MCP support
• Antigravity - Full MCP support
• Claude Desktop - Full MCP support
• VS Code + GitHub Copilot - Agent mode integration (requires VS Code 1.95+)

VS Code + GitHub Copilot Integration

RagCode integrates with GitHub Copilot's Agent Mode through MCP, enabling semantic code search as part of Copilot's autonomous workflow.

Quick Setup:

1. Install RagCode with ragcode-installer (it configures VS Code automatically)
2. Open VS Code in your project
3. Open Copilot Chat (Ctrl+Shift+I / Cmd+Shift+I)
4. Enable Agent Mode (click "Agent" button or type /agent)
5. Ask questions - Copilot will automatically use RagCode tools

Example Prompts:

Find all authentication middleware functions in this codebase
Show me the User model definition and all its methods
Search for functions that handle database connections

Manual Configuration:
Edit ~/.config/Code/User/globalStorage/mcp-servers.json:

{
  "mcpServers": {
    "ragcode": {
      "command": "/home/YOUR_USERNAME/.local/share/ragcode/bin/rag-code-mcp",
      "args": [],
      "env": {
        "OLLAMA_BASE_URL": "http://localhost:11434",
        "OLLAMA_MODEL": "phi3:medium",
        "OLLAMA_EMBED": "nomic-embed-text",
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

Verify Integration:

• Command Palette → MCP: Show MCP Servers
• Check that ragcode appears with "Connected" status

📖 Detailed Guide: See docs/vscode-copilot-integration.md for complete setup, troubleshooting, and advanced features.

See QUICKSTART.md for detailed VS Code setup and troubleshooting.

Available Tools

1. search_code – semantic code search
2. hybrid_search – semantic + lexical search
3. get_function_details – detailed information about a function or method
4. find_type_definition – locate struct, interface, or type definitions
5. find_implementations – find implementations or usages of a symbol
6. list_package_exports – list all exported symbols in a package
7. search_docs – search markdown documentation
8. index_workspace – manually trigger indexing of a workspace (usually not needed)
9. get_code_context – read code from specific file locations with context

All tools require a file_path parameter so that RagCode can determine the correct workspace.

---

🔄 Automatic Indexing

When a tool is invoked for the first time in a workspace, RagCode will:

1. Detect the workspace from file_path
2. Create a Qdrant collection for that workspace and language
3. Index the code in the background
4. Return results immediately (even if indexing is still in progress)

You never need to run index_workspace manually.

⚡ Incremental Indexing

RagCode features smart incremental indexing that dramatically reduces re-indexing time by only processing files that have changed.

How it works:

• Tracks file modification times and sizes in .ragcode/state.json
• On subsequent indexing runs, compares current state with saved state
• Only indexes new or modified files
• Automatically removes outdated chunks from deleted/modified files

Performance Benefits:

• First run: Indexes all files (e.g., 77 files in ~20 seconds)
• No changes: Completes instantly with "No code changes detected"
• Single file change: Re-indexes only that file (e.g., 1 file in ~1 second)

Example:

# First run
./bin/index-all -paths /path/to/project
# Output: "📝 Indexing 77 new/modified files..."

# Second run (no changes)
./bin/index-all -paths /path/to/project
# Output: "✨ No code changes detected for language 'go'"

# After modifying one file
./bin/index-all -paths /path/to/project
# Output: "📝 Indexing 1 new/modified files..."

Note: Incremental indexing applies to source code files. Markdown documentation is currently re-indexed on every run.

For technical details, see docs/incremental_indexing.md.

---

🛠 Advanced Configuration

Changing AI Models

Edit ~/.local/share/ragcode/config.yaml:

llm:
  provider: "ollama"
  base_url: "http://localhost:11434"
  model: "phi3:medium"        # change to another model if desired
  embed_model: "nomic-embed-text"

Recommended models:

• LLM: phi3:medium, llama3.1:8b, qwen2.5:7b
• Embeddings: nomic-embed-text, all-minilm

Qdrant Configuration

qdrant:
  url: "http://localhost:6333"
  collection_prefix: "ragcode"

Excluding Directories

workspace:
  exclude_patterns:
    - "vendor"
    - "node_modules"
    - ".git"
    - "dist"
    - "build"

---

🐛 Troubleshooting

"Workspace '/home' is not indexed yet"

Cause: file_path is missing or points outside a recognized project. Fix: Provide a valid file_path inside your project, e.g.:

{ "query": "search query", "file_path": "/path/to/your/project/file.go" }

"Could not connect to Qdrant"

Cause: Docker is not running or the Qdrant container is stopped. Fix:

sudo systemctl start docker   # Linux
# Then start Qdrant (the installer does this automatically)
~/.local/share/ragcode/start.sh

"Ollama model not found"

Cause: Required models have not been downloaded. Fix:

ollama pull nomic-embed-text
ollama pull phi3:medium

Indexing is too slow

Cause: Large workspace or a heavy model. Fix:

• Use a smaller model (phi3:mini)
• Exclude large directories in config.yaml
• Wait – indexing runs in the background.

---

📚 Example Requests

{ "query": "user authentication login", "file_path": "/home/user/myproject/auth/handler.go" }

{ "type_name": "UserController", "file_path": "/home/user/laravel-app/app/Http/Controllers/UserController.php" }

{ "query": "API endpoints documentation", "file_path": "/home/user/myproject/docs/API.md" }

---

🔗 Resources & Documentation

📖 Project Documentation

• Quick Start Guide - Get started in 5 minutes
• VS Code + Copilot Integration - Detailed setup for GitHub Copilot
• Architecture Overview - Technical deep dive
• Tool Schema Reference - Complete API documentation

🌐 External Resources

• GitHub Repository - Source code and releases
• Issue Tracker - Report bugs or request features
• Model Context Protocol - Official MCP specification
• Ollama Documentation - LLM and embedding models
• Qdrant Documentation - Vector database guide

🎓 Learning Resources

• What is RAG? - Understanding Retrieval-Augmented Generation
• Vector Embeddings Explained - How semantic search works
• MCP for Developers - Building MCP servers

---

🤝 Contributing & Community

We welcome contributions from the community! Here's how you can help:

• 🐛 Report Bugs - Open an issue
• 💡 Request Features - Share your ideas for new tools or languages
• 🔧 Submit PRs - Improve code, documentation, or add new features
• ⭐ Star the Project - Show your support on GitHub
• 📢 Spread the Word - Share RagCode with other developers

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.

See the LICENSE file for full details.

---

🏷️ 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 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

---