文件范围MCP
你的AI已经知道如何编码了。现在它知道你的代码库了。
 ](https://nodejs.org/)  
FileScopeMCP监视您的代码，按重要性对每个文件进行排名，映射所有依赖关系，并在后台保持AI生成的摘要的新鲜度。当你的LLM问“这个文件做什么？”时，它会在不读取源代码的情况下得到一个真实的答案。
适用于 克劳德代码, 赫尔墨斯代理, 法典, 龙虾, 光标AI，或作为独立的守护进程。支持TypeScript、JavaScript、Python、C、C++、Rust、Go、Ruby、Lua、Zig、PHP、C#和Java。
主要特点
重要性排名 --每个文件根据依赖它的东西的数量、导出的内容以及存放的位置得分为0-10。LLM首先看到关键文件。
依赖关系映射 --跨所有支持语言的双向导入跟踪。用于TS/JS、Python、C、C++和Rust的AST级提取（树形图）；基于正则表达式的Go、Ruby、Lua、Zig、PHP、C#和Java。也发现循环依赖关系。
符号智能 --通过TypeScript、JavaScript、Python、Go和Ruby的树形图提取函数、类、接口、类型、枚举、常量、模块和结构。 find_symbol 将名称解析为文件+行范围。 find_callers 和 find_callees 映射TS/JS的调用图，这样你的AI就可以在重构之前回答“谁调用这个函数？”。
永远新鲜 --文件观察器+语义变化检测意味着元数据会自动更新。TS/JS的AST级别差异，其他所有内容的LLM驱动分析。只是重新处理实际发生的变化。
LLM经纪人 -后台进程通过llama.cpp的llama-server（或任何与OpenAI兼容的HTTP API）协调所有AI工作。优先级队列确保交互式查询优于后台处理。在单个GPU上运行。
Nexus仪表板 --web UI位于 localhost:1234 这使您可以在所有存储库中直观地探索代码库。交互式依赖关系图、文件详细信息面板、实时代理活动和每个仓库的健康监控。
先决条件
- Node.js>=22 和npm(下载)
- 构建工具 对于本机模块(
better-sqlite3,tree-sitter):
- Linux： sudo apt install build-essential python3 - macOS： xcode-select --install - Windows:带C++工作负载的Visual Studio构建工具
快速开始
git clone https://github.com/admica/FileScopeMCP.git
cd FileScopeMCP
./build.sh # installs deps, compiles, registers with Claude Code./build.sh 通过全局注册FileScopeMCP claude mcp add --scope user （幂等；重新运行 npm run register-mcp).如果 claude 缺少CLI，构建仍然成功--请参阅 docs/mcp-clients.md 对于其他MCP客户端。
在任何项目中打开Claude Code会话，FileScopeMCP会自动初始化。MCP工具会自动出现——你的AI可以在对话中直接调用它们：
find_important_files(limit: 5)
status()建议安装Claude Code
用于添加项目启动的更丰富的安装 CLAUDE.md 并指向可选的钩子模板：
npm run install-claude-code # or: npx filescope-install --claude-code该命令是分层的，没有侵入性——它从不自动写入您的 .claude/settings.json.钩子模板记录在 docs/claude-code-hooks.md；如果需要，可以将它们粘贴到您的设置中。这 CLAUDE.md 底漆被包裹在 ` / ` 标记，以便在不接触周围内容的情况下干净地添加、替换或删除。看 ROADMAP.md 设计原理的第一阶段。
代理运行库（Hermes、Codex、OpenClaw）
代理运行时通过仓库发现FileScopeMCP AGENTS.md，其中包括MCP注册配置、代理/LLM设置以及指向可移植技能文件的指针 skills/filescope-mcp/SKILL.md.
赫尔墨斯 --添加到 ~/.hermes/config.yaml:
mcp_servers:
filescope:
command: "node"
args: ["/path/to/FileScopeMCP/dist/mcp-server.js"]
timeout: 120已经有一个本地LLM在运行？ 指向经纪人--编辑 ~/.filescope/broker.json 并设置 baseURL 到达法学硕士的终点。看 AGENTS.md 了解详情。
法学硕士摘要（可选）
跑 ./setup-llm.sh 有关设置llama.cpp的平台特定指南 llama-server --看 docs/llm-setup.md 了解详情。在Linux上，你也可以 sudo ./setup-llm.sh --install-service 将llama服务器注册为systemd单元（将流记录到journalctl，OOM保护，启动时自动重启）。由于llama服务器在WSL2的Windows主机上运行，因此该标志在WSL2下为禁止操作。如果没有llama服务器，其他一切仍然可以工作（文件跟踪、依赖关系、符号、调用图——只是没有LLM生成的摘要）。如果您的代理运行时已经有一个本地LLM，请配置代理以重用它。
添加到您的项目 .gitignore:
.filescope/
.filescope-daemon.logLLM监控（可选）
如果llama服务器在本地运行，可选的VictoriaMetrics+vmui堆栈为您提供了一个用于VRAM、RAM、交换、吞吐量和累积工作的单窗格仪表板。总驻留占用空间约为120 MB，通过systemd cgroups限制，因此行为不端的导出器无法OOM杀死llama服务器。
sudo ./monitoring/install.sh浏览仪表板 http://:8881/vmui/#/dashboards。参见 监测/ 用于布局和卸载脚本。
MCP工具
| 工具 | 它做什么 |
|---|---|
status | 代理连接、队列深度、LLM进度、观察者状态 |
find_important_files | 按重要性得分和依赖性计数列出的顶级文件 |
get_file_summary | 关于文件的一切：摘要、概念、变更影响、导出、deps、过期 |
list_files | 完整文件树（无参数）或按重要性排列的平顶N（带 maxItems) |
find_symbol | 将符号名称解析为文件+行范围；支持通过尾随进行前缀匹配 * |
find_callers | 查找所有调用命名符号的符号（TS/JS调用图） |
find_callees | 查找命名符号调用的所有符号（TS/JS调用图） |
search | 跨符号、摘要、目的和路径搜索文件元数据 |
list_changed_since | 自时间戳或git SHA以来更改的文件 |
get_communities | Louvain通过导入耦合对文件组进行集群 |
detect_cycles | 查找循环依赖链 |
get_cycles_for_file | 涉及特定文件的循环 |
scan_all | 通过代理对LLM摘要文件进行排队 |
set_base_directory | 指向另一个项目 |
set_file_summary | 手动设置或覆盖文件的LLM摘要 |
set_file_importance | 手动设置文件的重要性分数（0-10） |
exclude_and_remove | 从跟踪中删除文件/模式（破坏性） |
Nexus仪表板
npm run build:nexus # one-time build (API + UI)
npm run nexus # starts at http://localhost:1234一个只读的web仪表板，连接到您计算机上的每个FileScopeMCP仓库：
- 项目视图 --带有重要性、热颜色和过期指示器的文件树，单击任何文件以获取完整的元数据
- 依赖图 --交互式Cytoscape.js可视化，按目录过滤，点击节点进行检查
- 系统视图 --实时代理状态、每个回购令牌的使用情况、流媒体活动日志
- 设置 --管理出现的存储库，从黑名单中删除或还原
通过扫描以下内容自动发现存储库 .filescope/data.db 目录。无需配置。
多回购观察程序（仅限Linux系统）
对于希望每个repo都在 ~/.filescope/nexus.json 持续监视——不仅在MCP客户端打开时——安装per-report监视器用户单元：
./scripts/nexus.sh install-watchers # writes the unit, enables it, starts it
systemctl --user status filescope-watchers.service
./scripts/nexus.sh uninstall-watchers # symmetric removal机组启动 scripts/watchers.mjs，这会产生一个 dist/mcp-server.js --base-dir= 每个注册的仓库都有一个子仓库，并对其进行监督（退出时自动重启，SIGTERM干净关闭）。单元 Requires=filescope-broker.service --自行安装代理用户单元；此命令不发送一个。
日志： ~/.filescope/watchers.log （主管）和 ~/.filescope/watcher-logs/*.log （每个回购子公司）。
运作原理
Your code changes
→ file watcher picks it up
→ AST diff classifies the change (exports? types? body only?)
→ symbols extracted (functions, classes, types, etc.)
→ call-site edges resolved (TS/JS: who calls what)
→ importance scores recalculated
→ staleness cascades to dependents (only if exports/types changed)
→ LLM broker regenerates summaries, concepts, change impact
→ your AI's next query gets fresh answers万物皆有生命 .filescope/data.db （SQLite，WAL模式）每个项目。代理通过Unix套接字在您的所有存储库中协调LLM工作 ~/.filescope/broker.sock.
文档
| 医生 | 里面有什么 |
|---|---|
| 代理商.md | 跨代理上下文文件——MCP注册、代理配置、架构（由Hermes、Codex、OpenClaw阅读） |
| FileScopeMCP技能 | 可移植技能文件——工具参考、工作流程、使用FileScopeMCP的代理提示 |
| LLM设置 | llama.cp/llama服务器安装——Linux/MOS本机（默认）、WSL2+Windows或远程局域网 |
| 配置 | 按项目配置、代理配置、忽略模式 |
| MCP 客户端 | Claude代码、Cursor AI、守护进程模式的设置 |
| 故障排除 | 常见问题和修复 |
| 内部机制 | 依赖性检测、重要性公式、符号提取、调用站点边缘、存储 |
| LLM监控 | 本地骆驼服务器的可选VictoriaMetrics+vmui仪表板 |
许可证
版权所有（c）2026 admica。保留所有权利。看 许可证.