星战科技xingzhan.cloud
返回市场
MCP代码索引器

MCP代码索引器

作者：fluffypony9 星标更新：2025-09-13
安装使用来源：spider==github.com

项目介绍

MCP Code Indexer 🚀

PyPI 版本 Python 许可证

一个生产就绪的 模型上下文协议 (MCP) 服务器，它革新了AI代理如何导航和理解代码库。AI代理无需反复扫描文件，即可即时访问智能描述、语义搜索和上下文感知建议。

🎯 功能概述

MCP Code Indexer 解决了大型代码库中AI代理的一个关键问题：无需反复扫描文件就能理解代码结构。代理可以：

  • 使用自然语言描述即时查询文件用途
  • 使用全文搜索跨代码库搜索
  • 根据代码库大小获得智能推荐（概览与搜索）
  • 在合并分支时解决冲突并合并分支描述
  • 自动从上游仓库继承描述

适用于AI驱动的代码审查、重构工具、文档生成和代码库分析工作流。

⚡ 快速开始

👨‍💻 开发者

开始将MCP Code Indexer集成到您的AI代理工作流中：

# 安装包
pip install mcp-code-indexer

# 启动MCP服务器
mcp-code-indexer

# 连接您的MCP客户端并开始使用工具
# 查看API参考以获取完整的工具文档

🔧 系统管理员

部署并配置服务器供团队使用：

# 生产环境部署，自定义设置
mcp-code-indexer \
  --token-limit 64000 \
  --db-path /data/mcp-index.db \
  --cache-dir /var/cache/mcp \
  --log-level INFO

# 检查安装
mcp-code-indexer --version

🎯 所有人

新用户？ 从这里开始：

  1. 安装：pip install mcp-code-indexer
  2. 运行：mcp-code-indexer --token-limit 32000
  3. 连接：使用您喜欢的MCP客户端
  4. 探索：首先尝试check_codebase_size工具

开发设置：

# 克隆并设置贡献环境
git clone https://github.com/fluffypony/mcp-code-indexer.git
cd mcp-code-indexer

# 以开发模式安装（必需）
pip install -e .

# 运行服务器
mcp-code-indexer --token-limit 32000

🔗 Git Hook 集成

🚀 新功能：自动代码索引，结合AI驱动的分析！随着代码库的发展，自动同步文件描述。

👤 用户快速设置

# 设置OpenRouter API密钥
export OPENROUTER_API_KEY="sk-or-v1-your-api-key-here"

# 测试git钩子功能
mcp-code-indexer --githook

# 安装post-commit钩子
cp examples/git-hooks/post-commit .git/hooks/
chmod +x .git/hooks/post-commit

👨‍💻 开发者：如何工作

Git钩子集成为智能自动化提供支持：

  • 📊 Git 分析：提交或合并后自动分析git差异
  • 🤖 AI 处理：使用OpenRouter API和Anthropic的Claude Sonnet 4
  • ⚡ 智能更新：仅处理实际更改的文件
  • 🔄 概览维护：当结构变化时更新项目概览
  • 🛡️ 错误隔离：即使索引失败，git操作也会继续
  • ⏱️ 速率限制：内置指数退避重试逻辑

🎯 主要优势

💡 零手动工作：描述始终保持最新，无需任何努力 ⚡ 性能：仅分析更改的文件，而不是整个代码库 🔒 可靠性：强大的错误处理确保git操作不会失败 🎛️ 可配置性：支持自定义模型和超时设置

了解更多：参见Git Hook 设置指南，了解完整的配置选项和故障排除方法。

🔧 开发设置

👨‍💻 贡献者

为MCP Code Indexer贡献？遵循这些步骤设置适当的开发环境：

# 设置开发环境
git clone https://github.com/fluffypony/mcp-code-indexer.git
cd mcp-code-indexer

# 创建并激活虚拟环境
python -m venv venv
source venv/bin/activate  # 在Windows上：venv\Scripts\activate

# 以可编辑模式安装包（开发必需）
pip install -e .

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

# 验证安装
python main.py --help
mcp-code-indexer --version

⚠️ 重要：可编辑安装（pip install -e .）是开发所必需的。项目使用标准的PyPI包结构，绝对导入如from mcp_code_indexer.database.database import DatabaseManager。如果没有可编辑安装，将会遇到ModuleNotFoundError异常。

🎯 开发工作流程

# 激活虚拟环境
source venv/bin/activate

# 直接运行服务器
python main.py --token-limit 32000

# 或使用已安装的CLI命令
mcp-code-indexer --token-limit 32000

# 运行测试
python -m pytest tests/ -v

# 带覆盖率运行测试
python -m pytest tests/ --cov=src --cov-report=html

# 格式化代码
black src/ tests/
isort src/ tests/

# 类型检查
mypy src/

🛠️ MCP 工具可用

服务器提供了11个强大的MCP工具，用于智能代码库管理。无论是AI代理还是人类开发者，这些工具都能使代码导航变得轻松。

🎯 所有人：从这里开始

  • check_codebase_size - 获取即时推荐，了解如何导航您的代码库
  • search_descriptions - 通过它们的功能查找文件，而不仅仅是名称
  • get_codebase_overview - 获取任何项目的高层次理解

👨‍💻 开发者：核心操作

  • get_file_description - 即时检索存储的文件描述
  • update_file_description - 存储详细的文件摘要和元数据
  • find_missing_descriptions - 扫描项目以查找没有描述的文件
  • update_missing_descriptions - 批量更新多个文件描述

🔍 高级用户：搜索与发现

  • get_all_descriptions - 完整的分层项目结构
  • get_word_frequency - 技术词汇分析，带停用词过滤
  • merge_branch_descriptions - 两阶段合并，带冲突解决
  • update_codebase_overview - 创建全面的代码库文档

💡 专业提示：始终从check_codebase_size开始，以获取针对特定代码库的个性化推荐。

🔗 Git Hook 集成

在每次提交、rebase或合并时，自动同步代码库文档，进行分析：

# 分析当前暂存的变化
mcp-code-indexer --githook

# 分析特定提交
mcp-code-indexer --githook abc123def

# 分析提交范围（适合rebase）
mcp-code-indexer --githook abc123 def456

🎯 适用于：

  • 自动文档，永远不会过时
  • rebase感知分析，处理复杂的git操作
  • 零努力维护，后台处理

参见**Git Hook 设置指南**，了解包括post-commit、post-merge和post-rewrite钩子在内的完整安装说明。

🏗️ 架构亮点

性能优化

  • SQLite 附带WAL模式，实现高并发访问
  • 连接池，实现高效的数据库操作
  • FTS5全文搜索，带有前缀索引
  • 令牌感知缓存，以最小化昂贵的操作

生产就绪

  • 全面的错误处理，带有结构化的JSON日志
  • 异步优先设计，带有正确的资源清理
  • MCP协议兼容，带有干净的stdio流
  • 上游继承，适用于fork工作流
  • Git集成，带有.gitignore支持

开发者友好

  • 95%以上的测试覆盖率，带有异步支持
  • 集成测试，覆盖完整的工作流
  • 性能基准测试，适用于大型代码库
  • 清晰的错误消息，符合MCP协议

📖 文档

👤 用户

👨‍💻 开发者

🤝 贡献者

🚦 系统需求

  • Python 3.8+，带有asyncio支持
  • SQLite 3.35+（随Python自带）
  • 4GB+ 内存，适用于大型代码库（1000+ 文件）
  • SSD 存储，推荐以获得最佳性能

📊 性能

经过高达10,000个文件的代码库测试：

  • 文件描述检索：<10毫秒
  • 全文搜索：<100毫秒
  • 代码库概览生成：<2秒
  • 合并冲突检测：<5秒

🔧 高级配置

# 生产环境设置，自定义限制
mcp-code-indexer \
  --token-limit 50000 \
  --db-path /data/mcp-index.db \
  --cache-dir /tmp/mcp-cache \
  --log-level INFO

# 启用结构化日志
export MCP_LOG_FORMAT=json
mcp-code-indexer

🤝 集成示例

与AI代理

# 示例：AI代理使用MCP工具
async def analyze_codebase(project_path):
    # 检查代码库是否很大
    size_info = await mcp_client.call_tool("check_codebase_size", {
        "projectName": "my-project",
        "folderPath": project_path,
        "branch": "main"
    })
    
    if size_info["isLarge"]:
        # 对于大型代码库使用搜索
        results = await mcp_client.call_tool("search_descriptions", {
            "projectName": "my-project", 
            "folderPath": project_path,
            "branch": "main",
            "query": "认证逻辑"
        })
    else:
        # 对于较小的项目获取完整概览
        overview = await mcp_client.call_tool("get_codebase_overview", {
            "projectName": "my-project",
            "folderPath": project_path, 
            "branch": "main"
        })

与CI/CD流水线

# 示例：GitHub Actions集成
- name: 更新代码描述
  run: |
    python -c "
    import asyncio
    from mcp_client import MCPClient
    
    async def update_descriptions():
        client = MCPClient('mcp-code-indexer')
        
        # 查找没有描述的文件
        missing = await client.call_tool('find_missing_descriptions', {
            'projectName': '${{ github.repository }}',
            'folderPath': '.',
            'branch': '${{ github.ref_name }}'
        })
        
        # 使用AI处理并更新...
    
    asyncio.run(update_descriptions())
    "

🧪 测试

# 安装带测试依赖
pip install mcp-code-indexer[test]

# 运行完整测试套件
python -m pytest tests/ -v

# 带覆盖率运行测试
python -m pytest tests/ --cov=src --cov-report=html

# 运行性能测试
python -m pytest tests/ -m performance

# 仅运行集成测试
python -m pytest tests/integration/ -v

📈 监控

服务器提供结构化的JSON日志用于监控：

{
  "timestamp": "2024-01-15T10:30:00Z",
  "level": "INFO",
  "message": "工具search_descriptions完成",
  "tool_usage": {
    "tool_name": "search_descriptions",
    "success": true,
    "duration_seconds": 0.045,
    "result_size": 1247
  }
}

📋 命令行选项

服务器模式（默认）

mcp-code-indexer [OPTIONS]

选项：
  --token-limit INT     推荐搜索前的最大令牌数（默认：32000）
  --db-path PATH        SQLite数据库路径（默认：~/.mcp-code-index/tracker.db）
  --cache-dir PATH      缓存目录路径（默认：~/.mcp-code-index/cache）
  --log-level LEVEL     日志级别：DEBUG|INFO|WARNING|ERROR|CRITICAL（默认：INFO）

Git Hook 模式

mcp-code-indexer --githook [OPTIONS]

# 使用OpenRouter API自动分析git变更
# 需要：OPENROUTER_API_KEY环境变量

实用命令

# 列出所有项目和分支
mcp-code-indexer --getprojects

# 直接执行MCP工具
mcp-code-indexer --runcommand '{"method": "tools/call", "params": {...}}'

# 导出项目的描述
mcp-code-indexer --dumpdescriptions PROJECT_ID [BRANCH]

🛡️ 安全特性

  • 所有MCP工具参数上的输入验证
  • SQL注入防护，通过参数化查询
  • 文件系统沙箱，尊重.gitignore
  • 错误净化，防止信息泄露
  • 异步资源清理，防止内存泄漏

🚀 下一步

准备好为您的AI代理提供智能代码库导航吗？

👤 开始使用

  1. 安装并运行您的第一个服务器 - 2分钟内启动
  2. 设置git钩子 - 自动化您的工作流
  3. 配置生产环境 - 为您的团队部署

👨‍💻 开发者

  1. 探索API工具 - 掌握全部11个MCP工具
  2. 理解架构 - 深入技术设计

🤝 加入社区

  1. 为项目贡献 - 让它变得更好
  2. 在GitHub上报告问题 - 分享反馈和建议

🤝 贡献

我们欢迎贡献！参见我们的**贡献指南**，了解：

  • 开发设置
  • 代码风格指南
  • 测试要求
  • 拉取请求过程

📄 许可证

MIT 许可证 - 详情见**LICENSE**。

🙏 使用的技术

转变您的AI代理对代码的理解方式！ 🚀

🎯 新用户？ 2分钟内开始 👨‍💻 开发者？ 探索完整的API 🔧 生产环境？ 自信地部署