fast-codeindex-mcp

---

English

Overview

fast-codeindex-mcp is a high-performance code indexing and semantic search tool that integrates seamlessly with Claude AI through the Model Context Protocol (MCP). It enables rapid indexing of large codebases and provides intelligent code search capabilities.

Key Features

🚀 Ultra-Fast Indexing

• Multi-threaded parallel processing for efficient index building
• Optimized for large projects with thousands of files
• Incremental indexing support

🔍 Semantic Code Search

• Advanced full-text search with relevance scoring
• Function definition search
• Language-specific filtering
• Multi-language support (13+ programming languages)

🌐 Modern Web UI Dashboard

• Intuitive web interface for code search and indexing
• Real-time search results and statistics
• Dynamic storage configuration on-the-fly
• System health monitoring and diagnostics
• Parameter management interface

🗄️ Pluggable Storage Architecture

• SQLite: Reliable persistent storage (default, no external dependencies)
• Redis: Ultra-fast in-memory caching (optional)
• Hybrid: Best of both worlds (recommended for production)
• Runtime storage mode switching without restart

🧠 Claude AI Integration

• Native MCP stdio server implementation (NEW! 🆕)
• Seamless Claude Desktop integration via MCP protocol
• Support for direct execution, Docker, and docker-compose
• Standard API interface for easy extension

⚡ High Performance

• Sub-10ms search response time
• Efficient SQLite-based storage
• Memory-optimized architecture

📦 Docker Ready

• Pre-built Docker images
• Docker Compose support with multiple storage modes
• One-command deployment
• Health checks and monitoring
• Persistent volume support

🔌 REST API

• Comprehensive REST API endpoints
• JSON request/response format
• Support for all storage backends
• Perfect for automation and integration

🔧 Developer-Friendly

• Complete API documentation
• Practical code examples
• VSCode debugging configuration
• Comprehensive test suite

Supported Languages

Python, JavaScript, TypeScript, Go, Java, C++, C, Rust, Ruby,
PHP, Swift, Kotlin, Scala, Bash, YAML, JSON, XML, HTML, CSS,
SQL, Markdown, and more...

Quick Start

Installation

# Clone the repository
git clone https://github.com/yourusername/fast-codeindex-mcp.git
cd fast-codeindex-mcp

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate  # Windows

# Install dependencies
pip install -e .

Basic Usage - CLI

# Index a project
fast-codeindex index /path/to/your/project

# Full-text search
fast-codeindex search "function_name"

# Search function definitions
fast-codeindex search-func "my_function"

# Search by programming language
fast-codeindex search-lang python "query"

# Display statistics
fast-codeindex stats

Basic Usage - MCP Stdio Server (NEW! 🆕)

# Start the MCP stdio server (recommended for Claude Desktop)
python -m fast_codeindex.mcp_stdio_server

# With environment variables for custom storage
STORAGE_TYPE=hybrid python -m fast_codeindex.mcp_stdio_server

Then configure Claude Desktop (~/.claude.json):

{
  "mcpServers": {
    "fast-codeindex-mcp": {
      "command": "python",
      "args": ["-m", "fast_codeindex.mcp_stdio_server"],
      "type": "stdio",
      "env": {
        "STORAGE_TYPE": "sqlite",
        "SQLITE_PATH": "./code_index.db"
      }
    }
  }
}

For more details, see MCP_SETUP.md and QUICK_REFERENCE.md.

Basic Usage - Web UI

# Start the Web UI server (SQLite mode)
fast-codeindex web

# Or with specific storage backend
fast-codeindex web --storage hybrid --redis-host localhost

# Then open your browser to http://localhost:8000

The Web UI provides:

• 🔍 Full-text search with real-time results
• 📊 Index statistics and health monitoring
• ⚙️ Dynamic storage configuration
• 🎯 Function and language-specific search filters

Python API

from fast_codeindex import FastCodeIndexMCP

# Initialize MCP server
mcp = FastCodeIndexMCP("code_index.db")

# Index a project
result = mcp.index_project("/path/to/project")
print(f"Indexed {result['indexed_files']} files")

# Perform searches
results = mcp.search("def my_function")
for result in results:
    print(f"{result['file']}:{result['line']} - {result['content']}")

# Language-specific search
python_results = mcp.search_by_language("python", "class MyClass")

# Get statistics
stats = mcp.get_stats()
print(f"Total files: {stats['total_files']}")
print(f"Total lines: {stats['total_lines']}")

Docker Deployment

MCP Stdio Server with Docker (NEW! 🆕)

For Claude Desktop integration via MCP protocol:

# 1. Build the image
docker build -t fast-codeindex-mcp:latest .

# 2. Run MCP server (SQLite mode)
docker run -i --rm \
  -v codeindex-data:/data \
  -e STORAGE_TYPE=sqlite \
  -e SQLITE_PATH=/data/code_index.db \
  fast-codeindex-mcp:latest \
  python -m fast_codeindex.mcp_stdio_server

# 3. Or use docker-compose (recommended)
docker-compose -f docker-compose.mcp.yml up -d

Then configure Claude Desktop (see DOCKER_MCP.md for details).

Quick Start with Docker Compose (Web UI)

# 1. Start with SQLite (simplest, no external dependencies)
docker-compose up -d

# 2. Open Web UI
open http://localhost:8000

# 3. View logs
docker-compose logs -f codeindex

Using Different Storage Modes

# SQLite mode (default, local storage only)
docker-compose up -d

# Hybrid mode (Redis + SQLite, recommended for production)
docker-compose --profile hybrid up -d

# Redis mode (in-memory caching only)
docker-compose --profile redis up -d

Using Docker Directly

# Build image
docker build -t fast-codeindex:latest .

# SQLite mode
docker run -d \
  --name codeindex \
  -p 8000:8000 \
  -e STORAGE_TYPE=sqlite \
  fast-codeindex:latest

# Hybrid mode (requires Redis running)
docker run -d \
  --name codeindex \
  -p 8000:8000 \
  -e STORAGE_TYPE=hybrid \
  -e REDIS_HOST=redis \
  --link redis:redis \
  fast-codeindex:latest

Using Pre-built Docker Hub Image

The official image is available on Docker Hub:

# Pull the latest image
docker pull wmeng8503/fast-codeindex-mcp:latest

# Run with SQLite (simplest)
docker run -d -p 8000:8000 \
  -e STORAGE_TYPE=sqlite \
  wmeng8503/fast-codeindex-mcp:latest

# Run with Hybrid mode (recommended)
docker run -d -p 8000:8000 \
  -e STORAGE_TYPE=hybrid \
  -e REDIS_HOST=redis \
  --link redis:redis \
  wmeng8503/fast-codeindex-mcp:latest

# Open web UI
open http://localhost:8000

Image: wmeng8503/fast-codeindex-mcp

Publishing Your Own Docker Hub Image

# 1. Login to Docker Hub
docker login

# 2. Run the automated publish script
./scripts/docker-publish.sh \
  --username your_dockerhub_username \
  --version 1.0.0 \
  --push

# 3. Others can now use:
docker pull your_username/fast-codeindex-mcp:latest

For detailed Docker instructions, see DOCKER_README.md and DOCKER_MCP.md

Storage Architecture

The pluggable storage system allows you to choose the best backend for your use case:

| Feature | SQLite | Redis | Hybrid | |---------|--------|-------|--------| | Speed | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | | Persistence | ✅ Built-in | ❌ In-memory | ✅ L2 Fallback | | Setup | Zero-config | Needs Server | Moderate | | Memory | Disk-based | RAM-based | Balanced | | Use Case | Development, Local | High-speed Cache | Production | | Cost | Free | Free | Free |

Choosing Storage Mode

# SQLite (Default - no external dependencies)
export STORAGE_TYPE=sqlite
export SQLITE_PATH=/data/code_index.db

# Redis (requires Redis server running)
export STORAGE_TYPE=redis
export REDIS_HOST=localhost
export REDIS_PORT=6379

# Hybrid (recommended for production)
export STORAGE_TYPE=hybrid
export REDIS_HOST=localhost
export SQLITE_PATH=/data/code_index.db

Hybrid Mode Architecture

┌─────────────────────────┐
│   Fast-CodeIndex MCP    │
└────────────┬────────────┘
             │
      ┌──────┴──────┐
      ▼             ▼
   L1 Cache       L2 Storage
   (Redis)        (SQLite)
 ─────────────  ─────────────
• Ultra-fast    • Persistent
• In-memory     • Fallback
• Auto-expire   • Full Data

Project Structure

fast-codeindex-mcp/
├── src/fast_codeindex/
│   ├── __init__.py          # Package initialization
│   ├── cli.py               # Command-line interface
│   ├── indexer.py           # Code indexing engine
│   ├── mcp_server.py        # MCP server implementation
│   ├── search_engine.py     # Search engine core
│   └── utils.py             # Utility functions
├── tests/                   # Test suite
├── docs/
│   ├── API.md               # Complete API documentation
│   ├── DEVELOPMENT.md       # Development guide
│   └── DEPLOYMENT.md        # Deployment guide
├── examples/                # Usage examples
├── .github/workflows/       # CI/CD configuration
├── Dockerfile               # Docker configuration
├── docker-compose.yml       # Docker Compose configuration
└── README.md               # This file

API Highlights

CodeIndexer

indexer = CodeIndexer("code_index.db")

# Index directory
result = indexer.index_directory("/path/to/project", recursive=True)

# Get statistics
stats = indexer.get_stats()

CodeSearchEngine

engine = CodeSearchEngine("code_index.db")

# Full-text search
results = engine.search_text("query", limit=50)

# Function search
functions = engine.search_function("func_name", limit=50)

# Language-specific search
python_code = engine.search_by_language("python", "import", limit=50)

# Export results
json_output = engine.export_results(results, format="json")

FastCodeIndexMCP

mcp = FastCodeIndexMCP("code_index.db")

# Index project
mcp.index_project("/path/to/project")

# Various search methods
mcp.search("query")
mcp.search_function("func_name")
mcp.search_by_language("python")

# Statistics and management
mcp.get_stats()
mcp.clear_index()

Documentation

• 📖 Quick Start Guide
• 📚 API Documentation
• 🔧 Development Guide
• 🚀 Deployment Guide
• 🤝 Contributing Guide

Development

Setup

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Code quality checks
black src tests
flake8 src tests
mypy src

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=src/fast_codeindex

# Run specific test
pytest tests/test_search.py::TestCodeSearchEngine

Performance

• Indexing: Processes 1000+ files efficiently
• Search: Sub-10ms response time for average queries
• Memory: Optimized for large codebases (tested with 100K+ lines)

Configuration

Environment Variables

Create .env file in project root:

DATABASE_PATH=./code_index.db
HOST=localhost
PORT=8000
LOG_LEVEL=INFO
MAX_RESULTS=100
MIN_MATCH_SCORE=0.5

MCP Server Configuration

The fast-codeindex-mcp can be used as an MCP server with Claude and other AI tools. To integrate it:

1. Install as MCP Server

pip install -e .

2. Configure Claude Desktop

Edit ~/.claude.json file and add the following configuration:

Stdio Protocol (Recommended - NEW! 🆕):

{
  "mcpServers": {
    "fast-codeindex-mcp": {
      "command": "python",
      "args": ["-m", "fast_codeindex.mcp_stdio_server"],
      "type": "stdio",
      "env": {
        "STORAGE_TYPE": "sqlite",
        "SQLITE_PATH": "./code_index.db"
      }
    }
  }
}

With Environment Variables for Dynamic Configuration:

{
  "mcpServers": {
    "fast-codeindex-mcp": {
      "command": "python",
      "args": ["-m", "fast_codeindex.mcp_stdio_server"],
      "type": "stdio",
      "env": {
        "STORAGE_TYPE": "sqlite",
        "SQLITE_PATH": "./code_index.db"
      }
    }
  }
}

Note: The MCP server supports stdio protocol for seamless integration with Claude. No need to run ccswitch or manage HTTP ports.

3. Storage Backend Configuration

Configure which storage backend to use by setting environment variables in your MCP configuration:

SQLite (Default - Recommended for most users)

{
  "mcpServers": {
    "fast-codeindex-mcp": {
      "command": "python",
      "args": ["-m", "fast_codeindex.mcp_stdio_server"],
      "type": "stdio",
      "env": {
        "STORAGE_TYPE": "sqlite",
        "SQLITE_PATH": "./code_index.db"
      }
    }
  }
}

Redis (For in-memory caching)

{
  "mcpServers": {
    "fast-codeindex-mcp": {
      "command": "python",
      "args": ["-m", "fast_codeindex.mcp_stdio_server"],
      "type": "stdio",
      "env": {
        "STORAGE_TYPE": "redis",
        "REDIS_HOST": "localhost",
        "REDIS_PORT": "6379",
        "REDIS_TTL": "3600"
      }
    }
  }
}

Hybrid Mode (Recommended for production)

{
  "mcpServers": {
    "fast-codeindex-mcp": {
      "command": "python",
      "args": ["-m", "fast_codeindex.mcp_stdio_server"],
      "type": "stdio",
      "env": {
        "STORAGE_TYPE": "hybrid",
        "REDIS_HOST": "localhost",
        "REDIS_PORT": "6379",
        "SQLITE_PATH": "./code_index.db"
      }
    }
  }
}

4. MCP Server Usage with Claude

Once configured, you can use fast-codeindex-mcp directly in Claude:

# The MCP server provides these tools:
# - index_project(path): Index a project directory
# - search(query): Full-text search in indexed code
# - search_function(name): Search for function definitions
# - search_by_language(language, query): Language-specific search
# - get_stats(): Get indexing statistics
# - clear_index(): Clear all indexed data

5. Docker MCP Server

If running the server in Docker, use Docker volumes for better data persistence:

# First, create a Docker volume for the database
docker volume create codeindex-storage

Then configure Claude Desktop:

Hybrid Mode (Recommended):

{
  "mcpServers": {
    "fast-codeindex-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "codeindex-storage:/data",
        "-e", "STORAGE_TYPE=hybrid",
        "-e", "REDIS_HOST=host.docker.internal",
        "-e", "SQLITE_PATH=/data/code_index.db",
        "your-username/fast-codeindex-mcp:latest",
        "python", "-m", "fast_codeindex.mcp_stdio_server"
      ],
      "type": "stdio"
    }
  }
}

SQLite Only (Simpler):

{
  "mcpServers": {
    "fast-codeindex-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "codeindex-storage:/data",
        "-e", "STORAGE_TYPE=sqlite",
        "-e", "SQLITE_PATH=/data/code_index.db",
        "your-username/fast-codeindex-mcp:latest",
        "python", "-m", "fast_codeindex.mcp_stdio_server"
      ],
      "type": "stdio"
    }
  }
}

6. Troubleshooting MCP Configuration

Issue: MCP server not found

• Ensure fast-codeindex-mcp is installed: pip install -e .
• Check the path is correct in your configuration

Issue: Connection timeout

• Verify the Python environment is accessible from Claude
• Check that required dependencies are installed

Issue: Storage backend not accessible

• For Redis: Ensure Redis service is running and accessible
• For SQLite: Verify file permissions for the database path
• Check environment variables are set correctly

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details on:

• How to report bugs
• How to suggest features
• Development workflow
• Code style guidelines
• Testing requirements

License

This project is licensed under the MIT License - see LICENSE file for details.

Citation

If you use this project in your research or work, please cite:

@software{fast_codeindex_mcp,
  title={fast-codeindex-mcp},
  author={Your Name},
  year={2024},
  url={https://github.com/yourusername/fast-codeindex-mcp}
}

Troubleshooting

Q: Search returns no results

• A: Make sure you've indexed your project with fast-codeindex index /path/to/project

Q: Slow indexing

• A: Limit the directory size or use --limit parameter for searches

Q: Database corruption

• A: Delete code_index.db and re-index the project

FAQ

Q: What's the maximum project size?

• A: Tested with projects containing 100K+ lines of code

Q: Can I use it with multiple projects?

• A: Yes, create separate databases for different projects

Q: Is the index persistent?

• A: Yes, the SQLite database persists across sessions

Roadmap

• [x] Web UI interface (✅ Completed!)
• [x] Pluggable storage (✅ SQLite, Redis, Hybrid)
• [x] Docker deployment (✅ Docker & Docker Compose ready)
• [ ] Advanced semantic search
• [ ] Distributed indexing
• [ ] Cloud storage integration
• [ ] IDE plugin support

Support

• 📧 Email: contact@example.com
• 🐛 Issue Tracker: GitHub Issues
• 💬 Discussions: GitHub Discussions

---

中文

项目简介

fast-codeindex-mcp 是一个高性能的代码索引和语义搜索工具，通过 Model Context Protocol (MCP) 与 Claude AI 无缝集成。它能够快速索引大型代码库，并提供智能的代码搜索功能。

核心特性

🚀 极速索引

• 采用多线程并行处理，高效构建索引
• 针对包含数千个文件的大型项目优化
• 支持增量索引

🔍 语义代码搜索

• 高级全文搜索，支持相关性评分
• 函数定义搜索
• 基于编程语言的搜索过滤
• 支持 13+ 种编程语言

🌐 现代 Web UI 仪表板

• 直观的 Web 界面用于代码搜索和索引
• 实时搜索结果和统计信息
• 动态存储配置，无需重启
• 系统健康监控和诊断
• 参数管理界面

🗄️ 可插拔存储架构

• SQLite: 可靠的持久存储（默认，无外部依赖）
• Redis: 超快速内存缓存（可选）
• Hybrid: 双存储混合模式（生产环境推荐）
• 运行时无需重启即可切换存储模式

🧠 Claude AI 集成

• 原生 MCP 服务器实现
• 与 Claude 无缝集成
• 标准 API 接口便于扩展

⚡ 高性能

• 搜索响应时间 <10ms
• 基于 SQLite 的高效存储
• 内存优化架构

📦 Docker 就绪

• 预构建的 Docker 镜像
• Docker Compose 支持多存储模式
• 一条命令部署
• 健康检查和监控
• 数据卷持久化支持

🔌 REST API

• 完整的 REST API 端点
• JSON 请求/响应格式
• 支持所有存储后端
• 完美适合自动化和集成

🔧 开发者友好

• 完整的 API 文档
• 实用的代码示例
• VSCode 调试配置
• 完善的测试套件

支持的编程语言

Python、JavaScript、TypeScript、Go、Java、C++、C、Rust、Ruby、
PHP、Swift、Kotlin、Scala、Bash、YAML、JSON、XML、HTML、CSS、
SQL、Markdown 等多种编程语言...

快速开始

安装

# 克隆仓库
git clone https://github.com/yourusername/fast-codeindex-mcp.git
cd fast-codeindex-mcp

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# 或
venv\Scripts\activate  # Windows

# 安装依赖
pip install -e .

基本用法 - 命令行

# 索引项目
fast-codeindex index /path/to/your/project

# 全文搜索
fast-codeindex search "函数名称"

# 搜索函数定义
fast-codeindex search-func "my_function"

# 按编程语言搜索
fast-codeindex search-lang python "查询"

# 显示统计信息
fast-codeindex stats

基本用法 - Web UI

# 启动 Web UI 服务器（SQLite 模式）
fast-codeindex web

# 或指定特定的存储后端
fast-codeindex web --storage hybrid --redis-host localhost

# 然后打开浏览器访问 http://localhost:8000

Web UI 提供：

• 🔍 全文搜索与实时结果
• 📊 索引统计和健康监控
• ⚙️ 动态存储配置
• 🎯 函数和语言特定搜索过滤

Python API

from fast_codeindex import FastCodeIndexMCP

# 初始化 MCP 服务器
mcp = FastCodeIndexMCP("code_index.db")

# 索引项目
result = mcp.index_project("/path/to/project")
print(f"已索引 {result['indexed_files']} 个文件")

# 执行搜索
results = mcp.search("def my_function")
for result in results:
    print(f"{result['file']}:{result['line']} - {result['content']}")

# 语言特定搜索
python_results = mcp.search_by_language("python", "class MyClass")

# 获取统计信息
stats = mcp.get_stats()
print(f"总文件数: {stats['total_files']}")
print(f"总行数: {stats['total_lines']}")

Docker 部署

使用 Docker Compose 快速开始（推荐）

# 1. 启动服务（SQLite 模式，最简单）
docker-compose up -d

# 2. 打开 Web UI
open http://localhost:8000

# 3. 查看日志
docker-compose logs -f codeindex

使用不同的存储模式

# SQLite 模式（默认，本地存储）
docker-compose up -d

# Hybrid 模式（Redis + SQLite，生产环境推荐）
docker-compose --profile hybrid up -d

# Redis 模式（纯内存缓存）
docker-compose --profile redis up -d

使用 Docker 直接运行

# 构建镜像
docker build -t fast-codeindex:latest .

# SQLite 模式
docker run -d \
  --name codeindex \
  -p 8000:8000 \
  -e STORAGE_TYPE=sqlite \
  fast-codeindex:latest

# Hybrid 模式（需要 Redis 运行）
docker run -d \
  --name codeindex \
  -p 8000:8000 \
  -e STORAGE_TYPE=hybrid \
  -e REDIS_HOST=redis \
  --link redis:redis \
  fast-codeindex:latest

使用预构建的 Docker Hub 镜像

官方镜像已在 Docker Hub 上提供：

# 拉取最新镜像
docker pull wmeng8503/fast-codeindex-mcp:latest

# 使用 SQLite 运行（最简单）
docker run -d -p 8000:8000 \
  -e STORAGE_TYPE=sqlite \
  wmeng8503/fast-codeindex-mcp:latest

# 使用 Hybrid 模式运行（推荐）
docker run -d -p 8000:8000 \
  -e STORAGE_TYPE=hybrid \
  -e REDIS_HOST=redis \
  --link redis:redis \
  wmeng8503/fast-codeindex-mcp:latest

# 打开 Web UI
open http://localhost:8000

镜像：wmeng8503/fast-codeindex-mcp

发布到 Docker Hub

# 1. 登录到 Docker Hub
docker login

# 2. 运行自动发布脚本
./scripts/docker-publish.sh \
  --username your_dockerhub_username \
  --version 1.0.0 \
  --push

# 3. 其他人现在可以使用：
docker pull your_username/fast-codeindex-mcp:latest

详细的 Docker 说明，请参见 DOCKER_README.md 和 DOCKER_MCP.md

存储架构

可插拔存储系统允许您为不同的使用场景选择最佳的后端：

| 特性 | SQLite | Redis | Hybrid | |------|--------|-------|--------| | 速度 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | | 持久化 | ✅ 内置 | ❌ 内存 | ✅ L2 降级 | | 设置 | 零配置 | 需服务器 | 中等 | | 内存 | 磁盘基 | 内存基 | 均衡 | | 用途 | 开发、本地 | 高速缓存 | 生产环境 | | 成本 | 免费 | 免费 | 免费 |

选择存储模式

# SQLite（默认 - 无外部依赖）
export STORAGE_TYPE=sqlite
export SQLITE_PATH=/data/code_index.db

# Redis（需要 Redis 服务器运行）
export STORAGE_TYPE=redis
export REDIS_HOST=localhost
export REDIS_PORT=6379

# Hybrid（生产环境推荐）
export STORAGE_TYPE=hybrid
export REDIS_HOST=localhost
export SQLITE_PATH=/data/code_index.db

Hybrid 模式架构

┌─────────────────────────┐
│   Fast-CodeIndex MCP    │
└────────────┬────────────┘
             │
      ┌──────┴──────┐
      ▼             ▼
   L1 缓存       L2 存储
   (Redis)      (SQLite)
 ─────────────  ─────────────
• 超快速        • 持久化
• 内存基        • 降级方案
• 自动过期      • 完整数据

项目结构

fast-codeindex-mcp/
├── src/fast_codeindex/
│   ├── __init__.py          # 包初始化
│   ├── cli.py               # 命令行界面
│   ├── indexer.py           # 代码索引引擎
│   ├── mcp_server.py        # MCP 服务器实现
│   ├── search_engine.py     # 搜索引擎核心
│   └── utils.py             # 工具函数
├── tests/                   # 测试套件
├── docs/
│   ├── API.md               # 完整 API 文档
│   ├── DEVELOPMENT.md       # 开发指南
│   └── DEPLOYMENT.md        # 部署指南
├── examples/                # 使用示例
├── .github/workflows/       # CI/CD 配置
├── Dockerfile               # Docker 配置
├── docker-compose.yml       # Docker Compose 配置
└── README.md               # 本文件

API 亮点

CodeIndexer（代码索引器）

indexer = CodeIndexer("code_index.db")

# 索引目录
result = indexer.index_directory("/path/to/project", recursive=True)

# 获取统计信息
stats = indexer.get_stats()

CodeSearchEngine（搜索引擎）

engine = CodeSearchEngine("code_index.db")

# 全文搜索
results = engine.search_text("查询", limit=50)

# 函数搜索
functions = engine.search_function("函数名", limit=50)

# 语言特定搜索
python_code = engine.search_by_language("python", "import", limit=50)

# 导出结果
json_output = engine.export_results(results, format="json")

FastCodeIndexMCP（MCP 服务器）

mcp = FastCodeIndexMCP("code_index.db")

# 索引项目
mcp.index_project("/path/to/project")

# 各种搜索方法
mcp.search("查询")
mcp.search_function("函数名")
mcp.search_by_language("python")

# 统计和管理
mcp.get_stats()
mcp.clear_index()

文档

• 📖 快速开始指南
• 📚 API 文档
• 🔧 开发指南
• 🚀 部署指南
• 🤝 贡献指南

开发

环境设置

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 代码质量检查
black src tests
flake8 src tests
mypy src

测试

# 运行所有测试
pytest

# 运行带覆盖率的测试
pytest --cov=src/fast_codeindex

# 运行特定测试
pytest tests/test_search.py::TestCodeSearchEngine

性能

• 索引性能: 高效处理 1000+ 个文件
• 搜索性能: 平均查询响应时间 <10ms
• 内存占用: 针对大型代码库优化（已测试 100K+ 行代码）

配置

环境变量

在项目根目录创建 .env 文件：

DATABASE_PATH=./code_index.db
HOST=localhost
PORT=8000
LOG_LEVEL=INFO
MAX_RESULTS=100
MIN_MATCH_SCORE=0.5

MCP 服务器配置

fast-codeindex-mcp 可以作为 MCP 服务器与 Claude 和其他 AI 工具集成。按照以下步骤进行集成：

1. 安装为 MCP 服务器

pip install -e .

2. 配置 Claude Desktop

编辑 Claude Desktop 配置文件：

macOS/Linux: ~/.config/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

基本配置（直接方式）：

{
  "mcpServers": {
    "fast-codeindex-mcp": {
      "command": "python",
      "args": ["-m", "fast_codeindex.mcp_server"],
      "env": {
        "STORAGE_TYPE": "sqlite",
        "SQLITE_PATH": "./code_index.db"
      }
    }
  }
}

使用 ccswitch（推荐）：

如果你使用 ccswitch 来管理多个 Claude 实例，可以通过 ccswitch HTTP 端点添加配置：

{
  "mcpServers": {
    "fast-codeindex-mcp": {
      "command": "http",
      "url": "http://127.0.0.1:12138"
    }
  }
}

或者使用环境变量进行动态配置：

{
  "mcpServers": {
    "fast-codeindex-mcp": {
      "command": "http",
      "url": "http://127.0.0.1:12138",
      "env": {
        "STORAGE_TYPE": "sqlite",
        "SQLITE_PATH": "./code_index.db"
      }
    }
  }
}

注意：确保在启动 Claude Desktop 前 ccswitch 已运行。端口 12138 是默认值，如果你的 ccswitch 使用不同端口，请进行相应调整。

3. 存储后端配置

通过在 MCP 配置中设置环境变量来选择存储后端：

SQLite（默认）

{
  "mcpServers": {
    "fast-codeindex-mcp": {
      "command": "python",
      "args": ["-m", "fast_codeindex.mcp_server"],
      "env": {
        "STORAGE_TYPE": "sqlite",
        "SQLITE_PATH": "/path/to/code_index.db"
      }
    }
  }
}

Redis

{
  "mcpServers": {
    "fast-codeindex-mcp": {
      "command": "python",
      "args": ["-m", "fast_codeindex.mcp_server"],
      "env": {
        "STORAGE_TYPE": "redis",
        "REDIS_HOST": "localhost",
        "REDIS_PORT": "6379"
      }
    }
  }
}

混合模式（推荐）

{
  "mcpServers": {
    "fast-codeindex-mcp": {
      "command": "python",
      "args": ["-m", "fast_codeindex.mcp_server"],
      "env": {
        "STORAGE_TYPE": "hybrid",
        "REDIS_HOST": "localhost",
        "REDIS_PORT": "6379",
        "SQLITE_PATH": "/path/to/code_index.db"
      }
    }
  }
}

4. 在 Claude 中使用 MCP 服务器

配置完成后，可以直接在 Claude 中使用 fast-codeindex-mcp：

# MCP 服务器提供以下工具：
# - index_project(path): 索引项目目录
# - search(query): 在索引代码中进行全文搜索
# - search_function(name): 搜索函数定义
# - search_by_language(language, query): 按编程语言搜索
# - get_stats(): 获取索引统计信息
# - clear_index(): 清空所有索引数据

5. Docker MCP 服务器

如果在 Docker 中运行服务器，使用 Docker 卷（volume）可以更好地持久化数据：

# 首先，为数据库创建 Docker 卷
docker volume create codeindex-storage

然后配置 Claude Desktop：

混合模式（推荐）：

{
  "mcpServers": {
    "fast-codeindex-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "codeindex-storage:/data",
        "-e", "STORAGE_TYPE=hybrid",
        "-e", "REDIS_HOST=host.docker.internal",
        "-e", "SQLITE_PATH=/data/code_index.db",
        "your-username/fast-codeindex-mcp:latest",
        "python", "-m", "fast_codeindex.mcp_server"
      ]
    }
  }
}

仅 SQLite（更简单）：

{
  "mcpServers": {
    "fast-codeindex-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "codeindex-storage:/data",
        "-e", "STORAGE_TYPE=sqlite",
        "-e", "SQLITE_PATH=/data/code_index.db",
        "your-username/fast-codeindex-mcp:latest",
        "python", "-m", "fast_codeindex.mcp_server"
      ]
    }
  }
}

6. MCP 配置故障排除

问题：MCP 服务器未找到

• 确保已安装 fast-codeindex-mcp：pip install -e .
• 检查配置文件中的路径是否正确

问题：连接超时

• 验证 Python 环境是否可从 Claude 访问
• 检查是否已安装所有必需的依赖

问题：存储后端不可访问

• Redis：确保 Redis 服务正在运行且可访问
• SQLite：验证数据库文件的文件权限
• 检查环境变量是否设置正确

贡献

欢迎提交贡献！请阅读 贡献指南 了解：

• 如何报告 Bug
• 如何提出功能建议
• 开发工作流程
• 代码风格指南
• 测试要求

许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

引用

如果您在研究或工作中使用了本项目，请引用：

@software{fast_codeindex_mcp,
  title={fast-codeindex-mcp},
  author={Your Name},
  year={2024},
  url={https://github.com/yourusername/fast-codeindex-mcp}
}

故障排除

Q: 搜索没有返回结果

• A: 确保已使用 fast-codeindex index /path/to/project 索引您的项目

Q: 索引速度慢

• A: 限制目录大小或使用搜索的 --limit 参数

Q: 数据库损坏

• A: 删除 code_index.db 并重新索引项目

常见问题

Q: 最大支持的项目大小是多少？

• A: 已测试包含 100K+ 行代码的项目

Q: 可以用于多个项目吗？

• A: 可以，为不同项目创建单独的数据库

Q: 索引是否持久化？

• A: 是的，SQLite 数据库会跨会话持久化

路线图

• [x] Web UI 界面 (✅ 已完成！)
• [x] 可插拔存储 (✅ SQLite, Redis, Hybrid)
• [x] Docker 部署 (✅ Docker 和 Docker Compose 就绪)
• [ ] 高级语义搜索
• [ ] 分布式索引
• [ ] 云存储集成
• [ ] IDE 插件支持

支持

• 📧 邮件: contact@example.com
• 🐛 问题追踪: GitHub Issues
• 💬 讨论: GitHub Discussions

---