Skip to main content
Glama
mcp-intelligence-context

mcp-intelligence-context

by LeoChimal09

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 工具

工具

用途

index_repository

为某个仓库根目录构建/刷新索引

get_repo_overview

顶层目录、语言分布、核心模块

search_code

对某条查询返回相关文件/符号命中

get_file_summary

某个文件中符号表、导入、导出的摘要

get_dependencies

一个文件导入了什么,以及谁导入了它

get_relevant_context

针对查询的受 token 约束的上下文包,外加一个 token_savings 对比,虚构一个朴素的全仓库扫描基线

评估它是否真的有用

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 门禁的测试套件。

Available Tools

6 tools
get_dependenciesA

Return what a file imports and which files import it (reverse deps), to understand blast radius before changing a file.

Inputs: path (required), repo_root.

get_file_summaryB

Return the symbol table (functions/classes/methods with signatures and docstrings), imports, and exports for a single indexed file — without returning the entire file body.

Inputs: path (required), repo_root.

get_relevant_contextA

Build a focused, token-budgeted context package (symbol tables + small code excerpts) for the files most relevant to a query. This is the main entry point for "help me find/fix X" style requests — use it instead of reading whole files or globbing the repo.

Inputs: query (required), repo_root, token_budget.

get_repo_overviewA

Return a high-level architecture summary: top-level directories, language breakdown, and the files with the most symbols (likely core modules). Use this to orient before drilling into specific files.

Inputs: repo_root.

index_repositoryA

Index (or re-index) a repository: extracts files, symbols, imports and a reverse dependency graph. Call this first, and again with refresh=true after significant file changes. Uses an on-disk cache for fast re-runs.

Inputs: refresh, repo_root.

search_codeA

Search the indexed repository for files/symbols relevant to a natural language or keyword query (e.g. "authentication middleware", "parseConfig"). Returns ranked file hits with the matching symbol/reason — much cheaper than scanning the whole repo.

Inputs: query (required), top_k, repo_root.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 6 tools

    Disambiguation4/5

    Each tool has a largely distinct purpose (index, overview, search, file details, dependencies, context), and the descriptive text flags get_relevant_context as the main entry point. However, search_code and get_relevant_context could both serve as the starting point for a 'find X' request, creating minor selection ambiguity.

    Naming Consistency5/5

    All tools follow a consistent verb_noun snake_case pattern (index_, get_, search_), making the API predictable and scannable. The only minor nitpick is abbreviating 'repository' as 'repo' in get_repo_overview, but this does not affect the overall pattern.

    Tool Count5/5

    Six tools sit at the sweet spot for a code-intelligence server, each earning its place in the index-query workflow. The set covers setup, orientation, discovery, drill-down, and impact analysis without bloat.

    Completeness4/5

    The core indexing-to-context pipeline is well covered, including re-indexing via refresh and reverse-dependency analysis for safe edits. Minor gaps exist (no full-file body reader, no way to list indexed repositories or explicitly purge the cache), but these seem like intentional scope decisions for a token-budget-focused tool.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI coding agents with structured access to indexed codebases via semantic search, symbol analysis, and file reading tools.
      13
      Server Side Public , v 1
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides token-efficient code retrieval for coding agents by indexing repositories and enabling ranked snippet search, symbol outlines, and surgical line reads.
      5 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables LLM agents to efficiently understand and navigate a codebase by providing semantic search over symbols and a reference graph, replacing expensive grep/glob calls with structured tools like definition lookup, caller/callee queries, and change-impact analysis.
      4
      MIT