mcp-intelligence-context
MCP Intelligence Context
一个 Repository Intelligence MCP 服务器,它索引代码库的文件、符号、导入关系和依赖图,并将一个小而聚焦的上下文包交给 Copilot/智能体,而不是让它们扫描整个仓库。
为什么
当智能体收到一个关于大型仓库的含糊问题时,它往往得反复列出目录、打开无关文件,并在找到相关代码之前重新推导出仓库结构——既烧掉大量 token 又浪费时间。这个项目为仓库构建了一个持久化、增量更新的索引(文件、符号、导入、反向依赖),并通过 MCP 工具只返回与某个查询相关的上下文,同时带有近似 token 预算。
Related MCP server: lens
工作原理
index_repository遍历仓库(遵守.gitignore),解析 Python(通过ast)以及 JS/TS(通过轻量正则的启发式规则)中的函数/类/方法/导入/导出,并构建反向依赖图。它索引缓存在.mcp_intel_cache/index.json,并增量刷新(只根据 mtime/size 重新解析发生变化的文件)。search_code/get_relevant_context通过符号名、文件名、docstring/摘要以及导入匹配来对文件排序(词法/符号搜索——该 MVP 中没有嵌入向量),返回一个受 token 预算约束的上下文包:符号表加上小型代码片段,而不是整份文件;get_relevant_context还会给出与单跑全仓库扫描基线的token_savings对比,让省下来的次数直接显示在工具响应中。get_file_summary/get_dependencies让智能体深入查看某个文件里的符号和影响范围(importers/imports),而无需读取整个文件。如果缓存的索引早于 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这个脚本会做什么:
用
pipx安装(或更新)mcp-intelligence-context。为该工作区写入
.vscode/mcp.json。通过设置
MCP_INTEL_ALLOWED_ROOTS=${workspaceFolder}把索引限定到当前工作区文件夹。
然后,在 VS Code 里:
命令面板 ->
MCP: List Servers。启动/重启
mcp-intelligence-context。在 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 工具
工具 | 用途 |
| 为某个仓库根目录构建/刷新索引 |
| 顶层目录、语言分布、核心模块 |
| 对某条查询返回相关文件/符号命中 |
| 某个文件中符号表、导入、导出的摘要 |
| 一个文件导入了什么,以及谁导入了它 |
| 针对查询的受 token 约束的上下文包,外加一个 |
评估它是否真的有用
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 文件,以取得可脱离人工且可信的生产安装方式——mcp1.x 到 2.0 的 breaking change 已经把我们坑过一次。尚未加上自动化回归测试 这套代码本身的 Changes modified 还只能依赖手跑的
eval/和临时性的本地测试,不作 CT 门禁的测试套件。
Available Tools
6 toolsget_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
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Related MCP Servers
AlicenseNot gradedqualityDmaintenanceProvides AI coding agents with structured access to indexed codebases via semantic search, symbol analysis, and file reading tools.13Server Side Public , v 1- AlicenseNot gradedqualityCmaintenanceProvides token-efficient code retrieval for coding agents by indexing repositories and enabling ranked snippet search, symbol outlines, and surgical line reads.5 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables 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.4MIT
- FlicenseNot gradedqualityBmaintenanceProvides efficient code navigation and graph-based analysis for AI agents, enabling symbol resolution, callers, implementations, and type schemas with minimal token usage.-