FileScopeMCP

FileScopeMCP 是一个面向 AI 编程助手的代码库分析工具，核心目标是让 AI 在回答关于代码的问题时，无需读取源码即可获得准确答案。它通过监控代码、按重要性对文件排序、映射依赖关系，并在后台持续更新 AI 生成的摘要来实现这一目标。

主要能力

• 重要性排名：每个文件根据被依赖的数量、导出内容以及所在位置获得 0-10 的评分，让 LLM 优先看到关键文件。
• 依赖映射：支持所有受支持语言的双向导入跟踪。对 TypeScript/JavaScript、Python、C、C++、Rust 使用 AST 级提取（tree-sitter）；对 Go、Ruby、Lua、Zig、PHP、C#、Java 使用基于正则的提取。同时能发现循环依赖。
• 符号智能：通过 tree-sitter 为 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 仪表盘：位于 localhost:1234 的 Web UI，可跨所有仓库可视化探索代码库，包括交互式依赖图、文件详情面板、实时代理活动和每个仓库的健康监控。

使用方式

环境要求

• Node.js >= 22 和 npm
• 原生模块（better-sqlite3、tree-sitter）的构建工具：
  • Linux：sudo apt install build-essential python3
  • macOS：xcode-select --install
  • Windows：安装带 C++ 工作负载的 Visual Studio Build Tools

安装与注册

运行 ./build.sh 会通过 claude mcp add --scope user 全局注册 FileScopeMCP（幂等；可用 npm run register-mcp 重新运行）。如果缺少 claude CLI，构建仍会成功——其他 MCP 客户端参见 docs/mcp-clients.md。

在任何项目中打开 Claude Code 会话，FileScopeMCP 会自动初始化，MCP 工具自动出现，AI 可在对话中直接调用。

其他集成

• Agent 运行时（Hermes、Codex、OpenClaw）：通过仓库的 AGENTS.md 发现 FileScopeMCP，其中包含 MCP 注册配置、代理/LLM 设置以及指向 skills/filescope-mcp/SKILL.md 的便携技能文件。Hermes 可添加到 ~/.hermes/config.yaml。
• 已有本地 LLM：编辑 ~/.filescope/broker.json 并将 baseURL 设置为 LLM 端点即可复用。
• LLM 摘要（可选）：运行 ./setup-llm.sh 获取平台特定的 llama-server 设置指南。Linux 上还可 sudo ./setup-llm.sh --install-service 将 llama-server 注册为 systemd 单元。没有 llama-server 时，文件跟踪、依赖、符号、调用图仍可工作，只是没有 LLM 生成的摘要。

数据存储

每个项目的数据存放在 .filescope/data.db（SQLite，WAL 模式）。代理通过 Unix 套接字 ~/.filescope/broker.sock 协调所有仓库的 LLM 工作。

多仓库监视器（仅 Linux systemd）

对于希望 ~/.filescope/nexus.json 中所有仓库持续被监视的用户，可安装每仓库监视器用户单元。该单元启动 scripts/watchers.mjs，为每个注册仓库生成一个 dist/mcp-server.js --base-dir=<repo> 子进程并监督它们（退出自动重启、SIGTERM 干净关闭）。日志位于 ~/.filescope/watchers.log 和 ~/.filescope/watcher-logs/*.log。

适用场景

• 让 AI 编程助手快速理解大型或陌生代码库
• 重构前分析函数调用关系
• 可视化探索多仓库依赖结构
• 在本地 GPU 上运行 LLM 摘要生成

限制

• 需要 Node.js >= 22 和原生模块构建工具
• LLM 摘要功能需要 llama-server 或兼容 OpenAI 的 API
• 多仓库监视器仅支持 Linux systemd
• 部分语言（Go、Ruby、Lua、Zig、PHP、C#、Java）的依赖提取基于正则而非 AST
• 符号提取仅支持 TypeScript、JavaScript、Python、Go、Ruby
• 调用图映射仅支持 TS/JS
• 版权归 admica 所有，具体许可条款见 LICENSE