Package Exports

@ngotaico/mcp-codebase-index
@ngotaico/mcp-codebase-index/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@ngotaico/mcp-codebase-index) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

MCP Codebase Index Server

AI-powered semantic search for your codebase in Claude Desktop

A Model Context Protocol (MCP) server that enables Claude to search and understand your codebase using Google's Gemini embeddings and Qdrant Cloud vector storage.

✨ Features

🔍 Semantic Search: Find code by meaning, not just keywords
🎯 Smart Chunking: Automatically splits code into logical functions/classes
🔄 Real-time Watch: Monitors file changes and updates index automatically
🌐 Multi-language: Supports 15+ programming languages
☁️ Cloud Storage: Uses Qdrant Cloud for persistent vector storage
📦 Simple Setup: Just 4 environment variables to get started

🚀 Quick Start

Prerequisites

Gemini API Key: Get free at Google AI Studio
Qdrant Cloud Account: Sign up free at cloud.qdrant.io

Installation

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "codebase": {
      "command": "npx",
      "args": ["-y", "@ngotaico/mcp-codebase-index"],
      "env": {
        "REPO_PATH": "/absolute/path/to/your/project",
        "GEMINI_API_KEY": "AIzaSyC...",
        "QDRANT_URL": "https://your-cluster.gcp.cloud.qdrant.io:6333",
        "QDRANT_API_KEY": "eyJhbGci..."
      }
    }
  }
}

All 4 variables are required:

Variable	Where to Get	Example
`REPO_PATH`	Absolute path to your project	`/Users/you/Projects/myapp`
`GEMINI_API_KEY`	Google AI Studio	`AIzaSyC...`
`QDRANT_URL`	Qdrant Cloud cluster URL	`https://xxx.gcp.cloud.qdrant.io:6333`
`QDRANT_API_KEY`	Qdrant Cloud API key	`eyJhbGci...`

Restart Claude Desktop

The server will automatically:

Connect to your Qdrant Cloud cluster
Create a collection (if needed)
Index your entire codebase
Watch for file changes

📖 Usage

Ask Claude to search your codebase:

"Find the authentication logic"
"Show me how database connections are handled"  
"Where is error logging implemented?"
"Find all API endpoint definitions"

🎛️ Configuration

Required Variables

{
  "env": {
    "REPO_PATH": "/Users/you/Projects/myapp",
    "GEMINI_API_KEY": "AIzaSyC...",
    "QDRANT_URL": "https://xxx.gcp.cloud.qdrant.io:6333",
    "QDRANT_API_KEY": "eyJhbGci..."
  }
}

Optional Variables

{
  "env": {
    "QDRANT_COLLECTION": "my_project",
    "WATCH_MODE": "true",
    "BATCH_SIZE": "50"
  }
}

Variable	Default	Description
`QDRANT_COLLECTION`	`codebase`	Collection name in Qdrant
`WATCH_MODE`	`true`	Auto-update on file changes
`BATCH_SIZE`	`50`	Embedding batch size

🔧 Setup Guides

SETUP.md - Detailed setup walkthrough
QDRANT_CLOUD_SETUP.md - Get Qdrant credentials
QUICK_REF.md - Quick reference card

🌍 Supported Languages

Python • TypeScript • JavaScript • Dart • Go • Rust • Java • Kotlin • Swift • Ruby • PHP • C • C++ • C# • Shell • SQL • HTML • CSS

📝 How It Works

┌─────────────┐
│  Your Code  │
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│  File Watcher   │  Monitors changes
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  Code Parser    │  Splits into chunks
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  Gemini API     │  Creates embeddings
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  Qdrant Cloud   │  Stores vectors
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  Claude Search  │  Semantic queries
└─────────────────┘

🐛 Troubleshooting

Server not appearing in Claude?

Check Claude logs:

tail -f ~/Library/Logs/Claude/mcp*.log

Common issues:

❌ REPO_PATH must be absolute path
❌ All 4 env variables must be set
❌ Qdrant URL must include :6333 port
❌ Gemini API key must be valid

Can't connect to Qdrant?

Test connection:

curl -H "api-key: YOUR_KEY" \
  https://YOUR_CLUSTER.gcp.cloud.qdrant.io:6333/collections

Should return JSON with collections list.

Indexing too slow?

Large repos (1000+ files) take 5-10 minutes initially
Reduce BATCH_SIZE if hitting rate limits
Check Gemini API quota: aistudio.google.com

📊 Performance

Embedding speed: ~100 chunks/minute (Gemini API)
Search latency: <100ms (Qdrant Cloud)
Storage: ~1KB per code chunk
Recommended: <10K chunks per collection

📄 License

MIT © NgoTaiCo

🤝 Contributing

Issues and PRs welcome at github.com/NgoTaiCo/mcp-codebase-index