Code Intelligence MCP Server

为 AI 编程助手提供智能代码分析和上下文检索的 Model Context Protocol (MCP) 服务器。

English | 简体中文

这是什么？

Code Intelligence MCP Server 通过以下功能增强 AI 编程助手对代码库的理解：

• 语义搜索：通过含义而非关键词查找代码
• Graph-RAG：使用知识图谱的上下文感知代码检索
• 调用链分析：追踪函数依赖和影响
• 智能上下文：自动向 AI 对话注入相关代码片段

完美适配 Claude Code、Cline 或任何兼容 MCP 的 AI 助手。

快速开始

安装

通过 npm（推荐）：

npm install -g @ozbombor/code-intelligence-mcp

通过 git：

git clone https://github.com/Darkbluelr/code-intelligence-mcp.git
cd code-intelligence-mcp
./install.sh

系统要求

• Node.js >= 18.0.0
• Bash shell
• ripgrep（可选，用于更快的搜索）
• jq（可选，用于 JSON 处理）

使用方式

作为 MCP 服务器（推荐）：

添加到 MCP 客户端配置：

{
  "mcpServers": {
    "code-intelligence": {
      "command": "code-intelligence-mcp",
      "args": []
    }
  }
}

命令行：

ci-search "查找认证代码"
ci index build
ci index status --workspace demo-zod
ci-search --help

核心功能

语义代码搜索

# 自然语言查询
ci-search "用户认证是如何工作的"

Graph-RAG 上下文检索

# 获取相关上下文并智能裁剪
ci_graph_rag --query "修复登录 bug" --budget 8000

调用链追踪

# 追踪函数依赖
ci_call_chain --symbol "handleLogin" --depth 3

影响分析

# 分析变更影响
ci_impact --file "src/auth.ts"

Bug 定位

# 智能 bug 定位器
ci_bug_locate --error "TypeError: Cannot read property 'user'"

可用的 MCP 工具

| 工具 | 描述 | |------|------| | ci_search | 基于 embedding 的语义代码搜索 | | ci_graph_rag | 基于图的上下文检索 | | ci_call_chain | 函数调用链追踪 | | ci_bug_locate | 智能 bug 定位 | | ci_complexity | 代码复杂度分析 | | ci_hotspot | 高频修改文件检测 | | ci_impact | 传递影响分析 | | ci_arch_check | 架构规则验证 | | ci_vuln | 漏洞扫描 | | ci_index | 索引管理（支持工作区：status/build/clean/rebuild） |

查看全部 20+ 工具 →

说明：ci_index_status 仅为兼容保留，建议使用 ci_index。

配置

工作区与索引配置（ci-config.yaml）

ci-config.yaml 是工作区与索引的唯一入口，支持多项目与索引隔离：

version: 1.0

global:
  index_dir: .ci-index
  respect_gitignore: true
  global_exclude:
    - "**/node_modules/**"
    - "**/.git/**"
    - "**/dist/**"
    - "**/build/**"

default_workspace:
  name: main
  root: .
  include:
    - "src/**"
    - "packages/**"
  exclude:
    - "**/*.d.ts"

workspaces:
  - name: demo-zod
    root: demo/zod
    respect_gitignore: false
    include:
      - "packages/zod/src/**"
      - "packages/zod/tests/**"

imports:
  boundaries: config/boundaries.yaml
  features: config/features.yaml
  llm_providers: config/llm-providers.yaml

工作区使用示例：

# MCP 工具
ci_index action=build workspace=demo-zod
ci_search query="schema parse" workspace=demo-zod

# CLI
ci index build --workspace demo-zod
ci-search "schema parse" --workspace demo-zod

Embedding 提供商

服务器支持多个 embedding 提供商,并具有自动降级功能:

三级降级策略:

1. Ollama(本地,免费)→ 优先使用,无网络延迟,隐私安全
2. OpenAI API(云端,付费)→ Ollama 不可用时自动降级
3. 关键词搜索 → 无 embedding 服务时的最终降级方案

方案 1: Ollama(推荐本地使用)

安装:

# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 拉取 embedding 模型
ollama pull nomic-embed-text

配置:

# .devbooks/config.yaml（embedding 兼容配置）
embedding:
  provider: ollama  # 或使用 'auto' 自动检测
  ollama:
    model: nomic-embed-text
    endpoint: http://localhost:11434
    timeout: 30

使用:

# 构建 embedding 索引
ci index build

# 使用 Ollama 搜索
ci-search "认证代码"

方案 2: OpenAI API(云端)

设置:

# 设置 API 密钥
export OPENAI_API_KEY="sk-..."

配置:

# .devbooks/config.yaml（embedding 兼容配置）
embedding:
  provider: openai
  openai:
    model: text-embedding-3-small
    api_key: ${OPENAI_API_KEY}  # 或直接设置
    base_url: https://api.openai.com/v1
    timeout: 30

使用:

# 使用 OpenAI 构建索引
ci index build

# 或强制使用 OpenAI 进行单次搜索
ci-search "用户认证" --provider openai

方案 3: 关键词搜索(无需设置)

关键词搜索开箱即用,无需任何配置:

# 强制使用关键词搜索
ci-search "错误处理" --provider keyword

高级配置

自动 Provider 检测:

# .devbooks/config.yaml（embedding 兼容配置）
embedding:
  provider: auto  # 尝试 Ollama → OpenAI → 关键词
  fallback_to_keyword: true
  auto_build: true

命令行覆盖:

# 为单次搜索覆盖 provider
ci-search "测试" --provider ollama --ollama-model mxbai-embed-large

# JSON 输出与自定义设置
ci-search "支付" --format json --top-k 10 --threshold 0.7

环境变量:

• OPENAI_API_KEY - OpenAI API 密钥
• EMBEDDING_API_KEY - 通用 embedding API 密钥
• PROJECT_ROOT - 项目根目录

重要：Workspace 参数

在多工作区项目中使用 MCP 工具时，务必指定 workspace 参数：

# MCP 工具使用 - 正确
ci_search query="认证代码" workspace=demo-typescript

# MCP 工具使用 - 错误（使用默认的 'main' 工作区）
ci_search query="认证代码"

为什么这很重要：

• 每个工作区都有自己的 embedding 索引
• 使用错误的工作区会导致搜索结果为空或不正确
• 默认的 main 工作区可能不包含你要查找的文件

故障排除： 如果 ci_search 降级到关键词搜索或返回空结果：

1. 检查是否指定了正确的 workspace 参数
2. 验证工作区索引是否存在：ci_index action=status workspace=<name>
3. 如果需要，构建索引：ci_index action=build workspace=<name>
4. 确保 ollama 正在运行：curl http://localhost:11434/api/tags

可选功能

所有功能都支持优雅降级：

• 没有 embeddings？回退到关键词搜索
• 没有 SCIP 索引？使用正则解析
• 没有外部工具？核心功能仍然可用

文档

高级用法请参考本地文档：

• 完整工具参考和示例
• 架构和系统设计
• 性能调优指南
• 故障排除技巧

运行 ./install.sh 以访问完整本地文档。

示例

自动上下文注入

启用 Claude Code 的自动上下文注入：

ci-setup-hook

这会安装一个 hook，在你与 Claude 交互时自动注入相关的代码上下文，让 AI 助手无需手动查询就能了解你的代码库。

自定义查询

# 指定搜索模式
ci-search "用户服务" --mode semantic --limit 5

# 追踪调用链
ci_call_chain --symbol "processPayment" --direction both

# 检查架构
ci_arch_check --path src/

演示套件

运行完整的演示并进行 A/B 对比：

# 运行快速对比演示
bash demo/00-quick-compare.sh

# 运行所有演示
bash demo/run-suite.sh

# 对比版本（如果可用）
bash demo/compare.sh baseline.json current.json

演示套件展示：

• 自动上下文注入 vs 手动查询
• 语义搜索和 Graph-RAG 能力
• 性能基准测试和指标
• 不同配置之间的 A/B 对比

性能

以下指标由 python3 benchmarks/run_benchmarks.py 生成的 benchmark_result.json 自动更新。 执行 python3 benchmarks/update_readme.py 可刷新本段内容。

更新时间：2026-01-24T06:27:38+00:00

| 指标 | 数值 | 备注 | | --- | --- | --- | | 语义搜索 P95 延迟 | 222 ms | iterations=3 | | Graph-RAG 冷启动 P95 延迟 | 862.64 ms | iterations=3 | | Graph-RAG 热启动 P95 延迟 | 69.37 ms | iterations=3 | | Graph-RAG 提速 | 91.96 % | cold vs warm | | 检索质量 MRR@10 | 0.4264 | dataset=self, queries=12 | | 检索质量 Recall@10 | 1.0 | dataset=self, queries=12 | | 检索质量 Precision@10 | 0.3377 | dataset=self, queries=12 | | 检索 P95 延迟 | 6.10 ms | dataset=self, queries=12 | | 缓存命中 P95 延迟 | 75 ms | iterations=20 | | 完整查询 P95 延迟 | 89 ms | iterations=20 | | 预提交暂存 P95 | 35 ms | iterations=20 | | 预提交依赖 P95 | 27 ms | iterations=20 | | 压缩延迟 | 8.95 ms | iterations=1 |

贡献

欢迎贡献！请先阅读 CONTRIBUTING.md。

许可证

MIT License - 详见 LICENSE 文件。

致谢

构建于：Model Context Protocol、tree-sitter、SCIP

需要帮助？请在你的仓库提交 issue 或查看 docs/TECHNICAL.md。