Code Search MCP Server (TypeScript)

🚀 Give Claude Code superpowers — Semantic code search that lets Claude explore your codebase intelligently without reading every file.

Instead of loading entire directories into context, Claude can now:

• 🔍 Find relevant code with natural language queries
• 🎯 Locate specific functions/classes instantly
• 💡 Understand unfamiliar codebases quickly
• ⚡ Work efficiently even in massive repositories

Written in TypeScript for zero-friction installation with npx.

Installation

No installation needed! Just use npx:

npx @cr0hn/code-search-mcp

Or install globally:

npm install -g @cr0hn/code-search-mcp

Usage with Claude Code

Add to your ~/.config/claude-code/mcp.json:

{
  "mcpServers": {
    "code-search": {
      "command": "npx",
      "args": ["-y", "@cr0hn/code-search-mcp"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "ADELINA_BASE_URL": "http://localhost:8000"
      }
    }
  }
}

That's it! No Python, no git clone, no pip install. Just npx.

Prerequisites

• Node.js 18+ (you probably already have it)
• Running Qdrant and Adelina services (via docker-compose)

Environment Variables

• QDRANT_URL - Qdrant server URL (default: http://localhost:6333)
• ADELINA_BASE_URL - Adelina embedding service URL (default: http://localhost:8000)
• QDRANT_COLLECTION - Collection name (default: code_chunks)
• EMBEDDING_MODEL - Embedding model name (default: jinaai/jina-embeddings-v2-base-code)

MCP Tools

Claude Code automatically gets access to these powerful tools:

🔍 search_code - Semantic Code Search

What it does: Finds relevant code using natural language, understanding the meaning not just keywords.

When Claude uses it:

• User asks "how does X work?" → Claude searches before reading files
• Before implementing features → Finds similar existing patterns
• During debugging → Locates error-related code
• Understanding architecture → Discovers patterns and connections

Parameters:

• query (required): What you're looking for in natural language
  • Example: "authentication and user login logic"
  • Example: "database connection pool configuration"
  • Example: "API endpoints for payment processing"
• project_id (optional): Focus on specific project/repo
• limit (optional): Number of results 1-50 (default: 10)
• score_threshold (optional): Relevance cutoff 0.0-1.0
• response_mode (optional): Output format - NEW!
  • "full" (default): Complete code with full context
  • "summary": Grouped by file, first lines only (saves ~80% tokens)
  • "signatures": Function/class signatures only (saves ~90% tokens)

Example queries:

// Find auth code (full mode)
search_code({ query: "user authentication and session management" })

// Quick overview (summary mode - saves tokens!)
search_code({ query: "payment processing", response_mode: "summary" })

// See what exists (signatures only)
search_code({ query: "error handlers", response_mode: "signatures", limit: 20 })

// Project-specific search
search_code({ query: "error handling middleware", project_id: "api-server" })

🎯 search_by_symbol - Exact Symbol Search

What it does: Finds all occurrences of a specific function, class, or method name.

When Claude uses it:

• User mentions specific function/class → Instant location
• Refactoring → Find all usages before changes
• Understanding implementation → Find the actual code
• Following call chains → Start from entry points

Parameters:

• symbol (required): Exact name (case-sensitive)
  • Functions: handleRequest, processPayment
  • Classes: UserController, PaymentService
  • Methods: authenticate, validate
• project_id (optional): Filter by project
• limit (optional): Max results (default: 10)

Example queries:

// Find specific function
search_by_symbol({ symbol: "authenticate" })

// Find all UserController classes
search_by_symbol({ symbol: "UserController" })

// Project-specific
search_by_symbol({ symbol: "handlePayment", project_id: "checkout" })

📚 list_indexed_projects - See What's Available NEW!

What it does: Lists all indexed projects with statistics (files, chunks, languages).

When Claude uses it:

• At session start → Know what's available before searching
• User asks "what projects do you have?" → Show all indexed projects
• Before using project_id filter → Verify the project exists
• Understanding codebase scope → See size and coverage

Parameters: None required

Example:

// See all indexed projects
list_indexed_projects()

// Returns:
// 📚 Indexed Projects (3)
//
// 📦 `backend`
// - Files: 150
// - Code chunks: 1,247
// - Languages: python, typescript
//
// 📦 `frontend`
// - Files: 89
// - Code chunks: 623
// - Languages: typescript, css

Token savings: Tells Claude what exists without searching = 0 tokens used for exploration!

📋 get_code_structure - File Outline Without Code NEW!

What it does: Shows file structure (classes, functions, methods) without implementations.

When Claude uses it:

• Before reading a file → See what's in it first
• User asks "what's in this file?" → Show outline instead of full code
• Finding specific functions → See all functions without reading code
• Understanding file organization → Quick overview

Parameters:

• path (required): File path (from search results)
• project_id (optional): Filter to specific project (for monorepos)

Example:

// See file structure
get_code_structure({ path: "src/auth.py" })

// Returns:
// 📄 Code Structure: `src/auth.py`
// Language: python | Project: backend | Chunks: 8
//
// 🏛️ Classes (2)
// - `AuthService` (lines 10-45)
//   ```python
//   class AuthService:
//   ```
//
// ⚡ Functions (6)
// - `authenticate` (lines 50-75)
//   ```python
//   def authenticate(username, password):
//   ```
// - `verify_token` (lines 80-95)
//   ...

Token savings: ~90% vs reading full file. A 500-line file → ~50 lines of structure!

How It Works

User: "How does authentication work?"
           ↓
Claude: Uses search_code("authentication and login")
           ↓
MCP Server: Converts query → embedding → searches Qdrant
           ↓
Returns: Relevant code chunks with file:line references
           ↓
Claude: Analyzes results, explains to user

No need to read 1000s of files! 🎉

Development

# Install dependencies
npm install

# Run in dev mode
npm run dev

# Build
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with UI
npm run test:ui

# Publish
npm publish

Testing

Comprehensive test suite with 17 tests covering all functionality:

# Run all tests once
npm test

# Watch mode for development
npm run test:watch

# Interactive UI
npm run test:ui

Test Coverage:

• ✅ listIndexedProjects: empty collection, single project, multiple projects, pagination
• ✅ getCodeStructure: file not found, single file, multiple chunks, grouping by type
• ✅ searchCode: full/summary/signatures modes, filters, edge cases
• ✅ Error handling: API failures, malformed responses, connection issues

All tests use Vitest with mocked Qdrant and Adelina clients.

Complete Setup Example

# 1. Start backend services
curl -O https://raw.githubusercontent.com/cr0hn/the-opensource-context/main/infra/docker/docker-compose.yml
docker compose up -d

# 2. Install and run indexer client
pip install codeindex
codeindex agent --project-id my-app --path . --server http://localhost:8080 --token dev_token_123

# 3. Configure Claude Code (see above)

# 4. Done! Ask Claude: "Find authentication code in my-app"

Why TypeScript?

• ✅ No Python required - Works with just Node.js
• ✅ npx support - No installation needed
• ✅ Fast startup - Native JavaScript performance
• ✅ Easy distribution - Standard npm package

License

MIT