Codebase Contextifier 9000

代码库上下文生成器9000

基于Docker的模型上下文协议（MCP）服务器，用于语义代码搜索，具有AST感知分块、通过Neo4j图数据库进行关系跟踪、本地LLM支持和增量索引。

文档

• 📚 快速入门指南 -5分钟后开始跑步
• 🔧 多项目设置 -使用共享后端为多个项目建立索引
• ⚙️ 后台作业 -基于作业的大型代码库索引
• 👁️ 文件监视器指南 -实时监控和自动索引
• 🔬 研究与方法 -深入了解语义代码搜索
• 📖 全部文件 -完整的文档目录

目录

• 特性
• 建筑

- 主要建筑特征

• 快速开始

- 先决条件 - 两种部署选项 - Claude桌面配置 - 用法

• MCP工具

- 索引工具: index_repository, get_job_status, list_indexing_jobs, cancel_indexing_job - 搜索工具: search_code, get_symbols - 图形查询工具: find_usages, find_dependencies, query_graph - 依赖工具: detect_dependencies, index_dependencies, list_indexed_dependencies - 状态工具: get_indexing_status, clear_index, get_watcher_status, health_check

• 支持的语言
• 配置

- 环境变量 - 推荐的嵌入模型

• 演出
• 故障排除
• 发展
• 建筑细部

- AST感知分块 - 增量索引 - 内容寻址存储

• 路线图
• 研究与参考
• 许可证
• 贡献
• 支持

特性

• AST感知分块：使用树保姆来尊重函数和类边界，维护语义完整性
• 关系跟踪：Neo4j图形数据库跟踪代码库中的函数调用、导入、继承和依赖关系
• 外部依赖关系映射：自动为外部函数（WordPress、npm包等）创建占位符节点
• 基于作业的索引：大型代码库的背景索引和进度跟踪
• 按需集装箱产卵：无需手动挂载即可索引系统上的任何存储库
• 多存储库搜索：使用共享后端对多个项目进行索引和搜索
• 实时更新：文件系统监视器自动重新索引更改的文件（可选）
• 本地优先：所有处理都在本地使用Ollama进行嵌入（没有数据离开您的机器）
• Polyglot支持：支持10多种编程语言，包括TypeScript、Python、PHP、Go、Rust、Java、C++等
• 增量索引：基于默克尔树的变化检测，缓存命中率超过80%
• 等级：使用Qdrant矢量数据库进行低于10ms的搜索延迟，使用Neo4j进行关系查询
• 依赖性知识库：用于索引WordPress插件、Composer包和npm模块的特殊集合
• 灵活部署：每个项目或集中式服务器部署选项
• MCP集成：适用于Claude Desktop、Cursor、VS Code和其他MCP兼容工具

建筑

┌─────────────────────────────────────────────────────────────────┐
│  MCP Client (Claude Code, Claude Desktop, Cursor, etc.)         │
└──────────────────────────────┬──────────────────────────────────┘
                               │ MCP Protocol (stdio)
                               │
┌──────────────────────────────▼──────────────────────────────────┐
│  MCP Server Container (codebase-mcp-server)                     │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  FastMCP Server - Exposes MCP Tools:                      │  │
│  │  • index_repository (spawns indexer containers)           │  │
│  │  • search_code (semantic search across all repos)         │  │
│  │  • find_usages, find_dependencies (graph queries)         │  │
│  │  • detect_dependencies, index_dependencies                │  │
│  │  • get_job_status, list_indexing_jobs, cancel_job        │  │
│  │  • get_symbols, get_indexing_status, health_check        │  │
│  └──────────────┬───────────────────────────────────────────┘  │
│                 │                                                │
│                 │ Spawns via Docker Socket                       │
│                 ▼                                                │
│  ┌─────────────────────────────────────────────────────┐       │
│  │  On-Demand Indexer Containers (ephemeral)           │       │
│  │  • Mounts any host directory                        │       │
│  │  • AST-aware chunking with tree-sitter              │       │
│  │  • Extracts relationships (CALLS, IMPORTS, etc.)    │       │
│  │  • Generates embeddings via Ollama                  │       │
│  │  • Updates shared Qdrant & Neo4j databases          │       │
│  │  • Reports progress back to MCP server              │       │
│  └──────────────────────┬──────────────────────────────┘       │
└─────────────────────────┼──────────────────────────────────────┘
                          │
          ┌───────────────┴───────────────────┐
          │                                   │
   ┌──────▼──────┐              ┌────────────▼────────┐
   │   Qdrant    │              │      Neo4j          │
   │  Container  │              │    Container        │
   │  (Vectors)  │              │  (Relationships)    │
   └──────┬──────┘              └──────┬──────────────┘
          │                            │
   ┌──────▼────────────────────────────▼───────────┐
   │  Persistent Docker Volumes:                   │
   │  • qdrant_data (vector DB)                    │
   │  • neo4j_data (graph DB)                      │
   │  • index_data (merkle trees)                  │
   │  • cache_data (embeddings cache)              │
   └───────────────────────────────────────────────┘

   ┌────────────────────────┐
   │  Ollama (Host)         │
   │  Embedding Model       │
   └────────────────────────┘

主要建筑特征

• 双数据库架构：Qdrant用于语义向量搜索，Neo4j用于关系图查询
• 容器编排：MCP服务器通过Docker套接字按需生成轻量级索引器容器
• 多存储库支持：每个存储库都有自己的默克尔树状态，但共享向量和图形数据库
• 共享后端：所有项目都使用相同的Qdrant和Neo4j实例，支持跨存储库搜索和关系跟踪
• 基于作业的处理：具有大型代码库进度跟踪功能的后台作业
• 内容可寻址缓存：嵌入由内容哈希缓存，在所有存储库中共享
• 关系提取：基于AST提取CALLS、IMPORT、EXTENDS和IMPLEMENTS关系
• 外部依赖跟踪：为未解析的函数调用自动创建占位符节点

快速开始

看 快速启动.md 有关详细的设置说明。

先决条件

1. Docker桌面 （或Docker+Docker Compose）
2. 奥拉玛 使用嵌入模型在本地运行：

   # Install Ollama: https://ollama.ai

   # Recommended: Google's Gemma embedding model (best quality)
   ollama pull embeddinggemma:latest

   # Alternative: Nomic Embed (faster, smaller)
   ollama pull nomic-embed-text

两种部署选项

选项A：集中式服务器（推荐）

最适合：从MCP服务器进行索引，跨所有存储库进行查询

# 1. Start the backend
cd codebase-contextifier-9000
docker-compose up -d

# 2. Configure Claude Desktop (see below)

# 3. Index any repository
# In Claude: "Index the repository at /Users/me/projects/my-app"

选项B：按项目设置

最适合：每个项目管理自己的索引

# 1. Start shared backend (once)
cd codebase-contextifier-9000
docker-compose up -d

# 2. Copy .mcp.json to each project
cp .mcp.json.template ~/projects/my-app/.mcp.json

# 3. Open project in Claude Code
cd ~/projects/my-app
claude-code .

看 MULTI_PROJECT_SETUP.md 了解详情。

Claude桌面配置

对于集中式服务器（选项A）：

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "codebase-contextifier": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "codebase-mcp-server",
        "python",
        "-m",
        "src.server"
      ]
    }
  }
}

对于每个项目设置（选项B）：

只需复制 .mcp.json.template 到您的项目目录-无需手动配置！

用法

配置后，您可以在Claude Desktop或Claude Code中使用这些工具：

为系统上的任何存储库建立索引：

Claude, index the repository at /Users/me/projects/my-app

系统生成一个容器，在后台对存储库进行索引，并报告进度。

监控索引进度：

Claude, show me the status of job abc123

在所有索引存储库中搜索代码：

Claude, search for "authentication logic" in the codebase

使用筛选器搜索：

Claude, search for "error handling" filtering by language=python and repo_name=my-api

从文件中提取符号：

Claude, get all functions from /workspace/src/utils.py

查找函数的所有用法（图形查询）：

Claude, find all places where authenticate_user is called

查找函数的依赖关系（图查询）：

Claude, show me all functions that processPayment depends on

检测并索引外部依赖关系：

Claude, detect available WordPress plugins in this project
Claude, index the woocommerce plugin into the knowledge base

检查系统状态：

Claude, show me the indexing status and list all jobs

MCP工具

索引工具

index_repository

通过生成轻量级索引器容器，从主机上的任何目录对存储库进行索引。

参数：

• host_path （string，必填）：主机上到存储库的绝对路径（例如。， /Users/me/projects/my-app)
• repo_name （字符串，可选）：此存储库的唯一标识符（默认为目录名）
• incremental （bool）：使用增量索引仅重新索引更改的文件（默认值： true)
• exclude_patterns （string，可选）：要排除的逗号分隔的glob模式（例如。， "node_modules/*,dist/*")

退货：

{
  "success": true,
  "job_id": "abc123def456",
  "repo_name": "my-app",
  "status": "queued",
  "message": "Background indexing started for 'my-app'"
}

例子：

# Index a WordPress site, excluding plugins and uploads
await index_repository(
    host_path="/Users/me/sites/my-wordpress",
    repo_name="my-wordpress",
    exclude_patterns="wp-content/plugins/*,wp-content/uploads/*,wp-includes/*"
)

get_job_status

获取索引作业的状态和进度。

参数：

• job_id （字符串，必填）：从返回的作业标识符 index_repository

退货：

{
  "success": true,
  "job_id": "abc123def456",
  "repo_name": "my-app",
  "repo_path": "/Users/me/projects/my-app",
  "status": "running",
  "created_at": 1698765432.123,
  "started_at": 1698765433.456,
  "elapsed_seconds": 45.2,
  "progress": {
    "current_file": 45,
    "total_files": 100,
    "progress_pct": 45.0,
    "current_file_path": "/workspace/src/api/auth.py",
    "chunks_indexed": 234,
    "failed_files_count": 2,
    "cache_hit_rate": "35.50%"
  }
}

状态值： "queued", "running", "completed", "failed", "cancelled"

list_indexing_jobs

列出所有索引作业（过去和现在）。

退货：

{
  "success": true,
  "total_jobs": 3,
  "jobs": [
    {
      "job_id": "abc123",
      "repo_name": "my-api",
      "status": "completed",
      "progress": { "progress_pct": 100.0, ... }
    },
    {
      "job_id": "def456",
      "repo_name": "frontend",
      "status": "running",
      "progress": { "progress_pct": 67.5, ... }
    }
  ]
}

cancel_indexing_job

取消正在运行的索引作业。

参数：

• job_id （字符串，必填）：要取消的作业标识符

退货：

{
  "success": true,
  "message": "Job abc123 cancelled successfully"
}

搜索工具

search_code

使用具有语义理解的自然语言查询在所有索引存储库中搜索代码。

参数：

• query （字符串，必填）：自然语言搜索查询（例如，“身份验证逻辑”、“错误处理”）
• limit （int）：返回的最大结果数（默认值：10）
• repo_name （字符串，可选）：按存储库名称筛选（如果未指定，则搜索所有存储库）
• language （字符串，可选）：按编程语言过滤（例如，“python”、“typescript”、“php”）
• file_path_filter （string，可选）：按文件路径模式过滤（例如“src/components”）
• chunk_type （字符串，可选）：按块类型过滤（例如，“函数”、“类”、“方法”）

退货：

{
  "success": true,
  "query": "authentication logic",
  "total_results": 5,
  "results": [
    {
      "rank": 1,
      "score": 0.8234,
      "repo_name": "backend-api",
      "file": "/workspace/src/auth/login.ts",
      "lines": "42-68",
      "language": "typescript",
      "type": "function",
      "context": "class:AuthService",
      "code": "async function authenticateUser(username, password) { ... }"
    }
  ]
}

get_symbols

使用AST解析从文件中提取符号。

参数：

• file_path （string）：源文件的路径
• symbol_type （string，可选）：按类型过滤（例如。， "function", "class")

退货：

{
  "success": true,
  "file_path": "/workspace/src/utils.py",
  "total_symbols": 15,
  "symbols": [
    {
      "name": "format_date",
      "type": "function_definition",
      "start_line": 42,
      "end_line": 58,
      "context": "N/A",
      "language": "python"
    }
  ]
}

图形查询工具

find_usages

使用图形数据库查找整个代码库中使用函数、类或符号的所有位置。

参数：

• symbol_name （string，必填）：要查找用法的函数/类的名称
• repo_name （字符串，可选）：按存储库名称筛选

退货：

{
  "success": true,
  "symbol_name": "authenticate_user",
  "total_usages": 12,
  "usages": [
    {
      "caller": "LoginController.handleLogin",
      "caller_file": "/workspace/src/controllers/login.ts",
      "line_number": 42,
      "relationship_type": "CALLS"
    }
  ]
}

find_dependencies

使用图形数据库查找符号所依赖的所有函数、类或导入。

参数：

• symbol_name （string，必填）：要分析的函数/类的名称
• repo_name （字符串，可选）：按存储库名称筛选

退货：

{
  "success": true,
  "symbol_name": "processPayment",
  "total_dependencies": 8,
  "dependencies": [
    {
      "target": "validateCard",
      "target_file": "/workspace/src/utils/validation.ts",
      "relationship_type": "CALLS",
      "is_external": false
    },
    {
      "target": "stripe.charges.create",
      "relationship_type": "CALLS",
      "is_external": true
    }
  ]
}

query_graph

对Neo4j图形数据库执行自定义Cypher查询，以进行高级关系分析。

参数：

• cypher_query （string，必填）：要执行的密码查询
• limit （int，可选）：最大结果数（默认值：100）

退货：

{
  "success": true,
  "query": "MATCH (f:Function)-[:CALLS]->(ext:ExternalFunction) WHERE ext.name =~ 'wp_.*' RETURN f.name, ext.name",
  "results": [
    {"f.name": "enqueue_scripts", "ext.name": "wp_enqueue_script"},
    {"f.name": "setup_theme", "ext.name": "wp_register_nav_menu"}
  ],
  "total_results": 2
}

依赖工具

detect_dependencies

检测工作区中的可用依赖项（WordPress插件/主题、Composer包、npm模块）。

参数：

• workspace_path （字符串，可选）：工作区路径（默认为当前工作区）

退货：

{
  "success": true,
  "dependencies": {
    "wordpress_plugins": ["woocommerce", "advanced-custom-fields"],
    "wordpress_themes": ["twentytwentyfour"],
    "composer_packages": ["symfony/console", "guzzlehttp/guzzle"],
    "npm_packages": ["react", "typescript"]
  },
  "total_dependencies": 6
}

index_dependencies

将特定的依赖关系索引到知识库中，以便更好地理解外部API。

参数：

• dependency_names （array，必填）：要索引的依赖项名称列表（例如。， ["woocommerce", "react"])
• workspace_id （字符串，必填）：工作区/项目的唯一标识符
• workspace_path （字符串，可选）：工作区路径

退货：

{
  "success": true,
  "indexed_dependencies": ["woocommerce"],
  "total_chunks": 1247,
  "message": "Successfully indexed 1 dependencies with 1247 chunks"
}

list_indexed_dependencies

列出知识库中已编入索引的所有依赖项。

退货：

{
  "success": true,
  "dependencies": [
    {
      "name": "woocommerce",
      "version": "8.5.0",
      "type": "wordpress_plugin",
      "workspaces": ["my-store", "test-site"],
      "chunks_count": 1247,
      "indexed_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total_dependencies": 1
}

状态工具

get_indexing_status

获取索引的统计信息，包括向量数据库、图数据库和缓存指标。

退货：

{
  "success": true,
  "code_db": {
    "total_chunks": 2450,
    "vectors_count": 2450,
    "status": "green"
  },
  "knowledge_db": {
    "total_chunks": 1247,
    "indexed_dependencies": ["woocommerce"]
  },
  "graph_db": {
    "enabled": true,
    "total_nodes": 2230,
    "total_relationships": 4407,
    "node_types": {
      "Function": 1459,
      "ExternalFunction": 771
    }
  },
  "index": {
    "indexed_files": 150,
    "total_chunks": 2450
  },
  "cache": {
    "enabled": true,
    "cached_embeddings": 2450,
    "total_size_mb": 18.5
  }
}

clear_index

清除整个索引（有助于重新开始）。

get_watcher_status

获取实时文件监视器的状态。

退货：

{
  "success": true,
  "enabled": true,
  "running": true,
  "watch_path": "/workspace",
  "debounce_seconds": 2.0
}

health_check

检查所有组件（Ollama、Qdrant、Neo4j）的运行状况。

支持的语言

配置

环境变量

推荐的嵌入模型

• embeddinggemma:latest （推荐-最佳质量）
• nomic-embed-text （速度和质量的良好平衡）
• mxbai-embed-large （精度越高，速度越慢）
• all-minilm （最快，精度较低）

演出

索引性能

• 中等代码库 （5K-50K文件）：2-10分钟初始索引
• 增量更新：典型变化为10-60秒
• 缓存命中率：后续运行为80-95%
• 嵌入生成：约100-500块/分钟（取决于Olama的表现）

搜索性能

• 延迟：亚秒级语义搜索
• 吞吐量：10-50个查询/秒
• 准确度：比固定大小的组块好30%（来自研究）

故障排除

“Ollama健康检查失败”

1. 确保Ollama正在跑步： ollama serve
2. 拉动嵌入模型： ollama pull embeddinggemma:latest
3. 检查Docker是否可以访问主机：使用进行测试 curl http://host.docker.internal:11434

“Qdrant连接失败”

1. 检查Qdrant容器是否正在运行： docker-compose ps
2. 检查Qdrant日志： docker-compose logs qdrant
3. 重新启动服务： docker-compose restart

“未启用图形数据库”

1. 集 ENABLE_GRAPH_DB=true 在你的 .env 文件或 .mcp.json
2. 确保配置了Neo4j环境变量： NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD
3. 检查Neo4j容器是否正在运行： docker-compose ps
4. 查看Neo4j日志： docker-compose logs neo4j
5. 测试Neo4j连接： docker exec codebase-neo4j cypher-shell -u neo4j -p codebase123 "RETURN 1"

“找不到支持的文件”

1. 检查 CODEBASE_PATH 是正确的 .env
2. 验证文件是否具有支持的扩展名
3. 检查 .gitignore 没有排除太多

索引速度慢

1. 减少 BATCH_SIZE 如果RAM不足
2. 增加 MAX_CONCURRENT_EMBEDDINGS 如果你有空闲的CPU
3. 使用 incremental=true 用于重新索引

发展

本地运行（无Docker）

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export QDRANT_HOST=localhost
export OLLAMA_HOST=http://localhost:11434
export INDEX_PATH=./index
export CACHE_PATH=./cache
export WORKSPACE_PATH=/path/to/your/codebase

# Start Qdrant
docker run -p 6333:6333 qdrant/qdrant

# Run server
python -m src.server

运行测试

pip install -e ".[dev]"
pytest

代码质量

# Format code
black src/

# Lint code
ruff src/

建筑细部

AST感知分块

该系统使用树保姆将代码解析为抽象语法树（AST），然后提取符合以下条件的语义块：

• 功能边界
• 类定义
• 方法边界
• 接口/特性定义

这实现了 准确度提高30% 根据研究（arXiv:2506.15655），固定大小的组块效果更好。

增量索引

使用基于Merkle树的变化检测：

1. 计算每个文件的Blake3哈希值
2. 与之前的状态进行比较
3. 仅重新索引已更改的文件
4. 增量更新矢量数据库

典型的缓存命中率： 80-95%

内容寻址存储

嵌入使用内容哈希进行缓存：

cache_key = blake3(model_name + file_content)

这使得：

• 缓存嵌入的团队共享
• git操作后快速重新索引
• 跨机器的确定性缓存

路线图

• \[x\] 实时文件系统监视器，用于即时更新
• \[x\] 共享后端的多仓库搜索
• \[x\] 基于作业的背景索引和进度跟踪
• \[x\] 按需生成容器以实现灵活的存储库索引
• \[x\] Neo4j集成用于关系跟踪 -使用外部依赖占位符跟踪函数调用、导入、继承
• \[x\] 依赖性知识库 -索引WordPress插件、Composer包、npm模块
• \[\]使用交叉编码器重新排序以提高精度
• \[\]针对特定领域代码的微调嵌入
• \[\]远程MCP服务器的HTTP传输
• \[\]用于搜索和可视化的Web UI
• \[\]基于图形的代码导航UI（Neo4j浏览器或自定义可视化）

研究与参考

基于语义代码搜索的前沿研究：

• 铸造 （arXiv:2506.15655）：AST感知分块方法
• CodeRAG （arXiv:2504.10046）：图增强检索
• 模型上下文协议：Anthropic的AI工具集成标准
• Qdrant：高性能矢量数据库
• 树保姆：增量解析库

许可证

麻省理工学院

贡献

欢迎投稿！请打开问题或PR。

支持

对于问题、疑问或功能请求，请打开GitHub问题。