Context Engine

基于 tree-sitter 的代码索引与查询引擎，通过 MCP stdio 协议与 Claude Code 通信，提供符号查找、调用图遍历、文件大纲等能力。

特性

• 多语言支持: Python, TypeScript, JavaScript, Go, Rust, Java
• 符号提取: 函数、类、方法的完整信息（签名、注释、源码）
• 调用图分析: 支持多层调用关系查询（调用者/被调用者）
• 全文搜索: 基于 SQLite FTS5 的高效语义搜索
• 增量更新: 文件变化时自动更新索引
• 高性能: L 查询缓存、WAL 模式、并行索引构建

快速开始

安装

# 克隆仓库
git clone https://github.com/happy2h/Code_Context_Engine.git
cd context-engine

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

# 安装依赖
pip install -r requirements.txt

配置

创建 .env 文件（可选）：

CE_DB_PATH=~/.context-engine/my-repo.db
CE_REPO_ROOT=/path/to/your/repo
CE_LOG_LEVEL=INFO
CE_ENABLE_CACHE=true
CE_CACHE_SIZE=1000

索引仓库

# 全量索引
ce index /path/to/your/repo

# 查看索引状态
ce status

启动 MCP Server

ce serve

集成到 Claude Code

在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "context-engine": {
      "type": "stdio",
      "command": "python",
      "args": ["/path/to/context-engine/server.py"],
      "env": {
        "CE_REPO_ROOT": "${workspaceFolder}",
        "CE_DB_PATH": "${workspaceFolder}/.ce/index.db",
        "CE_LOG_LEVEL": "WARNING"
      }
    }
  }
}

MCP 工具

get_symbol

获取指定名称的符号（函数/类/方法）的完整源码。

参数:

• name (必填): 符号名称
• file (可选): 限定文件范围
• kind (可选): 符号类型（function/method/class）

示例:

get_symbol(name="parseUserToken")
get_symbol(name="handleLogin", file="auth.py")

search_code

根据查询搜索符号（全文搜索）。

参数:

• query (必填): 搜索查询字符串
• limit (可选): 返回结果数量，默认 10
• lang (可选): 限定语言类型

示例:

search_code(query="用户认证")
search_code(query="parse", limit=20, lang="python")

get_callers

获取调用指定符号的所有上层函数（调用者）。

参数:

• symbol_name (必填): 符号名称
• depth (可选): 查询深度，默认 1

示例:

get_callers(symbol_name="validateToken", depth=2)

get_callees

获取指定符号调用的所有下层函数（被调用函数）。

参数:

• symbol_name (必填): 符号名称
• depth (可选): 查询深度，默认 1

示例:

get_callees(symbol_name="handleRequest", depth=2)

get_context_window

获取符号的完整上下文窗口，包含调用者和被调用者。

参数:

• symbol_name (必填): 符号名称
• depth (可选): 查询深度，默认 1

示例:

get_context_window(symbol_name="processData", depth=1)

get_file_outline

获取文件内所有符号的大纲（不含函数体）。

参数:

• file_path (必填): 文件路径

示例:

get_file_outline(file_path="src/api/users.py")

list_symbols

根据条件筛选符号列表。

参数:

• kind (可选): 符号类型（function/method/class）
• lang (可选): 语言类型
• file (可选): 文件路径

示例:

list_symbols(kind="function", lang="python")
list_symbols(file="auth.py")

index_status

获取当前索引状态和统计信息。

示例:

index_status()

CLI 命令

ce index

对指定仓库执行全量索引。

ce index /path/to/repo

ce status

显示当前索引状态和统计信息。

ce status

ce watch

启动文件监听，自动增量更新。

ce watch /path/to/repo

ce query

命令行直接查询符号（调试用）。

ce query "parseUserToken"

ce search

全文搜索符号。

ce search "用户认证逻辑"

ce reindex

强制重建全量索引。

ce reindex --force

ce serve

以 MCP Server 模式启动。

ce serve

配置选项

环境变量	默认值	说明
CE_DB_PATH	~/.context-engine/{repo_hash}.db	SQLite 数据库文件路径
CE_REPO_ROOT	当前工作目录	索引的仓库根目录
CE_EXCLUDE_PATTERNS	node_modules,__pycache__,.git,dist,build	排除目录/文件模式
CE_MAX_FILE_SIZE	500000	最大文件大小（字节）
CE_PARALLEL_WORKERS	4	并行解析的线程数
CE_WATCHER_DEBOUNCE	0.5	文件变更防抖时间（秒）
CE_LOG_LEVEL	INFO	日志级别：DEBUG/INFO/WARNING/ERROR
CE_ENABLE_CACHE	true	是否启用查询缓存
CE_CACHE_SIZE	1000	缓存最大条目数
CE_JSON_LOGS	false	是否使用 JSON 格式输出日志
CE_LOG_FILE	None	日志文件路径（可选）

性能指标

指标	目标值	测量方法
全量索引（10 万行仓库）	< 30 秒	ce index + time
增量更新（单文件修改）	< 200 ms	watchdog 事件到 DB 写入完成
get_symbol 查询	< 5 ms (p99)	1000 次随机查询取 p99
search_code 全文搜索	< 30 ms (p99)	FTS5 查询基准测试
get_context_window (depth=2)	< 100 ms (p99)	递归 CTE 查询基准
DB 文件大小（10 万行仓库）	< 50 MB	du -sh *.db
内存占用（MCP Server 空闲）	< 80 MB	psutil 监控

已知限制

• 动态语言精度: Python 的动态类型导致部分间接调用无法静态分析
• 跨语言仓库: 同一函数调用跨语言暂不追踪
• 宏/装饰器: 高度宏展开的代码符号提取可能不完整
• 全文搜索质量: FTS5 基于词法匹配，中文代码注释需配合分词

开发

运行测试

pytest tests/
pytest --cov=engine --cov-report=html

性能基准测试

pytest tests/test_benchmark.py

代码风格

black engine/ server.py cli.py
flake8 engine/ server.py cli.py

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！