# MCP Code Indexer 🚀
[](https://badge.fury.io/py/mcp-code-indexer)
[](https://pypi.org/project/mcp-code-indexer/)
[](https://opensource.org/licenses/MIT)
A production-ready **Model Context Protocol (MCP) server** that revolutionizes how AI agents navigate and understand codebases. Built for high-concurrency environments with advanced database resilience, the server provides instant access to intelligent descriptions, semantic search, and context-aware recommendations while maintaining 800+ writes/sec throughput.
## 🎯 What It Does
The MCP Code Indexer solves a critical problem for AI agents working with large codebases: **understanding code structure without repeatedly scanning files**. Instead of reading every file, agents can:
- **Query file purposes** instantly with natural language descriptions
- **Search across codebases** using full-text search
- **Get intelligent recommendations** based on codebase size (overview vs search)
- **Generate condensed overviews** for project understanding
Perfect for AI-powered code review, refactoring tools, documentation generation, and codebase analysis workflows.
## ⚡ Quick Start
### 👨💻 For Developers
Get started integrating MCP Code Indexer into your AI agent workflow:
```bash
# Install with Poetry
poetry add mcp-code-indexer
# Or with pip
pip install mcp-code-indexer
# Start the MCP server
mcp-code-indexer
# Connect your MCP client and start using tools
# See API Reference for complete tool documentation
```
### 🌐 For Web Applications
Enable HTTP/REST API access for browser-based applications:
```bash
# Start HTTP server with authentication
mcp-code-indexer --http --auth-token "your-secret-token"
# Custom host and port
mcp-code-indexer --http --host 0.0.0.0 --port 8080
# CORS configuration for web apps
mcp-code-indexer --http --cors-origins "https://localhost:3000" "https://myapp.com"
```
**🔗 [Complete HTTP API Reference →](docs/http-api.md)**
### 🤖 For AI-Powered Q&A
Ask questions about your codebase using natural language:
```bash
# Set OpenRouter API key for Claude access
export OPENROUTER_API_KEY="your-openrouter-api-key"
# Simple questions about project architecture
mcp-code-indexer --ask "What does this project do?" my-project
# Enhanced analysis with file search
mcp-code-indexer --deepask "How is authentication implemented?" web-app
# JSON output for programmatic use
mcp-code-indexer --ask "List the main components" my-project --json
```
**🤖 [Complete Q&A Interface Guide →](docs/qa-interface.md)**
### 🔧 For System Administrators
Deploy and configure the server for your team:
```bash
# Production deployment with custom settings
mcp-code-indexer \
--token-limit 64000 \
--db-path /data/mcp-index.db \
--cache-dir /var/cache/mcp \
--log-level INFO
# Check installation
mcp-code-indexer --version
```
### 🎯 For Everyone
**New to MCP Code Indexer?** Start here:
1. **Install**: `poetry add mcp-code-indexer` (or `pip install mcp-code-indexer`)
2. **Run**: `mcp-code-indexer --token-limit 32000`
3. **Connect**: Use your favorite MCP client
4. **Explore**: Try the `check_codebase_size` tool first
**Development Setup**:
```bash
# Clone and setup for contributing
git clone https://github.com/fluffypony/mcp-code-indexer.git
cd mcp-code-indexer
# Install with Poetry (recommended)
poetry install
# Or install in development mode with pip
pip install -e .
# Run the server
mcp-code-indexer --token-limit 32000
```
## 🔗 Git Hook Integration
🚀 **NEW Feature**: Automated code indexing with AI-powered analysis! Keep your file descriptions synchronized automatically as your codebase evolves.
### 👤 For Users: Quick Setup
```bash
# Set your OpenRouter API key
export OPENROUTER_API_KEY="sk-or-v1-your-api-key-here"
# Test git hook functionality
mcp-code-indexer --githook
# Install post-commit hook
cp examples/git-hooks/post-commit .git/hooks/
chmod +x .git/hooks/post-commit
```
### 👨💻 For Developers: How It Works
The git hook integration provides intelligent automation:
- **📊 Git Analysis**: Automatically analyzes git diffs after commits/merges
- **🤖 AI Processing**: Uses OpenRouter API with Anthropic's Claude Sonnet 4
- **⚡ Smart Updates**: Only processes files that actually changed
- **🔄 Overview Maintenance**: Updates project overview when structure changes
- **🛡️ Error Isolation**: Git operations continue even if indexing fails
- **⏱️ Rate Limiting**: Built-in retry logic with exponential backoff
### 🎯 Key Benefits
💡 **Zero Manual Work**: Descriptions stay current without any effort
⚡ **Performance**: Only analyzes changed files, not entire codebase
🔒 **Reliability**: Robust error handling ensures git operations never fail
🎛️ **Configurable**: Support for custom models and timeout settings
**Learn More**: See [Git Hook Setup Guide](docs/git-hook-setup.md) for complete configuration options and troubleshooting.
## 🧠 Vector Mode (BETA)
🚀 **NEW Feature**: Semantic code search with vector embeddings! Experience AI-powered code discovery that understands context and meaning, not just keywords.
### 🎯 What is Vector Mode?
Vector Mode transforms how you search and understand codebases by using AI embeddings:
- **🔍 Semantic Search**: Find code by meaning, not just text matching
- **⚡ Real-time Indexing**: Automatic embedding generation as code changes
- **🛡️ Secure by Default**: Comprehensive secret redaction before API calls
- **🌐 Multi-language**: Python, JavaScript, TypeScript with AST-based chunking
- **📊 Smart Chunking**: Context-aware code segmentation for optimal embeddings
### 🚀 Quick Start
```bash
# Install MCP Code Indexer (includes vector mode)
pip install mcp-code-indexer
# Set required API keys
export VOYAGE_API_KEY="pa-your-voyage-api-key"
export TURBOPUFFER_API_KEY="your-turbopuffer-api-key"
# Optional: Configure region (default: gcp-europe-west3)
export TURBOPUFFER_REGION="gcp-europe-west3"
# Start with vector mode enabled
mcp-code-indexer --vector
# The daemon automatically starts and begins indexing your projects
```
### 💡 Key Features
- **🔐 Secret Redaction**: 20+ pattern types automatically detected and redacted
- **🌳 Merkle Trees**: Efficient change detection without full directory scans
- **🎛️ Circuit Breakers**: Resilient API integration with automatic retry logic
- **📈 Production Ready**: Built for high-concurrency with comprehensive monitoring
### 🔧 Advanced Configuration
```bash
# Custom configuration
mcp-code-indexer --vector --vector-config /path/to/config.yaml
# HTTP mode with vector search
mcp-code-indexer --vector --http --port 8080
```
### 🛠️ Architecture
Vector Mode adds powerful new MCP tools:
- `vector_search` - Semantic code search across projects
- `similarity_search` - Find similar code patterns
- `dependency_search` - Discover code relationships
- `vector_status` - Monitor indexing progress
**Status**: Currently in BETA - foundations implemented, full pipeline in development.
## 🔧 Development Setup
### 👨💻 For Contributors
Contributing to MCP Code Indexer? Follow these steps for a proper development environment:
```bash
# Setup development environment
git clone https://github.com/fluffypony/mcp-code-indexer.git
cd mcp-code-indexer
# Install with Poetry (recommended)
poetry install
# Or use pip with virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -e .[dev]
# Verify installation
python main.py --help
mcp-code-indexer --version
```
⚠️ **Important**: The editable install (`pip install -e .`) is **required** for development. The project uses proper PyPI package structure with absolute imports like `from mcp_code_indexer.database.database import DatabaseManager`. Without editable installation, you'll get `ModuleNotFoundError` exceptions.
### 🎯 Development Workflow
```bash
# Activate virtual environment
source venv/bin/activate
# Run the server directly
python main.py --token-limit 32000
# Or use the installed CLI command
mcp-code-indexer --token-limit 32000
# Run tests
python -m pytest tests/ -v
# Run with coverage
python -m pytest tests/ --cov=src --cov-report=html
# Format code
black src/ tests/
isort src/ tests/
# Type checking
mypy src/
```
## 🛠️ MCP Tools Available
The server provides **11 powerful MCP tools** for intelligent codebase management. Whether you're an AI agent or human developer, these tools make navigating code effortless.
### 🎯 Essential Tools (Start Here)
| Tool | Purpose | When to Use |
|------|---------|-------------|
| **`check_codebase_size`** | Get navigation recommendations | First tool to call for any project |
| **`search_descriptions`** | Find files by functionality | When you need specific files |
| **`get_codebase_overview`** | Project architectural summary | Understanding system design |
### 🔧 Core Operations
| Tool | Purpose | Best For |
|------|---------|----------|
| **`get_file_description`** | Retrieve file summaries | Quick file understanding |
| **`update_file_description`** | Store detailed file analysis | AI agents updating descriptions |
| **`find_missing_descriptions`** | Scan for undocumented files | Maintenance and coverage |
### 🔍 Advanced Features
| Tool | Purpose | Use Case |
|------|---------|----------|
| **`get_all_descriptions`** | Complete project structure | Small-to-medium codebases |
| **`get_word_frequency`** | Technical vocabulary analysis | Domain understanding |
| **`update_codebase_overview`** | Create project documentation | Architecture documentation |
| **`search_codebase_overview`** | Search in project overviews | Finding specific topics |
### 🏥 System Health
| Tool | Purpose | For |
|------|---------|-----|
| **`check_database_health`** | Real-time performance monitoring | Production deployments |
💡 **Pro Tip**: Always start with `check_codebase_size` to get personalized recommendations for navigating your specific codebase.
**📖 Complete API Documentation**: [View all 11 tools with examples →](docs/api-reference.md)
## 🔗 Git Hook Integration
Keep your codebase documentation automatically synchronized with automated analysis on every commit:
```bash
# Analyze current staged changes
mcp-code-indexer --githook
# Analyze a specific commit
mcp-code-indexer --githook abc123def
# Analyze using HEAD syntax
mcp-code-indexer --githook HEAD
mcp-code-indexer --githook HEAD~1
mcp-code-indexer --githook HEAD~3
# Analyze a commit range (perfect for rebases)
mcp-code-indexer --githook abc123 def456
mcp-code-indexer --githook HEAD~5 HEAD
```
**🎯 Perfect for**:
- **Automated documentation** that never goes stale
- **Rebase-aware analysis** that handles complex git operations
- **Zero-effort maintenance** with background processing
See the **[Git Hook Setup Guide](docs/git-hook-setup.md)** for complete installation instructions including post-commit, post-merge, and post-rewrite hooks.
## 🏗️ Architecture Highlights
### 🚀 Performance Optimized
- **SQLite with WAL mode** for high-concurrency access (800+ writes/sec)
- **Smart connection pooling** with optimized pool size (3 connections default)
- **FTS5 full-text search** with prefix indexing for sub-100ms queries
- **Token-aware caching** to minimize expensive operations
- **Write operation serialization** to eliminate database lock conflicts
### 🛡️ Production Ready
- **Database resilience features** with <2% error rate under high load
- **Exponential backoff retry logic** with intelligent failure recovery
- **Comprehensive health monitoring** with automatic pool refresh
- **Structured JSON logging** with performance metrics tracking
- **Async-first design** with proper resource cleanup
- **MCP protocol compliant** with clean stdio streams
- **Upstream inheritance** for fork workflows
- **Git integration** with .gitignore support
### 👨💻 Developer Friendly
- **95%+ test coverage** with async support and concurrent access tests
- **Integration tests** for complete workflows including database stress testing
- **Performance benchmarks** for large codebases with resilience validation
- **Clear error messages** with MCP protocol compliance
- **Comprehensive configuration options** for production tuning
## 📖 Documentation
Comprehensive documentation organized by user journey and expertise level.
### 🚀 Getting Started (New Users)
| Guide | Purpose | Time Investment |
|-------|---------|-----------------|
| **[Quick Start](#-quick-start)** | Install and run your first server | 2 minutes |
| **[API Reference](docs/api-reference.md)** | Master all 11 MCP tools | 15 minutes |
| **[HTTP API Reference](docs/http-api.md)** | REST API for web applications | 10 minutes |
| **[Q&A Interface](docs/qa-interface.md)** | AI-powered codebase analysis | 8 minutes |
| **[Git Hook Setup](docs/git-hook-setup.md)** | Automate your workflow | 5 minutes |
### 🏗️ Production Deployment (Teams & Admins)
| Guide | Focus | Best For |
|-------|-------|----------|
| **[CLI Reference](docs/cli-reference.md)** | Complete command documentation | All users |
| **[Administrative Commands](docs/admin-commands.md)** | Project & database management | System administrators |
| **[Configuration Guide](docs/configuration.md)** | Production setup & tuning | System administrators |
| **[Performance Tuning](docs/performance-tuning.md)** | High-concurrency optimization | DevOps teams |
| **[Monitoring & Diagnostics](docs/monitoring.md)** | Production monitoring | Operations teams |
### 🔧 Advanced Topics (Power Users)
| Guide | Depth | For |
|-------|-------|-----|
| **[Architecture Overview](docs/architecture.md)** | System design deep dive | Developers & architects |
| **[Database Resilience](docs/database-resilience.md)** | Advanced error handling | Senior developers |
| **[Contributing Guide](docs/contributing.md)** | Development workflow | Contributors |
### 📋 Quick References
- **[Examples & Integrations](examples/)** - Ready-to-use configurations
- **[Troubleshooting](#🚨-troubleshooting)** - Common issues & solutions
- **[API Tools Summary](#🛠️-mcp-tools-available)** - All 11 tools at a glance
**📚 Reading Paths:**
- **New to MCP Code Indexer?** Quick Start → API Reference → HTTP API → Q&A Interface
- **Web developers?** Quick Start → HTTP API Reference → Q&A Interface → Git Hooks
- **AI/ML engineers?** Quick Start → Q&A Interface → API Reference → Git Hooks
- **Setting up for a team?** CLI Reference → Configuration → Administrative Commands → Monitoring
- **Contributing to the project?** Architecture → Contributing → API Reference
## 🚦 System Requirements
- **Python 3.8+** with asyncio support
- **SQLite 3.35+** (included with Python)
- **4GB+ RAM** for large codebases (1000+ files)
- **SSD storage** recommended for optimal performance
## 📊 Performance
Tested with codebases up to **10,000 files**:
- File description retrieval: **< 10ms**
- Full-text search: **< 100ms**
- Codebase overview generation: **< 2s**
- Merge conflict detection: **< 5s**
## 🔧 Advanced Configuration
### 👨💻 For Developers: Basic Configuration
```bash
# Production setup with custom limits
mcp-code-indexer \
--token-limit 50000 \
--db-path /data/mcp-index.db \
--cache-dir /tmp/mcp-cache \
--log-level INFO
# Enable structured logging
export MCP_LOG_FORMAT=json
mcp-code-indexer
```
### 🔧 For System Administrators: Database Resilience Tuning
Configure advanced database resilience features for high-concurrency environments:
```bash
# High-performance production deployment
mcp-code-indexer \
--token-limit 64000 \
--db-path /data/mcp-index.db \
--cache-dir /var/cache/mcp \
--log-level INFO \
--db-pool-size 5 \
--db-retry-count 7 \
--db-timeout 15.0 \
--enable-wal-mode \
--health-check-interval 20.0
# Environment variable configuration
export DB_POOL_SIZE=5
export DB_RETRY_COUNT=7
export DB_TIMEOUT=15.0
export DB_WAL_MODE=true
export DB_HEALTH_CHECK_INTERVAL=20.0
mcp-code-indexer --token-limit 64000
```
#### Configuration Options
| Parameter | Default | Description | Use Case |
|-----------|---------|-------------|----------|
| `--db-pool-size` | 3 | Database connection pool size | Higher for more concurrent clients |
| `--db-retry-count` | 5 | Max retry attempts for failed operations | Increase for unstable environments |
| `--db-timeout` | 10.0 | Transaction timeout (seconds) | Increase for large operations |
| `--enable-wal-mode` | true | Enable WAL mode for concurrency | Always enable for production |
| `--health-check-interval` | 30.0 | Health monitoring interval (seconds) | Lower for faster issue detection |
💡 **Performance Tip**: For environments with 10+ concurrent clients, use `--db-pool-size 5` and `--health-check-interval 15.0` for optimal throughput.
## 🤝 Integration Examples
### With AI Agents
```python
# Example: AI agent using MCP tools
async def analyze_codebase(project_path):
# Check if codebase is large
size_info = await mcp_client.call_tool("check_codebase_size", {
"projectName": "my-project",
"folderPath": project_path
})
if size_info["isLarge"]:
# Use search for large codebases
results = await mcp_client.call_tool("search_descriptions", {
"projectName": "my-project",
"folderPath": project_path,
"query": "authentication logic"
})
else:
# Get full overview for smaller projects
overview = await mcp_client.call_tool("get_codebase_overview", {
"projectName": "my-project",
"folderPath": project_path
})
```
### With CI/CD Pipelines
```yaml
# Example: GitHub Actions integration
- name: Update Code Descriptions
run: |
python -c "
import asyncio
from mcp_client import MCPClient
async def update_descriptions():
client = MCPClient('mcp-code-indexer')
# Find files without descriptions
missing = await client.call_tool('find_missing_descriptions', {
'projectName': '${{ github.repository }}',
'folderPath': '.'
})
# Process with AI and update...
asyncio.run(update_descriptions())
"
```
## 🧪 Testing
```bash
# Install with test dependencies using Poetry
poetry install --with test
# Or with pip
pip install mcp-code-indexer[test]
# Run full test suite
python -m pytest tests/ -v
# Run with coverage
python -m pytest tests/ --cov=src --cov-report=html
# Run performance tests
python -m pytest tests/ -m performance
# Run integration tests only
python -m pytest tests/integration/ -v
```
## 📈 Monitoring
The server provides structured JSON logs for monitoring:
```json
{
"timestamp": "2024-01-15T10:30:00Z",
"level": "INFO",
"message": "Tool search_descriptions completed",
"tool_usage": {
"tool_name": "search_descriptions",
"success": true,
"duration_seconds": 0.045,
"result_size": 1247
}
}
```
## 📋 Command Line Options
### Server Mode (Default)
```bash
mcp-code-indexer [OPTIONS]
Options:
--token-limit INT Maximum tokens before recommending search (default: 32000)
--db-path PATH SQLite database path (default: ~/.mcp-code-index/tracker.db)
--cache-dir PATH Cache directory path (default: ~/.mcp-code-index/cache)
--log-level LEVEL Logging level: DEBUG|INFO|WARNING|ERROR|CRITICAL (default: INFO)
```
### Git Hook Mode
```bash
mcp-code-indexer --githook [OPTIONS]
# Automated analysis of git changes using OpenRouter API
# Requires: OPENROUTER_API_KEY environment variable
```
### HTTP Server Mode
```bash
# Start HTTP/REST API server
mcp-code-indexer --http [OPTIONS]
# HTTP server with authentication
mcp-code-indexer --http --auth-token "your-secret-token"
# Custom host and port configuration
mcp-code-indexer --http --host 0.0.0.0 --port 8080
```
### Q&A Commands
```bash
# Simple AI-powered questions (requires OPENROUTER_API_KEY)
mcp-code-indexer --ask "What does this project do?" PROJECT_NAME
# Enhanced analysis with file search
mcp-code-indexer --deepask "How is authentication implemented?" PROJECT_NAME
# JSON output for programmatic use
mcp-code-indexer --ask "Question" PROJECT_NAME --json
```
### Administrative Commands
```bash
# List all projects
mcp-code-indexer --getprojects
# Execute MCP tool directly
mcp-code-indexer --runcommand '{"method": "tools/call", "params": {...}}'
# Export descriptions for a project
mcp-code-indexer --dumpdescriptions PROJECT_ID
# Create local database for a project
mcp-code-indexer --makelocal /path/to/project
# Generate project documentation map
mcp-code-indexer --map PROJECT_NAME
```
## 🛡️ Security Features
- **Input validation** on all MCP tool parameters
- **SQL injection protection** via parameterized queries
- **File system sandboxing** with .gitignore respect
- **Error sanitization** to prevent information leakage
- **Async resource cleanup** to prevent memory leaks
## 🚨 Quick Troubleshooting
**Common issues and instant solutions:**
| Issue | Quick Fix | Learn More |
|-------|-----------|------------|
| **"No module named 'mcp_code_indexer'"** | `pip install -e .` (for development) | [Contributing Guide](docs/contributing.md#development-setup) |
| **"OPENROUTER_API_KEY not found"** | `export OPENROUTER_API_KEY="your-key"` | [Git Hook Setup](docs/git-hook-setup.md#prerequisites) |
| **"Database is locked"** | Enable WAL mode: `--enable-wal-mode` | [CLI Reference](docs/cli-reference.md#database-configuration) |
| **"Large codebase - use search"** | Normal for 200+ files. Use `search_descriptions` | [API Reference](docs/api-reference.md#search_descriptions) |
| **HTTP authentication failed** | Check `--auth-token` configuration | [HTTP API Reference](docs/http-api.md#authentication) |
| **Q&A commands not working** | Set `OPENROUTER_API_KEY` environment variable | [Q&A Interface](docs/qa-interface.md#getting-started) |
| **High memory usage** | Reduce token limit: `--token-limit 10000` | [Configuration Guide](docs/configuration.md#performance-tuning) |
**💡 Not finding your issue?** Check the [complete troubleshooting guides](docs/monitoring.md#troubleshooting-runbook) in our documentation.
## 🚀 Next Steps
Ready to supercharge your AI agents with intelligent codebase navigation?
### 🎯 Choose Your Path
**🆕 New to MCP Code Indexer?**
1. **[Install and run your first server](#-quick-start)** - Get up and running in 2 minutes
2. **[Master the API tools](docs/api-reference.md)** - Learn all 11 tools with examples
3. **[Try HTTP API access](docs/http-api.md)** - REST API for web applications
4. **[Explore AI-powered Q&A](docs/qa-interface.md)** - Ask questions about your code
5. **[Set up git hooks](docs/git-hook-setup.md)** - Automate your workflow
**👥 Setting up for a team?**
1. **[Learn all CLI commands](docs/cli-reference.md)** - Complete command reference
2. **[Configure for production](docs/configuration.md)** - Production deployment guide
3. **[Set up administrative workflows](docs/admin-commands.md)** - Project & database management
4. **[Performance optimization](docs/performance-tuning.md)** - High-concurrency setup
5. **[Monitoring & alerts](docs/monitoring.md)** - Production monitoring
**🔧 Want to contribute?**
1. **[Understand the architecture](docs/architecture.md)** - Technical deep dive
2. **[Development setup](docs/contributing.md)** - Contribution workflow
3. **[Report issues](https://github.com/fluffypony/mcp-code-indexer/issues)** - Share feedback and suggestions
**📚 Learning Resources:**
- **[Examples & integrations](examples/)** - Ready-to-use configurations
- **[Video tutorials](#)** - Coming soon!
- **[Community discussions](https://github.com/fluffypony/mcp-code-indexer/discussions)** - Ask questions and share tips
## 🤝 Contributing
We welcome contributions! See our **[Contributing Guide](docs/contributing.md)** for:
- Development setup
- Code style guidelines
- Testing requirements
- Pull request process
## 📄 License
MIT License - see **[LICENSE](LICENSE)** for details.
## 🙏 Built With
- **[Model Context Protocol](https://github.com/modelcontextprotocol/python-sdk)** - The foundation for tool integration
- **[tiktoken](https://pypi.org/project/tiktoken/)** - Fast BPE tokenization
- **[aiosqlite](https://pypi.org/project/aiosqlite/)** - Async SQLite operations
- **[aiohttp](https://pypi.org/project/aiohttp/)** - Async HTTP client for OpenRouter API
- **[tenacity](https://pypi.org/project/tenacity/)** - Robust retry logic and rate limiting
- **[Pydantic](https://pydantic.dev/)** - Data validation and settings
---
**Transform how your AI agents understand code!** 🚀
🎯 **New User?** [Get started in 2 minutes](#-quick-start)
👨💻 **Developer?** [Explore the complete API](docs/api-reference.md)
🔧 **Production?** [Deploy with confidence](docs/configuration.md)
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-code-indexer",
"maintainer": "MCP Code Indexer Contributors",
"docs_url": null,
"requires_python": "<3.14,>=3.10",
"maintainer_email": null,
"keywords": "mcp, model-context-protocol, code-indexer, ai-tools, codebase-navigation, file-descriptions, llm-tools",
"author": "MCP Code Indexer Contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/9a/4e/be0850a65af06f3fc13e764838647ab28c4c1bcabaad160037f20858cee7/mcp_code_indexer-4.2.15.tar.gz",
"platform": null,
"description": "# MCP Code Indexer \ud83d\ude80\n\n[](https://badge.fury.io/py/mcp-code-indexer)\n[](https://pypi.org/project/mcp-code-indexer/)\n[](https://opensource.org/licenses/MIT)\n\nA production-ready **Model Context Protocol (MCP) server** that revolutionizes how AI agents navigate and understand codebases. Built for high-concurrency environments with advanced database resilience, the server provides instant access to intelligent descriptions, semantic search, and context-aware recommendations while maintaining 800+ writes/sec throughput.\n\n## \ud83c\udfaf What It Does\n\nThe MCP Code Indexer solves a critical problem for AI agents working with large codebases: **understanding code structure without repeatedly scanning files**. Instead of reading every file, agents can:\n\n- **Query file purposes** instantly with natural language descriptions\n- **Search across codebases** using full-text search\n- **Get intelligent recommendations** based on codebase size (overview vs search)\n- **Generate condensed overviews** for project understanding\n\nPerfect for AI-powered code review, refactoring tools, documentation generation, and codebase analysis workflows.\n\n## \u26a1 Quick Start\n\n### \ud83d\udc68\u200d\ud83d\udcbb For Developers\n\nGet started integrating MCP Code Indexer into your AI agent workflow:\n\n```bash\n# Install with Poetry\npoetry add mcp-code-indexer\n\n# Or with pip\npip install mcp-code-indexer\n\n# Start the MCP server\nmcp-code-indexer\n\n# Connect your MCP client and start using tools\n# See API Reference for complete tool documentation\n```\n\n### \ud83c\udf10 For Web Applications\n\nEnable HTTP/REST API access for browser-based applications:\n\n```bash\n# Start HTTP server with authentication\nmcp-code-indexer --http --auth-token \"your-secret-token\"\n\n# Custom host and port\nmcp-code-indexer --http --host 0.0.0.0 --port 8080\n\n# CORS configuration for web apps\nmcp-code-indexer --http --cors-origins \"https://localhost:3000\" \"https://myapp.com\"\n```\n\n**\ud83d\udd17 [Complete HTTP API Reference \u2192](docs/http-api.md)**\n\n### \ud83e\udd16 For AI-Powered Q&A\n\nAsk questions about your codebase using natural language:\n\n```bash\n# Set OpenRouter API key for Claude access\nexport OPENROUTER_API_KEY=\"your-openrouter-api-key\"\n\n# Simple questions about project architecture\nmcp-code-indexer --ask \"What does this project do?\" my-project\n\n# Enhanced analysis with file search\nmcp-code-indexer --deepask \"How is authentication implemented?\" web-app\n\n# JSON output for programmatic use\nmcp-code-indexer --ask \"List the main components\" my-project --json\n```\n\n**\ud83e\udd16 [Complete Q&A Interface Guide \u2192](docs/qa-interface.md)**\n\n### \ud83d\udd27 For System Administrators\n\nDeploy and configure the server for your team:\n\n```bash\n# Production deployment with custom settings\nmcp-code-indexer \\\n --token-limit 64000 \\\n --db-path /data/mcp-index.db \\\n --cache-dir /var/cache/mcp \\\n --log-level INFO\n\n# Check installation\nmcp-code-indexer --version\n```\n\n### \ud83c\udfaf For Everyone\n\n**New to MCP Code Indexer?** Start here:\n\n1. **Install**: `poetry add mcp-code-indexer` (or `pip install mcp-code-indexer`)\n2. **Run**: `mcp-code-indexer --token-limit 32000`\n3. **Connect**: Use your favorite MCP client\n4. **Explore**: Try the `check_codebase_size` tool first\n\n**Development Setup**:\n\n```bash\n# Clone and setup for contributing\ngit clone https://github.com/fluffypony/mcp-code-indexer.git\ncd mcp-code-indexer\n\n# Install with Poetry (recommended)\npoetry install\n\n# Or install in development mode with pip\npip install -e .\n\n# Run the server\nmcp-code-indexer --token-limit 32000\n```\n\n## \ud83d\udd17 Git Hook Integration\n\n\ud83d\ude80 **NEW Feature**: Automated code indexing with AI-powered analysis! Keep your file descriptions synchronized automatically as your codebase evolves.\n\n### \ud83d\udc64 For Users: Quick Setup\n\n```bash\n# Set your OpenRouter API key\nexport OPENROUTER_API_KEY=\"sk-or-v1-your-api-key-here\"\n\n# Test git hook functionality\nmcp-code-indexer --githook\n\n# Install post-commit hook\ncp examples/git-hooks/post-commit .git/hooks/\nchmod +x .git/hooks/post-commit\n```\n\n### \ud83d\udc68\u200d\ud83d\udcbb For Developers: How It Works\n\nThe git hook integration provides intelligent automation:\n\n- **\ud83d\udcca Git Analysis**: Automatically analyzes git diffs after commits/merges\n- **\ud83e\udd16 AI Processing**: Uses OpenRouter API with Anthropic's Claude Sonnet 4\n- **\u26a1 Smart Updates**: Only processes files that actually changed\n- **\ud83d\udd04 Overview Maintenance**: Updates project overview when structure changes\n- **\ud83d\udee1\ufe0f Error Isolation**: Git operations continue even if indexing fails\n- **\u23f1\ufe0f Rate Limiting**: Built-in retry logic with exponential backoff\n\n### \ud83c\udfaf Key Benefits\n\n\ud83d\udca1 **Zero Manual Work**: Descriptions stay current without any effort\n\u26a1 **Performance**: Only analyzes changed files, not entire codebase\n\ud83d\udd12 **Reliability**: Robust error handling ensures git operations never fail\n\ud83c\udf9b\ufe0f **Configurable**: Support for custom models and timeout settings\n\n**Learn More**: See [Git Hook Setup Guide](docs/git-hook-setup.md) for complete configuration options and troubleshooting.\n\n## \ud83e\udde0 Vector Mode (BETA)\n\n\ud83d\ude80 **NEW Feature**: Semantic code search with vector embeddings! Experience AI-powered code discovery that understands context and meaning, not just keywords.\n\n### \ud83c\udfaf What is Vector Mode?\n\nVector Mode transforms how you search and understand codebases by using AI embeddings:\n\n- **\ud83d\udd0d Semantic Search**: Find code by meaning, not just text matching\n- **\u26a1 Real-time Indexing**: Automatic embedding generation as code changes \n- **\ud83d\udee1\ufe0f Secure by Default**: Comprehensive secret redaction before API calls\n- **\ud83c\udf10 Multi-language**: Python, JavaScript, TypeScript with AST-based chunking\n- **\ud83d\udcca Smart Chunking**: Context-aware code segmentation for optimal embeddings\n\n### \ud83d\ude80 Quick Start\n\n```bash\n# Install MCP Code Indexer (includes vector mode)\npip install mcp-code-indexer\n\n# Set required API keys\nexport VOYAGE_API_KEY=\"pa-your-voyage-api-key\"\nexport TURBOPUFFER_API_KEY=\"your-turbopuffer-api-key\"\n\n# Optional: Configure region (default: gcp-europe-west3)\nexport TURBOPUFFER_REGION=\"gcp-europe-west3\" \n\n# Start with vector mode enabled\nmcp-code-indexer --vector\n\n# The daemon automatically starts and begins indexing your projects\n```\n\n### \ud83d\udca1 Key Features\n\n- **\ud83d\udd10 Secret Redaction**: 20+ pattern types automatically detected and redacted\n- **\ud83c\udf33 Merkle Trees**: Efficient change detection without full directory scans\n- **\ud83c\udf9b\ufe0f Circuit Breakers**: Resilient API integration with automatic retry logic\n- **\ud83d\udcc8 Production Ready**: Built for high-concurrency with comprehensive monitoring\n\n### \ud83d\udd27 Advanced Configuration\n\n```bash\n# Custom configuration\nmcp-code-indexer --vector --vector-config /path/to/config.yaml\n\n# HTTP mode with vector search\nmcp-code-indexer --vector --http --port 8080\n```\n\n### \ud83d\udee0\ufe0f Architecture\n\nVector Mode adds powerful new MCP tools:\n- `vector_search` - Semantic code search across projects\n- `similarity_search` - Find similar code patterns \n- `dependency_search` - Discover code relationships\n- `vector_status` - Monitor indexing progress\n\n**Status**: Currently in BETA - foundations implemented, full pipeline in development.\n\n## \ud83d\udd27 Development Setup\n\n### \ud83d\udc68\u200d\ud83d\udcbb For Contributors\n\nContributing to MCP Code Indexer? Follow these steps for a proper development environment:\n\n```bash\n# Setup development environment\ngit clone https://github.com/fluffypony/mcp-code-indexer.git\ncd mcp-code-indexer\n\n# Install with Poetry (recommended)\npoetry install\n\n# Or use pip with virtual environment\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\npip install -e .[dev]\n\n# Verify installation\npython main.py --help\nmcp-code-indexer --version\n```\n\n\u26a0\ufe0f **Important**: The editable install (`pip install -e .`) is **required** for development. The project uses proper PyPI package structure with absolute imports like `from mcp_code_indexer.database.database import DatabaseManager`. Without editable installation, you'll get `ModuleNotFoundError` exceptions.\n\n### \ud83c\udfaf Development Workflow\n\n```bash\n# Activate virtual environment\nsource venv/bin/activate\n\n# Run the server directly\npython main.py --token-limit 32000\n\n# Or use the installed CLI command\nmcp-code-indexer --token-limit 32000\n\n# Run tests\npython -m pytest tests/ -v\n\n# Run with coverage\npython -m pytest tests/ --cov=src --cov-report=html\n\n# Format code\nblack src/ tests/\nisort src/ tests/\n\n# Type checking\nmypy src/\n```\n\n## \ud83d\udee0\ufe0f MCP Tools Available\n\nThe server provides **11 powerful MCP tools** for intelligent codebase management. Whether you're an AI agent or human developer, these tools make navigating code effortless.\n\n### \ud83c\udfaf Essential Tools (Start Here)\n| Tool | Purpose | When to Use |\n|------|---------|-------------|\n| **`check_codebase_size`** | Get navigation recommendations | First tool to call for any project |\n| **`search_descriptions`** | Find files by functionality | When you need specific files |\n| **`get_codebase_overview`** | Project architectural summary | Understanding system design |\n\n### \ud83d\udd27 Core Operations\n| Tool | Purpose | Best For |\n|------|---------|----------|\n| **`get_file_description`** | Retrieve file summaries | Quick file understanding |\n| **`update_file_description`** | Store detailed file analysis | AI agents updating descriptions |\n| **`find_missing_descriptions`** | Scan for undocumented files | Maintenance and coverage |\n\n### \ud83d\udd0d Advanced Features\n| Tool | Purpose | Use Case |\n|------|---------|----------|\n| **`get_all_descriptions`** | Complete project structure | Small-to-medium codebases |\n| **`get_word_frequency`** | Technical vocabulary analysis | Domain understanding |\n| **`update_codebase_overview`** | Create project documentation | Architecture documentation |\n| **`search_codebase_overview`** | Search in project overviews | Finding specific topics |\n\n### \ud83c\udfe5 System Health\n| Tool | Purpose | For |\n|------|---------|-----|\n| **`check_database_health`** | Real-time performance monitoring | Production deployments |\n\n\ud83d\udca1 **Pro Tip**: Always start with `check_codebase_size` to get personalized recommendations for navigating your specific codebase.\n\n**\ud83d\udcd6 Complete API Documentation**: [View all 11 tools with examples \u2192](docs/api-reference.md)\n\n## \ud83d\udd17 Git Hook Integration\n\nKeep your codebase documentation automatically synchronized with automated analysis on every commit:\n\n```bash\n# Analyze current staged changes\nmcp-code-indexer --githook\n\n# Analyze a specific commit\nmcp-code-indexer --githook abc123def\n\n# Analyze using HEAD syntax\nmcp-code-indexer --githook HEAD\nmcp-code-indexer --githook HEAD~1\nmcp-code-indexer --githook HEAD~3\n\n# Analyze a commit range (perfect for rebases)\nmcp-code-indexer --githook abc123 def456\nmcp-code-indexer --githook HEAD~5 HEAD\n```\n\n**\ud83c\udfaf Perfect for**:\n- **Automated documentation** that never goes stale\n- **Rebase-aware analysis** that handles complex git operations\n- **Zero-effort maintenance** with background processing\n\nSee the **[Git Hook Setup Guide](docs/git-hook-setup.md)** for complete installation instructions including post-commit, post-merge, and post-rewrite hooks.\n\n## \ud83c\udfd7\ufe0f Architecture Highlights\n\n### \ud83d\ude80 Performance Optimized\n- **SQLite with WAL mode** for high-concurrency access (800+ writes/sec)\n- **Smart connection pooling** with optimized pool size (3 connections default)\n- **FTS5 full-text search** with prefix indexing for sub-100ms queries\n- **Token-aware caching** to minimize expensive operations\n- **Write operation serialization** to eliminate database lock conflicts\n\n### \ud83d\udee1\ufe0f Production Ready\n- **Database resilience features** with <2% error rate under high load\n- **Exponential backoff retry logic** with intelligent failure recovery\n- **Comprehensive health monitoring** with automatic pool refresh\n- **Structured JSON logging** with performance metrics tracking\n- **Async-first design** with proper resource cleanup\n- **MCP protocol compliant** with clean stdio streams\n- **Upstream inheritance** for fork workflows\n- **Git integration** with .gitignore support\n\n### \ud83d\udc68\u200d\ud83d\udcbb Developer Friendly\n- **95%+ test coverage** with async support and concurrent access tests\n- **Integration tests** for complete workflows including database stress testing\n- **Performance benchmarks** for large codebases with resilience validation\n- **Clear error messages** with MCP protocol compliance\n- **Comprehensive configuration options** for production tuning\n\n## \ud83d\udcd6 Documentation\n\nComprehensive documentation organized by user journey and expertise level.\n\n### \ud83d\ude80 Getting Started (New Users)\n| Guide | Purpose | Time Investment |\n|-------|---------|-----------------|\n| **[Quick Start](#-quick-start)** | Install and run your first server | 2 minutes |\n| **[API Reference](docs/api-reference.md)** | Master all 11 MCP tools | 15 minutes |\n| **[HTTP API Reference](docs/http-api.md)** | REST API for web applications | 10 minutes |\n| **[Q&A Interface](docs/qa-interface.md)** | AI-powered codebase analysis | 8 minutes |\n| **[Git Hook Setup](docs/git-hook-setup.md)** | Automate your workflow | 5 minutes |\n\n### \ud83c\udfd7\ufe0f Production Deployment (Teams & Admins)\n| Guide | Focus | Best For |\n|-------|-------|----------|\n| **[CLI Reference](docs/cli-reference.md)** | Complete command documentation | All users |\n| **[Administrative Commands](docs/admin-commands.md)** | Project & database management | System administrators |\n| **[Configuration Guide](docs/configuration.md)** | Production setup & tuning | System administrators |\n| **[Performance Tuning](docs/performance-tuning.md)** | High-concurrency optimization | DevOps teams |\n| **[Monitoring & Diagnostics](docs/monitoring.md)** | Production monitoring | Operations teams |\n\n### \ud83d\udd27 Advanced Topics (Power Users)\n| Guide | Depth | For |\n|-------|-------|-----|\n| **[Architecture Overview](docs/architecture.md)** | System design deep dive | Developers & architects |\n| **[Database Resilience](docs/database-resilience.md)** | Advanced error handling | Senior developers |\n| **[Contributing Guide](docs/contributing.md)** | Development workflow | Contributors |\n\n### \ud83d\udccb Quick References\n- **[Examples & Integrations](examples/)** - Ready-to-use configurations\n- **[Troubleshooting](#\ud83d\udea8-troubleshooting)** - Common issues & solutions\n- **[API Tools Summary](#\ud83d\udee0\ufe0f-mcp-tools-available)** - All 11 tools at a glance\n\n**\ud83d\udcda Reading Paths:**\n- **New to MCP Code Indexer?** Quick Start \u2192 API Reference \u2192 HTTP API \u2192 Q&A Interface\n- **Web developers?** Quick Start \u2192 HTTP API Reference \u2192 Q&A Interface \u2192 Git Hooks\n- **AI/ML engineers?** Quick Start \u2192 Q&A Interface \u2192 API Reference \u2192 Git Hooks\n- **Setting up for a team?** CLI Reference \u2192 Configuration \u2192 Administrative Commands \u2192 Monitoring\n- **Contributing to the project?** Architecture \u2192 Contributing \u2192 API Reference\n\n## \ud83d\udea6 System Requirements\n\n- **Python 3.8+** with asyncio support\n- **SQLite 3.35+** (included with Python)\n- **4GB+ RAM** for large codebases (1000+ files)\n- **SSD storage** recommended for optimal performance\n\n## \ud83d\udcca Performance\n\nTested with codebases up to **10,000 files**:\n- File description retrieval: **< 10ms**\n- Full-text search: **< 100ms**\n- Codebase overview generation: **< 2s**\n- Merge conflict detection: **< 5s**\n\n## \ud83d\udd27 Advanced Configuration\n\n### \ud83d\udc68\u200d\ud83d\udcbb For Developers: Basic Configuration\n\n```bash\n# Production setup with custom limits\nmcp-code-indexer \\\n --token-limit 50000 \\\n --db-path /data/mcp-index.db \\\n --cache-dir /tmp/mcp-cache \\\n --log-level INFO\n\n# Enable structured logging\nexport MCP_LOG_FORMAT=json\nmcp-code-indexer\n```\n\n### \ud83d\udd27 For System Administrators: Database Resilience Tuning\n\nConfigure advanced database resilience features for high-concurrency environments:\n\n```bash\n# High-performance production deployment\nmcp-code-indexer \\\n --token-limit 64000 \\\n --db-path /data/mcp-index.db \\\n --cache-dir /var/cache/mcp \\\n --log-level INFO \\\n --db-pool-size 5 \\\n --db-retry-count 7 \\\n --db-timeout 15.0 \\\n --enable-wal-mode \\\n --health-check-interval 20.0\n\n# Environment variable configuration\nexport DB_POOL_SIZE=5\nexport DB_RETRY_COUNT=7\nexport DB_TIMEOUT=15.0\nexport DB_WAL_MODE=true\nexport DB_HEALTH_CHECK_INTERVAL=20.0\nmcp-code-indexer --token-limit 64000\n```\n\n#### Configuration Options\n\n| Parameter | Default | Description | Use Case |\n|-----------|---------|-------------|----------|\n| `--db-pool-size` | 3 | Database connection pool size | Higher for more concurrent clients |\n| `--db-retry-count` | 5 | Max retry attempts for failed operations | Increase for unstable environments |\n| `--db-timeout` | 10.0 | Transaction timeout (seconds) | Increase for large operations |\n| `--enable-wal-mode` | true | Enable WAL mode for concurrency | Always enable for production |\n| `--health-check-interval` | 30.0 | Health monitoring interval (seconds) | Lower for faster issue detection |\n\n\ud83d\udca1 **Performance Tip**: For environments with 10+ concurrent clients, use `--db-pool-size 5` and `--health-check-interval 15.0` for optimal throughput.\n\n## \ud83e\udd1d Integration Examples\n\n### With AI Agents\n```python\n# Example: AI agent using MCP tools\nasync def analyze_codebase(project_path):\n # Check if codebase is large\n size_info = await mcp_client.call_tool(\"check_codebase_size\", {\n \"projectName\": \"my-project\",\n \"folderPath\": project_path\n })\n\n if size_info[\"isLarge\"]:\n # Use search for large codebases\n results = await mcp_client.call_tool(\"search_descriptions\", {\n \"projectName\": \"my-project\",\n \"folderPath\": project_path,\n \"query\": \"authentication logic\"\n })\n else:\n # Get full overview for smaller projects\n overview = await mcp_client.call_tool(\"get_codebase_overview\", {\n \"projectName\": \"my-project\",\n \"folderPath\": project_path\n })\n```\n\n### With CI/CD Pipelines\n```yaml\n# Example: GitHub Actions integration\n- name: Update Code Descriptions\n run: |\n python -c \"\n import asyncio\n from mcp_client import MCPClient\n\n async def update_descriptions():\n client = MCPClient('mcp-code-indexer')\n\n # Find files without descriptions\n missing = await client.call_tool('find_missing_descriptions', {\n 'projectName': '${{ github.repository }}',\n 'folderPath': '.'\n })\n\n # Process with AI and update...\n\n asyncio.run(update_descriptions())\n \"\n```\n\n## \ud83e\uddea Testing\n\n```bash\n# Install with test dependencies using Poetry\npoetry install --with test\n\n# Or with pip\npip install mcp-code-indexer[test]\n\n# Run full test suite\npython -m pytest tests/ -v\n\n# Run with coverage\npython -m pytest tests/ --cov=src --cov-report=html\n\n# Run performance tests\npython -m pytest tests/ -m performance\n\n# Run integration tests only\npython -m pytest tests/integration/ -v\n```\n\n## \ud83d\udcc8 Monitoring\n\nThe server provides structured JSON logs for monitoring:\n\n```json\n{\n \"timestamp\": \"2024-01-15T10:30:00Z\",\n \"level\": \"INFO\",\n \"message\": \"Tool search_descriptions completed\",\n \"tool_usage\": {\n \"tool_name\": \"search_descriptions\",\n \"success\": true,\n \"duration_seconds\": 0.045,\n \"result_size\": 1247\n }\n}\n```\n\n## \ud83d\udccb Command Line Options\n\n### Server Mode (Default)\n```bash\nmcp-code-indexer [OPTIONS]\n\nOptions:\n --token-limit INT Maximum tokens before recommending search (default: 32000)\n --db-path PATH SQLite database path (default: ~/.mcp-code-index/tracker.db)\n --cache-dir PATH Cache directory path (default: ~/.mcp-code-index/cache)\n --log-level LEVEL Logging level: DEBUG|INFO|WARNING|ERROR|CRITICAL (default: INFO)\n```\n\n### Git Hook Mode\n```bash\nmcp-code-indexer --githook [OPTIONS]\n\n# Automated analysis of git changes using OpenRouter API\n# Requires: OPENROUTER_API_KEY environment variable\n```\n\n### HTTP Server Mode\n```bash\n# Start HTTP/REST API server\nmcp-code-indexer --http [OPTIONS]\n\n# HTTP server with authentication\nmcp-code-indexer --http --auth-token \"your-secret-token\"\n\n# Custom host and port configuration\nmcp-code-indexer --http --host 0.0.0.0 --port 8080\n```\n\n### Q&A Commands\n```bash\n# Simple AI-powered questions (requires OPENROUTER_API_KEY)\nmcp-code-indexer --ask \"What does this project do?\" PROJECT_NAME\n\n# Enhanced analysis with file search\nmcp-code-indexer --deepask \"How is authentication implemented?\" PROJECT_NAME\n\n# JSON output for programmatic use\nmcp-code-indexer --ask \"Question\" PROJECT_NAME --json\n```\n\n### Administrative Commands\n```bash\n# List all projects\nmcp-code-indexer --getprojects\n\n# Execute MCP tool directly\nmcp-code-indexer --runcommand '{\"method\": \"tools/call\", \"params\": {...}}'\n\n# Export descriptions for a project\nmcp-code-indexer --dumpdescriptions PROJECT_ID\n\n# Create local database for a project\nmcp-code-indexer --makelocal /path/to/project\n\n# Generate project documentation map\nmcp-code-indexer --map PROJECT_NAME\n```\n\n## \ud83d\udee1\ufe0f Security Features\n\n- **Input validation** on all MCP tool parameters\n- **SQL injection protection** via parameterized queries\n- **File system sandboxing** with .gitignore respect\n- **Error sanitization** to prevent information leakage\n- **Async resource cleanup** to prevent memory leaks\n\n## \ud83d\udea8 Quick Troubleshooting\n\n**Common issues and instant solutions:**\n\n| Issue | Quick Fix | Learn More |\n|-------|-----------|------------|\n| **\"No module named 'mcp_code_indexer'\"** | `pip install -e .` (for development) | [Contributing Guide](docs/contributing.md#development-setup) |\n| **\"OPENROUTER_API_KEY not found\"** | `export OPENROUTER_API_KEY=\"your-key\"` | [Git Hook Setup](docs/git-hook-setup.md#prerequisites) |\n| **\"Database is locked\"** | Enable WAL mode: `--enable-wal-mode` | [CLI Reference](docs/cli-reference.md#database-configuration) |\n| **\"Large codebase - use search\"** | Normal for 200+ files. Use `search_descriptions` | [API Reference](docs/api-reference.md#search_descriptions) |\n| **HTTP authentication failed** | Check `--auth-token` configuration | [HTTP API Reference](docs/http-api.md#authentication) |\n| **Q&A commands not working** | Set `OPENROUTER_API_KEY` environment variable | [Q&A Interface](docs/qa-interface.md#getting-started) |\n| **High memory usage** | Reduce token limit: `--token-limit 10000` | [Configuration Guide](docs/configuration.md#performance-tuning) |\n\n**\ud83d\udca1 Not finding your issue?** Check the [complete troubleshooting guides](docs/monitoring.md#troubleshooting-runbook) in our documentation.\n\n## \ud83d\ude80 Next Steps\n\nReady to supercharge your AI agents with intelligent codebase navigation?\n\n### \ud83c\udfaf Choose Your Path\n\n**\ud83c\udd95 New to MCP Code Indexer?**\n1. **[Install and run your first server](#-quick-start)** - Get up and running in 2 minutes\n2. **[Master the API tools](docs/api-reference.md)** - Learn all 11 tools with examples\n3. **[Try HTTP API access](docs/http-api.md)** - REST API for web applications\n4. **[Explore AI-powered Q&A](docs/qa-interface.md)** - Ask questions about your code\n5. **[Set up git hooks](docs/git-hook-setup.md)** - Automate your workflow\n\n**\ud83d\udc65 Setting up for a team?**\n1. **[Learn all CLI commands](docs/cli-reference.md)** - Complete command reference\n2. **[Configure for production](docs/configuration.md)** - Production deployment guide\n3. **[Set up administrative workflows](docs/admin-commands.md)** - Project & database management\n4. **[Performance optimization](docs/performance-tuning.md)** - High-concurrency setup\n5. **[Monitoring & alerts](docs/monitoring.md)** - Production monitoring\n\n**\ud83d\udd27 Want to contribute?**\n1. **[Understand the architecture](docs/architecture.md)** - Technical deep dive\n2. **[Development setup](docs/contributing.md)** - Contribution workflow\n3. **[Report issues](https://github.com/fluffypony/mcp-code-indexer/issues)** - Share feedback and suggestions\n\n**\ud83d\udcda Learning Resources:**\n- **[Examples & integrations](examples/)** - Ready-to-use configurations\n- **[Video tutorials](#)** - Coming soon!\n- **[Community discussions](https://github.com/fluffypony/mcp-code-indexer/discussions)** - Ask questions and share tips\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! See our **[Contributing Guide](docs/contributing.md)** for:\n- Development setup\n- Code style guidelines\n- Testing requirements\n- Pull request process\n\n## \ud83d\udcc4 License\n\nMIT License - see **[LICENSE](LICENSE)** for details.\n\n## \ud83d\ude4f Built With\n\n- **[Model Context Protocol](https://github.com/modelcontextprotocol/python-sdk)** - The foundation for tool integration\n- **[tiktoken](https://pypi.org/project/tiktoken/)** - Fast BPE tokenization\n- **[aiosqlite](https://pypi.org/project/aiosqlite/)** - Async SQLite operations\n- **[aiohttp](https://pypi.org/project/aiohttp/)** - Async HTTP client for OpenRouter API\n- **[tenacity](https://pypi.org/project/tenacity/)** - Robust retry logic and rate limiting\n- **[Pydantic](https://pydantic.dev/)** - Data validation and settings\n\n---\n\n**Transform how your AI agents understand code!** \ud83d\ude80\n\n\ud83c\udfaf **New User?** [Get started in 2 minutes](#-quick-start)\n\ud83d\udc68\u200d\ud83d\udcbb **Developer?** [Explore the complete API](docs/api-reference.md)\n\ud83d\udd27 **Production?** [Deploy with confidence](docs/configuration.md)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server that tracks file descriptions across codebases, enabling AI agents to efficiently navigate and understand code through searchable summaries and token-aware overviews.",
"version": "4.2.15",
"project_urls": {
"Documentation": "https://github.com/fluffypony/mcp-code-indexer/blob/main/README.md",
"Homepage": "https://github.com/fluffypony/mcp-code-indexer",
"Repository": "https://github.com/fluffypony/mcp-code-indexer"
},
"split_keywords": [
"mcp",
" model-context-protocol",
" code-indexer",
" ai-tools",
" codebase-navigation",
" file-descriptions",
" llm-tools"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "62d90f7490a308a36468d4727e7541a1641dd97df8921139795711b11a58e54f",
"md5": "e2eead972b551cb66b0daa2fd8955d5d",
"sha256": "6a795da0f4b8645ff5a476940aadc0c17aebcc5b673482b37e658167cde92114"
},
"downloads": -1,
"filename": "mcp_code_indexer-4.2.15-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e2eead972b551cb66b0daa2fd8955d5d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.10",
"size": 951913,
"upload_time": "2025-08-11T12:29:57",
"upload_time_iso_8601": "2025-08-11T12:29:57.317251Z",
"url": "https://files.pythonhosted.org/packages/62/d9/0f7490a308a36468d4727e7541a1641dd97df8921139795711b11a58e54f/mcp_code_indexer-4.2.15-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9a4ebe0850a65af06f3fc13e764838647ab28c4c1bcabaad160037f20858cee7",
"md5": "493de6c75dd894463f067fff6dd72dd9",
"sha256": "903125e041afae930a769cb516c5603604d4e4f6c48f019b8fd804b8fd4cce57"
},
"downloads": -1,
"filename": "mcp_code_indexer-4.2.15.tar.gz",
"has_sig": false,
"md5_digest": "493de6c75dd894463f067fff6dd72dd9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.10",
"size": 928907,
"upload_time": "2025-08-11T12:30:01",
"upload_time_iso_8601": "2025-08-11T12:30:01.084015Z",
"url": "https://files.pythonhosted.org/packages/9a/4e/be0850a65af06f3fc13e764838647ab28c4c1bcabaad160037f20858cee7/mcp_code_indexer-4.2.15.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-11 12:30:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fluffypony",
"github_project": "mcp-code-indexer",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mcp-code-indexer"
}
JSON
