使用说明
MCP代码索引器🚀
生产准备就绪 模型上下文协议（MCP）服务器 这彻底改变了人工智能代理如何导航和理解代码库。代理可以即时访问智能描述、语义搜索和上下文感知推荐，而不是重复扫描文件。
🎯 它做什么
MCP代码索引器解决了使用大型代码库的AI代理的一个关键问题： 无需反复扫描文件即可理解代码结构。代理可以：
- 查询文件用途 立即使用自然语言描述
- 跨代码库搜索 使用全文搜索
- 获取智能推荐 基于代码库大小（概述与搜索）
- 合并分支描述 解决冲突
- 继承描述 自动从上游存储库
非常适合人工智能驱动的代码审查、重构工具、文档生成和代码库分析工作流程。
⚡ 快速开始
👨💻 对于开发者
开始将MCP代码索引器集成到您的AI代理工作流中：
# Install the package
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
🔧 适用于系统管理员
为您的团队部署和配置服务器：
# 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
🎯 给每个人
MCP代码索引器新手？ 从这里开始：
- 安装:
pip install mcp-code-indexer - 跑:
mcp-code-indexer --token-limit 32000 - 连接：使用您最喜欢的MCP客户端
- 探索：试试
check_codebase_size工具优先
开发设置:
# Clone and setup for contributing
git clone https://github.com/fluffypony/mcp-code-indexer.git
cd mcp-code-indexer
# Install in development mode (required)
pip install -e .
# Run the server
mcp-code-indexer --token-limit 32000
🔗 Git钩子集成
🚀 新功能：使用AI驱动的分析进行自动代码索引！随着代码库的发展，保持文件描述的自动同步。
👤 用户：快速设置
# 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
👨💻 开发者：它是如何工作的
git钩子集成提供智能自动化：
- 📊 Git分析：提交/合并后自动分析git差异
- 🤖 人工智能处理：使用OpenRouter API和Anthropic的Claude Sonnet 4
- ⚡ 智能更新：仅处理实际更改的文件
- 🔄 维护概述：结构更改时更新项目概述
- 🛡️ 错误隔离：即使索引失败，Git操作也会继续
- ⏱️ 速率限制：具有指数回退的内置重试逻辑
🎯 关键利益
💡 零人工操作：描述保持最新，无需任何努力
⚡ 演出：仅分析更改的文件，而不是整个代码库
🔒 可靠性：强大的错误处理确保git操作永远不会失败
🎛️ 可配置的：支持自定义模型和超时设置
了解更多：参见 Git钩子设置指南 了解完整的配置选项和故障排除。
🔧 开发设置
👨💻 对于贡献者
为MCP代码索引器做出贡献？遵循以下步骤以获得适当的开发环境：
# Setup development environment
git clone https://github.com/fluffypony/mcp-code-indexer.git
cd mcp-code-indexer
# Create and activate virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install package in editable mode (REQUIRED for development)
pip install -e .
# Install development dependencies
pip install -e .[dev]
# Verify installation
python main.py --help
mcp-code-indexer --version
⚠️ 重要：可编辑安装(pip install -e .)是 必需的 为了发展。该项目使用适当的PyPI包结构，具有绝对导入，如 from mcp_code_indexer.database.database import DatabaseManager。如果没有可编辑的安装，您将获得 ModuleNotFoundError 例外情况。
🎯 开发工作流程
# 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工具可用
服务器提供 11个强大的MCP工具 用于智能代码库管理。无论您是人工智能代理还是人类开发人员，这些工具都可以轻松地导航代码。
🎯 适合所有人：从这里开始
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钩子集成
使您的代码库文档与每次提交、重基或合并时的自动分析自动同步：
# Analyze current staged changes
mcp-code-indexer --githook
# Analyze a specific commit
mcp-code-indexer --githook abc123def
# Analyze a commit range (perfect for rebases)
mcp-code-indexer --githook abc123 def456
🎯 非常适合:
- 自动化文档 它永远不会过时
- 重基感知分析 处理复杂的git操作
- 零维护 带背景处理
请参阅 Git钩子设置指南 获取完整的安装说明，包括提交后、合并后和重写后挂钩。
🏗️ 建筑亮点
性能优化
- 带WAL模式的SQLite 用于高并发访问
- 连接池 实现高效的数据库操作
- FTS5全文搜索 带前缀索引
- 令牌感知缓存 尽量减少昂贵的操作
生产就绪
- 全面的错误处理 使用结构化JSON日志记录
- 异步优先设计 进行适当的资源清理
- 符合MCP协议 具有干净的stdio流
- 上游继承 用于fork工作流
- Git集成 有.gitignore支持
开发者友好
- 95%以上的测试覆盖率 支持异步
- 集成测试 用于完整的工作流程
- 性能基准 适用于大型代码库
- 清除错误消息 符合MCP协议
📖 文档
👤 对于用户
👨💻 对于开发者
🤝 对于贡献者
- 贡献指南 -开发设置和工作流程指南
🚦 系统要求
- Python 3.8+ 支持asyncio
- SQLite 3.35+ （包含在Python中）
- 4GB+内存 适用于大型代码库（1000+个文件）
- SSD存储 推荐以获得最佳性能
📊 演出
使用高达的代码库进行测试 10000个文件:
- 文件描述检索： <10ms
- 全文搜索： <100ms
- 代码库概述生成： <2s
- 合并冲突检测： <5s
🔧 高级配置
# 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
🤝 集成示例
使用AI代理
# 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,
"branch": "main"
})
if size_info["isLarge"]:
# Use search for large codebases
results = await mcp_client.call_tool("search_descriptions", {
"projectName": "my-project",
"folderPath": project_path,
"branch": "main",
"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,
"branch": "main"
})
使用CI/CD管道
# 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': '.',
'branch': '${{ github.ref_name }}'
})
# Process with AI and update...
asyncio.run(update_descriptions())
"
🧪 测试
# Install with test dependencies
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
📈 监控
服务器提供结构化的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
}
}
📋 命令行选项
服务器模式（默认）
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挂钩模式
mcp-code-indexer --githook [OPTIONS]
# Automated analysis of git changes using OpenRouter API
# Requires: OPENROUTER_API_KEY environment variable
实用程序命令
# List all projects and branches
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 [BRANCH]
🛡️ 安全功能
- 输入验证 所有MCP工具参数
- SQL注入保护 通过参数化查询
- 文件系统沙盒 尊敬的.gitignore
- 错误清理 防止信息泄露
- 异步资源清理 防止内存泄漏
🚀 后续步骤
准备好用智能代码库导航来增强你的人工智能代理了吗？
👤 入门指南
- 安装并运行您的第一台服务器 -2分钟后起床跑步
- 设置git挂钩 -自动化您的工作流程
- 配置用于生产 -为您的团队部署
👨💻 对于开发者
🤝 加入社区
- 为项目做出贡献 -帮助它变得更好
- 在GitHub上报告问题 -分享反馈和建议
🤝 贡献
我们欢迎捐款！查看我们的 贡献指南 用于：
- 开发设置
- 代码风格指南
- 测试要求
- 拉取请求流程
📄 许可证
MIT许可证-请参阅 许可证 了解详情。
🙏 构建于
- 模型上下文协议 -工具集成的基础
- tiktoken -快速BPE标记化
- aiosqlite -异步SQLite操作
- 意图tp -用于OpenRouter API的异步HTTP客户端
- 坚韧 -强大的重试逻辑和速率限制
- 派丹蒂克 -数据验证和设置
改变你的AI代理理解代码的方式！ 🚀
