MCP Intelligence Context

一个 Repository Intelligence MCP 服务器，它索引代码库的文件、符号、导入关系和依赖图，并将一个小而聚焦的上下文包交给 Copilot/智能体，而不是让它们扫描整个仓库。

为什么

当智能体收到一个关于大型仓库的含糊问题时，它往往得反复列出目录、打开无关文件，并在找到相关代码之前重新推导出仓库结构——既烧掉大量 token 又浪费时间。这个项目为仓库构建了一个持久化、增量更新的索引（文件、符号、导入、反向依赖），并通过 MCP 工具只返回与某个查询相关的上下文，同时带有近似 token 预算。

Related MCP server: lens

工作原理

1. index_repository 遍历仓库（遵守 .gitignore），解析 Python（通过 ast）以及 JS/TS（通过轻量正则的启发式规则）中的函数/类/方法/导入/导出，并构建反向依赖图。它索引缓存在 .mcp_intel_cache/index.json，并增量刷新（只根据 mtime/size 重新解析发生变化的文件）。

2. search_code / get_relevant_context 通过符号名、文件名、docstring/摘要以及导入匹配来对文件排序（词法/符号搜索——该 MVP 中没有嵌入向量），返回一个受 token 预算约束的上下文包：符号表加上小型代码片段，而不是整份文件；get_relevant_context 还会给出与单跑全仓库扫描基线的 token_savings 对比，让省下来的次数直接显示在工具响应中。

3. get_file_summary / get_dependencies 让智能体深入查看某个文件里的符号和影响范围（importers/imports），而无需读取整个文件。

4. 如果缓存的索引早于 5 分钟 且没有活着的（live）监听器，工具会报告陈旧警告。在现实中，对某个仓库的第一次调用会通过 watchdog 启动后台文件 watcher，立即把 create/modify/delete 事件应用到内存索引，让索引在代码变更时保持跟随更新——因此一个会话中无需手动再索引。磁盘上的索引在防抖（约 2 秒）之后才落盘，因此快速保存不会被击键一次就写盘。

仓库结构

src/mcp_intelligence_context/   Python MCP server package
  walker.py                     gitignore-aware file walker
  parsers/                      Python (ast) and JS/TS (regex) symbol extraction
  indexer.py                    builds/caches the RepoIndex, resolves imports
  watcher.py                    background file watcher that keeps the index live
  search.py                     lexical/symbol search + reverse-dep lookups
  context_builder.py            token-budgeted context package assembly
  server.py                     MCP tool definitions (stdio server)
vscode-extension/                VS Code extension wrapper (setup/reindex/status commands)
scripts/                         one-command bootstrap for new users

快速开始（新用户）

如果你是 MCP 新手，只想在 VS Code 里快速跑起来：

git clone https://github.com/LeoChimal09/MCP-INTELLIGENCE-CONTEXT.git
cd MCP-INTELLIGENCE-CONTEXT
bash scripts/setup_mcp_workspace.sh

这个脚本会做什么：

1. 用 pipx 安装（或更新）mcp-intelligence-context。

2. 为该工作区写入 .vscode/mcp.json。

3. 通过设置 MCP_INTEL_ALLOWED_ROOTS=${workspaceFolder} 把索引限定到当前工作区文件夹。

然后，在 VS Code 里：

1. 命令面板 -> MCP: List Servers。

2. 启动/重启 mcp-intelligence-context。

3. 在 Copilot Chat 的工具选择器中启用 mcp-intelligence-context。

如果脚本提示缺少 pipx，请先一次性安装：

brew install pipx
pipx ensurepath

独立运行 MCP 服务器

python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/mcp-intelligence-context        # or: python -m mcp_intelligence_context.server

输入要索引的仓库：通过设置 MCP_INTEL_REPO_ROOT，或对任何工具调用显式传入 repo_root（默认是服务器当前工作目录）。

不用克隆本仓库即可安装

其他用户并不需要本地 checkout——直接从 git 仓库安装（等它发布到 PyPI 后也可以）：

python3 -m venv .venv
.venv/bin/pip install "git+https://github.com/LeoChimal09/MCP-INTELLIGENCE-CONTEXT.git"
# once published: .venv/bin/pip install mcp-intelligence-context

无论是哪种方式，mcp-intelligence-context 的命令行入口脚本和 MCP_INTEL_REPO_ROOT 环境变量都完全一样——只有 pip install 的来源不同。

注册到某个 MCP 客户端（例如 VS Code）

在目标工作区里把下面这段加入 .vscode/mcp.json：

{
  "servers": {
    "mcp-intelligence-context": {
      "type": "stdio",
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "mcp_intelligence_context.server"],
      "env": { "MCP_INTEL_REPO_ROOT": "${workspaceFolder}" }
    }
  }
}

VS Code 扩展

vscode-extension/ 打包了一个薄封装，里面提供三个命令：

• MCP Intelligence: Setup Server —— 创建一个 venv 并安装 Python 包，然后写入前面提到的 .vscode/mcp.json 条目。

• MCP Intelligence: Reindex Repository —— 强制重建当前打开工作区的索引。

• MCP Intelligence: Show Status —— 打印缓存索引的文件数、git 提交和索引年龄。

默认情况下，“Setup Server” 会从该项目的 git 仓库安装到扩展的私有存储里的一个 venv 中——不需要本地克隆。控制它有两个设置：

• mcpIntelligenceContext.serverPath —— 指向一个本地 editable checkout（在这个 monorepo 上开发时用）；否则保持为空。

• mcpIntelligenceContext.pythonPackageSource —— 当 serverPath 为空时，覆盖 pip install 的目标（例如一个 PyPI 包名）。

要构建它，请执行：

cd vscode-extension
npm install
npm run compile

然后在 VS Code 里按 F5（打开 vscode-extension/）启动一个扩展开发宿主（Extension Development Host）。

可用的 MCP 工具

评估它是否真的有用

eval/ 里包含了一个小型的、如实的基准，就是对本仓库自身代码去测（没有 LLM 调用、没有捏造数字）：10 个手写的、带有已知 ground truth 的查询，把它和朴素基线（列出目录树、grep、读取整个命中的文件）对比。

.venv/bin/python eval/run_eval.py

它汇报 hit@1/hit@5（得出的最靠前结果是否有指向对的文件）、token 节省的平均值、以及时延。这只能衡量检索/token 机制的效率——并不测量真实 Copilot 答案到底有没有更好，因为那必须去调用真实的模型。

当前（MVP）局限

• JS/TS 解析是基于正则的（并不是完整 AST），因此某些不规则语法可能会漏掉。虽然 Python 用的标准 ast 模块已经比较准。

• 搜索本身只基于词汇/符号（带停用词过滤、并累积多个信号打分），目前还没有嵌入向量/语义搜索。

• 文件 watcher 虽然实时更新单个文件，但不重新遍历 .gitignore 自身变化——如果编辑的是 .gitignore，请手动用 refresh=true 调用一次 index_repository，让新规则生效。

除了更广泛/生产使用前安全考虑

已修：

• Shell 注入 —— 早期版本的 VS Code 扩展会把工作区设置直接嵌入 shell 命令的字符串里；现在改用参数数组的 execFile（不开 shell），并拒绝在不可信的工作区运行 “Setup Server”。

• 符号链接逃逸 —— 遍历逻辑会跳过解析出仓库根目录的符号链接（防止埋一条符号链接来暴露如 /etc/passwd）。

• 敏感信息泄漏 —— 匹配常见凭据的文件名（如 .env、*.pem、id_rsa、credentials.json，见 config.py 里的 SENSITIVE_FILENAME_PATTERNS）即使没有被 .gitignore 也会跳过，从而避免内容流露给上层调用者。

• 坏缓存导致工具崩溃 —— 现在当缓存 .mcp_intel_cache/index.json 损坏/被篡改时只会触发一次完全重建，而不是让服务在启动时崩溃。

• ReDoS —— JS/TS 的正则解析会跳过异常长的单行（比如 minified），避免灾难性的回溯造成 DoS。

• 不受约束的 repo_root —— 设置 MCP_INTEL_ALLOWED_ROOTS（一个 :分隔的绝对路径列表）来限制服务器能索引哪些目录；默认不设置，以便保留原有灵活的单用户行为。

架构性尚未解决的问题，在小范围 single local user 以外部署前请认真了解：

• 不适合当成共享/多租户的网络服务。 这个设计的定位是本地的、每用户一进程的 stdio 服务器。索引和监听的内存缓存没有做按用户隔离或校验。不要把它开放成共享的 HTTP/SSE 端点，除非底层还加了一套完整的调用方沙箱和认证。

• 依赖没有在上游 pin 版本（都只有 >=），建议再手工钉死精确版本，或换用 lock 文件，以取得可脱离人工且可信的生产安装方式——mcp 1.x 到 2.0 的 breaking change 已经把我们坑过一次。

• 尚未加上自动化回归测试 这套代码本身的 Changes modified 还只能依赖手跑的 eval/ 和临时性的本地测试，不作 CT 门禁的测试套件。