CodeGrok

CodeGrok MCP

Semantic Code Search for AI Assistants

Give your AI assistant the power to truly understand your codebase

Features • Quick Start • Capabilities • Limitations • Integrations • Use Cases

What is CodeGrok MCP?

CodeGrok MCP is a Model Context Protocol (MCP) server that enables AI assistants to intelligently search and understand codebases using semantic embeddings and Tree-sitter parsing.

Unlike simple text search, CodeGrok understands code structure - it knows what functions, classes, and methods are, and can find relevant code even when you describe it in natural language.

You: "Where is authentication handled?"
CodeGrok: Returns auth middleware, login handlers, JWT validation code...

Why Use CodeGrok?

The Problem: AI assistants have limited context windows. Sending your entire codebase is expensive and often impossible.

The Solution: CodeGrok indexes your code once, then AI can query semantically and receive only the 5-10 most relevant code snippets—10-100x token reduction vs naive "read all files" approaches.

Features

• Semantic Code Search - Find code by meaning, not just keywords
• 9 Languages Supported - Python, JavaScript, TypeScript, C, C++, Go, Java, Kotlin, Bash
• 28 File Extensions - Comprehensive coverage including .jsx, .tsx, .mjs, .hpp, etc.
• Fast Parallel Indexing - 3-5x faster with multi-threaded parsing
• Incremental Updates - Only re-index changed files (auto mode)
• Local & Private - All data stays on your machine in .codegrok/ folder
• Zero LLM Dependencies - Lightweight, focused tool (no API keys required)
• GPU Acceleration - Auto-detects CUDA for faster embeddings
• Works with Any MCP Client - Claude, Cursor, Cline, and more

✅ What CodeGrok CAN Do

For Live Coding (AI-Assisted Development)

For Learning a New Codebase

❌ What CodeGrok CANNOT Do

Important: Understanding limitations helps you use the tool effectively.

Not Designed For

Technical Constraints

Quick Start

Installation

# Clone the repository
git clone https://github.com/rdondeti/CodeGrok_mcp.git
cd CodeGrok_mcp

# Option 1: Use setup script (recommended)
./setup.sh              # Linux/macOS
# or
.\setup.ps1             # Windows PowerShell

# Option 2: Manual install
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
pip install -e .

# Verify installation
codegrok-mcp --help

Setup script options:

First Index

Once integrated with your AI tool (see below), ask your assistant:

"Learn my codebase at /path/to/my/project"

Then search:

"Find how API endpoints are defined"
"Where is error handling implemented?"
"Show me the database models"

🎯 Use Cases

Use Case 1: Live Coding with AI

How CodeGrok Saves Tokens:

Without CodeGrok:
  AI tries to read entire codebase → exceeds context window → fails or costs $$

With CodeGrok:
  AI: "I need to add a new route"
    ↓ calls get_sources("Express route definition")
  CodeGrok: Returns routes/api.js:15, routes/auth.js:8
    ↓ AI reads only those 2 files
  Result: 10-100x fewer tokens, faster responses

Use Case 2: Learning a New Codebase

Step 1: "Learn my codebase at ~/projects/big-app"
Step 2: "Where is the main entry point?"
Step 3: "How is authentication implemented?"
Step 4: "Find the database connection logic"
Step 5: "Show me how API errors are handled"

Use Case 3: Code Review Assistance

"Find all functions that handle user input"
"Where is validation performed?"
"Show me error handling patterns"

🔌 AI Tool Integrations

Claude Code (CLI)

The easiest way to add CodeGrok to Claude Code:

# Add the MCP server
claude mcp add codegrok-mcp -- codegrok-mcp

Or manually add to your settings (~/.claude/settings.json):

{
  "mcpServers": {
    "codegrok": {
      "command": "codegrok-mcp"
    }
  }
}

Usage in Claude Code:

> learn my codebase at ./my-project
> find authentication logic
> where is the main entry point?

Claude Desktop

Add to your Claude Desktop configuration:

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

Restart Claude Desktop after saving.

Cursor

Cursor supports MCP servers through its extension system:

1. Open Settings → Extensions → MCP
2. Add Server Configuration:

{
  "codegrok": {
    "command": "codegrok-mcp",
    "transport": "stdio"
  }
}

Or add to .cursor/mcp.json in your project:

{
  "servers": {
    "codegrok": {
      "command": "codegrok-mcp"
    }
  }
}

Windsurf (Codeium)

Windsurf supports MCP through Cascade:

1. Open Cascade Settings
2. Navigate to MCP Servers
3. Add configuration:

{
  "codegrok": {
    "command": "codegrok-mcp",
    "transport": "stdio"
  }
}

Cline (VS Code)

Add to Cline's MCP settings in VS Code:

1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Search "Cline: Open MCP Settings"
3. Add:

{
  "mcpServers": {
    "codegrok": {
      "command": "codegrok-mcp"
    }
  }
}

Zed Editor

Zed supports MCP through its assistant panel. Add to settings:

{
  "assistant": {
    "mcp_servers": {
      "codegrok": {
        "command": "codegrok-mcp"
      }
    }
  }
}

Continue (VS Code/JetBrains)

Add to your Continue configuration (~/.continue/config.json):

{
  "mcpServers": [
    {
      "name": "codegrok",
      "command": "codegrok-mcp"
    }
  ]
}

Generic MCP Client

For any MCP-compatible client, use stdio transport:

# Command to run
codegrok-mcp

# Transport
stdio (stdin/stdout)

# Protocol
Model Context Protocol (MCP)

MCP Tools Reference

CodeGrok provides 4 tools for AI assistants:

Learn modes:

• auto (default): Smart detection - incremental reindex if exists, full index if new
• full: Force complete re-index (destroys existing index)
• load_only: Just load existing index without any indexing

Tool Examples

Learn a Codebase

{
  "tool": "learn",
  "arguments": {
    "path": "/home/user/my-project",
    "mode": "auto"
  }
}

Response:

{
  "success": true,
  "message": "Indexed 150 files with 1,247 symbols",
  "stats": {
    "total_files": 150,
    "total_symbols": 1247,
    "total_chunks": 2834,
    "indexing_time": 12.5
  }
}

Search for Code

{
  "tool": "get_sources",
  "arguments": {
    "question": "How is user authentication implemented?",
    "n_results": 5
  }
}

Response:

{
  "sources": [
    {
      "file": "src/auth/middleware.py",
      "symbol": "authenticate_request",
      "type": "function",
      "line": 45,
      "content": "def authenticate_request(request):\n    ...",
      "score": 0.89
    }
  ]
}

Incremental Update (using learn with auto mode)

{
  "tool": "learn",
  "arguments": {
    "path": "/home/user/my-project",
    "mode": "auto"
  }
}

Response (when index exists):

{
  "success": true,
  "mode_used": "incremental",
  "files_added": 2,
  "files_modified": 5,
  "files_deleted": 1
}

Supported Languages

Total: 9 languages, 28 file extensions

How It Works

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     MCP Client                               │
│        (Claude, Cursor, Cline, etc.)                        │
└─────────────────────────┬───────────────────────────────────┘
                          │ MCP Protocol (stdio)
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                   CodeGrok MCP Server                        │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   Parsers   │  │  Embeddings │  │   Vector Storage    │  │
│  │ (Tree-sitter)│  │ (Sentence   │  │    (ChromaDB)       │  │
│  │             │  │ Transformers)│  │                     │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Indexing Pipeline

Source Files → Tree-sitter Parser → Symbol Extraction →
Code Chunks → Embeddings → ChromaDB Storage

1. Parse: Tree-sitter extracts functions, classes, methods with signatures
2. Chunk: Code is split into semantic chunks with context (docstrings, imports, calls)
3. Embed: Sentence-transformers create vector embeddings
4. Store: ChromaDB persists vectors locally in .codegrok/

Search Pipeline

Query → Embedding → Vector Similarity → Ranked Results

1. Embed Query: Convert natural language to vector
2. Search: Find similar vectors in ChromaDB
3. Return: Top-k results with file paths, line numbers, and code snippets

Storage

All data is stored locally in your project:

your-project/
└── .codegrok/
    ├── chroma/           # Vector database
    └── metadata.json     # Index metadata (stats, file mtimes)

Configuration

Environment Variables

Embedding Models

The default model (nomic-ai/CodeRankEmbed) is optimized for code retrieval with:

• 768-dimensional embeddings
• 8192 max sequence length
• State-of-the-art performance on CodeSearchNet benchmarks

Security Note: trust_remote_code

The default embedding model (nomic-ai/CodeRankEmbed) requires trust_remote_code=True when loading via SentenceTransformers. This flag allows execution of custom Python code bundled with the model.

Why it's required:

• The model uses a custom Nomic BERT architecture that isn't part of the standard HuggingFace model library
• Custom files: modeling_hf_nomic_bert.py (model architecture), configuration_hf_nomic_bert.py (config)

Security audit: The custom code has been reviewed and contains:

• Standard PyTorch neural network definitions
• No exec(), eval(), or dynamic code execution
• No subprocess or shell commands
• No network requests beyond HuggingFace's standard model download APIs
• Only imports from trusted libraries (torch, transformers, einops, safetensors)

For maximum security:

• Review the model code yourself: nomic-ai/CodeRankEmbed on HuggingFace
• Pin to a specific model revision in production deployments
• Consider using Microsoft CodeBERT (microsoft/codebert-base) as an alternative that doesn't require trust_remote_code (with potential quality trade-offs)

Development

Setup

# Clone
git clone https://github.com/rdondeti/CodeGrok_mcp.git
cd CodeGrok_mcp

# Run setup script
./setup.sh              # Linux/macOS (includes dev dependencies)
.\setup.ps1             # Windows PowerShell

# For clean reinstall:
./setup.sh --clean

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=src/codegrok_mcp --cov-report=term-missing

# Run specific test categories
pytest tests/unit/ -v          # Fast unit tests
pytest tests/integration/ -v   # Integration tests (uses real embeddings)
pytest tests/mcp/ -v           # MCP protocol simulation tests

Code Quality

# Format code
black src/

# Type checking
mypy src/

# Linting
flake8 src/

FAQ & Troubleshooting

# Check installation
pip show codegrok-mcp

# Check Python version (need 3.10+)
python --version

# Reinstall
pip install -e .

• Large codebases (>10k files) take longer on first index
• Use learn again after first index for incremental updates (auto mode)
• Close other heavy applications
• Consider indexing a subdirectory first

• Be more specific in queries (e.g., "JWT token validation" instead of "auth")
• Re-index if codebase changed significantly
• Check that the code type you're searching exists

• Index smaller portions of the codebase
• The default coderankembed model uses ~500MB-2GB RAM
• Close other applications

Use learn tool first:

"Learn my codebase at /path/to/project"

Comparison with Other Tools

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing)
3. Make your changes
4. Run tests (pytest)
5. Format code (black src/)
6. Submit a Pull Request

Development Guidelines

• Follow Black formatting (line length 100)
• Add type hints to all functions
• Write tests for new features
• Update documentation

License

MIT License - see LICENSE for details.

Related Projects

• Model Context Protocol - The protocol that powers this integration
• Tree-sitter - Fast, accurate code parsing
• ChromaDB - Vector database for embeddings
• Sentence Transformers - State-of-the-art embeddings

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Made with ❤️ for developers who want AI that truly understands their code

⬆ Back to Top