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 GitHub Copilot

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

🚀 Getting Started

📖 Full Documentation - Complete documentation
⚙️ Setup Guide - Installation and configuration
⚡ Quick Reference - Command cheat sheet
🗺️ Navigation Guide - Find any doc quickly

💻 For Developers

Source Code Structure - Code organization
MCP Server Guide - Build your own MCP server
Roadmap - Future plans

🔧 Resources

Qdrant Setup - Get Qdrant credentials
Testing Guide - Test search functionality
Prompt Enhancement Guide - Use prompt enhancement effectively
Changelog - Version history

✨ Features

🔍 Semantic Search - Find code by meaning, not just keywords
🎯 Smart Chunking - Automatically splits code into logical functions/classes
🔄 Incremental Indexing - Only re-indexes changed files (90%+ time savings)
💾 Auto-save Checkpoints - Saves progress every 10 files, resume anytime
📊 Real-time Progress - Track indexing with ETA and performance metrics
⚡ Parallel Processing - 25x faster indexing with batch execution
🔄 Real-time Watch - Auto-updates index on file changes
🌐 Multi-language - Supports 15+ programming languages
☁️ Vector Storage - Uses Qdrant for persistent storage
🤖 Prompt Enhancement - AI-powered query improvement (optional)
📦 Simple Setup - Just 4 environment variables

🚀 Quick Start

Prerequisites

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

Installation

Step 1: Open MCP Configuration in VS Code

Open GitHub Copilot Chat (Ctrl+Alt+I / Cmd+Alt+I)
Click Settings icon → MCP Servers → MCP Configuration (JSON)

Step 2: Add this configuration to mcp.json:

{
  "servers": {
    "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..."
      },
      "type": "stdio"
    }
  }
}

Step 3: Restart VS Code

The server will automatically:

Connect to Qdrant Cloud
Index your codebase
Watch for file changes

📖 Detailed instructions: Setup Guide

📖 Usage

Search Your Codebase

Ask GitHub Copilot:

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

Check Indexing Status

"Check indexing status"
"Show me detailed indexing progress"

📖 More examples: Testing Guide

🎯 Prompt Enhancement (Optional)

TL;DR: Prompt enhancement is a transparent background tool that automatically improves search quality. Just ask naturally - no need to mention "enhance" in your prompts.

Quick Overview

When enabled (PROMPT_ENHANCEMENT=true), the AI automatically:

Enhances your search query with codebase context
Searches with the improved query
Continues with your original request (implement, fix, explain, etc.)

Good Prompts ✅

✅ "Find authentication logic and add 2FA support"
✅ "Locate payment flow and fix the timeout issue"
✅ "Search for profile feature and add bio field"

Why these work: Clear goal (find + action) → AI knows what to do

Bad Prompts ❌

❌ "Enhance and search for authentication"
❌ "Use prompt enhancement to find profile"

Why these fail: No clear action → AI stops after search

Key Principle

Prompt enhancement is invisible infrastructure.

Just tell the AI what you want to accomplish. It will automatically use enhancement to improve search quality behind the scenes.

Think of it like autocomplete: You don't say "use autocomplete" - you just type and it helps automatically.

📖 Learn More

For detailed guide including:

Technical details and architecture
Configuration options
Real-world examples (TypeScript, Python, Dart, etc.)
Performance tips and optimization
Troubleshooting and FAQ
Advanced use cases

See: Prompt Enhancement Guide

🎛️ 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",
    "EMBEDDING_MODEL": "text-embedding-004",
    "PROMPT_ENHANCEMENT": "true"
  }
}

📖 Full configuration guide: Setup Guide

🌍 Supported Languages

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

📊 Performance

Metric	Value
Indexing Speed	~25 files/min
Search Latency	<100ms
Incremental Savings	90%+ time reduction
Parallel Processing	25 chunks/sec

📖 Performance details: Main Documentation

🐛 Troubleshooting

Server not appearing?

Check Copilot Chat → Settings → MCP Servers → Show Output
Verify all 4 env variables are set
Ensure REPO_PATH is absolute path

Can't connect to Qdrant?

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

Indexing too slow?

Large repos take 5-10 minutes initially
Subsequent runs only index changed files (90%+ faster)

📖 More troubleshooting: Main Documentation

📁 Project Structure

mcp-codebase-index/
├── docs/                    # All documentation
│   ├── README.md           # Main documentation
│   ├── SETUP.md            # Setup guide
│   ├── NAVIGATION.md       # Navigation guide
│   ├── guides/             # Detailed guides
│   └── planning/           # Development planning
│
├── src/                     # Source code
│   ├── core/               # Core business logic
│   ├── storage/            # Data persistence
│   ├── enhancement/        # Prompt enhancement
│   ├── mcp/                # MCP server
│   ├── types/              # Type definitions
│   └── index.ts            # Entry point
│
├── config/                  # Configuration files
├── .data/                   # Runtime data (gitignored)
├── package.json
└── README.md               # This file

📖 Detailed structure: Source Code Structure

🔧 Development

Build

npm run build

Run Locally

npm run dev

Test

npm test

📖 Development guide: Source Code Structure

🤝 Contributing

Contributions welcome! Check out:

Improvement Plan - Roadmap
Issues - Detailed feature docs
Source Code - Code structure

📄 License

MIT © NgoTaiCo

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: ngotaico.flutter@gmail.com

⭐ If you find this useful, please star the repo!

@ngotaico/mcp-codebase-index