FileScopeMCP（模型上下文协议）服务器
✨ 立即了解并可视化您的代码库结构和依赖关系！✨
基于 TypeScript 的工具，用于按重要性对代码库中的文件进行排序、跟踪依赖关系并提供摘要以帮助理解代码结构。
概述
此 MCP 服务器会分析您的代码库，根据依赖关系识别最重要的文件。它会为每个文件生成重要性分数 (0-10)，跟踪双向依赖关系，并允许您为文件添加自定义摘要。所有这些信息都通过 Cursor 的模型上下文协议提供给 AI 工具。
特征
🚀增强你的代码理解能力！ FileScopeMCP 直接向你的 AI 助手提供洞察：
- 🎯 文件重要性分析
- 根据文件在代码库中的作用，按 0-10 的等级对文件进行排名。
- 使用传入/传出依赖关系计算重要性。
- 立即查明项目中最重要的文件。
- 智能计算考虑文件类型、位置和名称意义。
- 🔗 依赖跟踪
- 映射文件之间的双向依赖关系。
- 确定哪些文件导入给定文件（从属文件）。
- 查看给定文件导入了哪些文件（依赖项）。
- 区分本地依赖和包依赖。
- 多语言支持：Python、JavaScript、TypeScript、C/C++、Rust、Lua、Zig。
- 📊 可视化
- 生成美人鱼图来可视化文件关系。
- 根据重要性分数进行颜色编码的可视化。
- 支持依赖图、目录树或混合视图。
- 带有嵌入式渲染的 HTML 输出，包括主题切换和响应式设计。
- 自定义图表深度、按重要性过滤并调整布局选项。
- 📝 文件摘要
- 向任何文件添加人工或人工智能生成的摘要。
- 检索存储的摘要以快速掌握文件用途。
- 摘要在服务器重启后仍然存在。
- 📚 多项目支持
- 为不同的项目区域创建和管理多个文件树。
- 使用不同的基目录配置单独的树。
- 轻松在不同的文件树之间切换。
- 缓存树以便更快地进行后续操作。
- 💾 持久存储
- 所有数据以 JSON 格式自动保存到磁盘。
- 无需重新扫描文件系统即可加载现有文件树。
- 跟踪文件树的最后更新时间。
安装
- 克隆此存储库
- 构建项目：构建脚本将安装所有节点依赖项并为您生成 mcp.json。视窗：将生成的 mcp.json 配置复制到项目的
.cursor目录：{
"mcpServers": {
"FileScopeMCP": {
"command": "node",
"args": ["<build script sets this>/mcp-server.js","--base-dir=C:/Users/admica/my/project/base"],
"transport": "stdio",
"disabled": false,
"alwaysAllow": []
}
}
}
{
"mcpServers": {
"FileScopeMCP": {
"command": "wsl",
"args": ["-d", "Ubuntu-24.04", "/home/admica/FileScopeMCP/run.sh"],
"transport": "stdio",
"disabled": false,
"alwaysAllow": []
}
}
}
- 将参数路径 --base-dir 更新为项目的基本路径。
工作原理
依赖性检测
该工具扫描源代码中的导入语句和其他特定于语言的模式：
- Python：
import和from ... import语句 - JavaScript/TypeScript：
import语句和require()调用 - C/C++：
#include指令 - Rust：
use和mod语句 - Lua：
require语句 - Zig：
@import指令
重要性计算
根据考虑以下因素的加权公式，为文件分配重要性分数（0-10）：
- 导入此文件的文件数（依赖项）
- 此文件导入的文件数（依赖项）
- 文件类型和扩展名（TypeScript/JavaScript 文件获得更高的基本分数）
- 项目结构中的位置（
src/中的文件权重更高） - 文件命名（像“index”、“main”、“server”等文件可获得额外加分）
代码库的中心文件（被许多文件导入）将具有更高的分数。
图表生成
该系统采用三阶段方法来生成有效的 Mermaid 语法：
- 收集阶段：注册所有节点和关系
- 节点定义阶段：在任何引用之前为所有节点生成定义
- 边生成阶段：在定义的节点之间创建边
这可确保所有图表都具有有效的语法并正确呈现。HTML 输出包括：
- 适用于任何设备的响应式设计
- 通过系统偏好设置检测切换明暗主题
- 客户端美人鱼渲染以实现最佳性能
- 生成时间戳
路径规范化
系统处理各种路径格式以确保文件识别的一致性：
- Windows 和 Unix 路径格式
- 绝对路径和相对路径
- URL 编码路径
- 跨平台兼容性
文件存储
所有文件树数据都存储在 JSON 文件中，其结构如下：
- 配置元数据（文件名、基目录、上次更新时间戳）
- 包含依赖项、被依赖项、重要性分数和摘要的完整文件树
技术细节
- TypeScript/Node.js ：使用 TypeScript 构建，以实现类型安全和现代 JavaScript 功能
- 模型上下文协议：实现与 Cursor 集成的 MCP 规范
- Mermaid.js ：使用 Mermaid 语法生成图表
- JSON 存储：使用简单的 JSON 文件进行持久化
- 路径规范化：跨平台路径处理，支持 Windows 和 Unix
- 缓存：实现缓存以实现更快的重复操作
可用工具
MCP 服务器公开以下工具：
文件树管理
- list_saved_trees ：列出所有已保存的文件树
- create_file_tree ：为特定目录创建新的文件树配置
- select_file_tree ：选择要使用的现有文件树
- delete_file_tree ：删除文件树配置
文件分析
- list_files ：列出项目中的所有文件及其重要性排名
- get_file_importance ：获取有关特定文件的详细信息，包括依赖项和被依赖项
- find_important_files ：根据可配置的标准查找项目中最重要的文件
- read_file_content ：读取特定文件的内容
- recalculate_importance ：根据依赖关系重新计算所有文件的重要性值
文件摘要
- get_file_summary ：获取特定文件的存储摘要
- set_file_summary ：设置或更新特定文件的摘要
文件监视
- toggle_file_watching ：打开/关闭文件监视
- get_file_watching_status ：获取文件监视的当前状态
- update_file_watching_config ：更新文件监视配置
图表生成
- generate_diagram ：使用可自定义选项创建美人鱼图
- 输出格式：美人鱼文本（
.mmd ）或嵌入渲染的 HTML - 图表样式：默认、依赖、目录或混合视图
- 过滤选项：最大深度、最小重要性阈值
- 布局选项：方向（TB、BT、LR、RL）、节点间距、等级间距
使用示例
最简单的入门方法是在 Cursor 中启用这个 mcp，并告诉 Cursor 自己识别并使用它。mcp 启动后，它会构建一个初始 json 树。告诉 LLM 对所有重要文件进行总结，并使用 mcp 的 set_file_summary 方法添加它们。
分析项目
- 为您的项目创建文件树：
create_file_tree(filename: "my-project.json", baseDirectory: "/path/to/project")
- 找到最重要的文件：
find_important_files(limit: 5, minImportance: 5)
- 获取特定文件的详细信息：
get_file_importance(filepath: "/path/to/project/src/main.ts")
使用摘要
- 阅读文件的内容以了解它：
read_file_content(filepath: "/path/to/project/src/main.ts")
- 向文件添加摘要：
set_file_summary(filepath: "/path/to/project/src/main.ts", summary: "Main entry point that initializes the application, sets up routing, and starts the server.")
- 稍后检索摘要：
get_file_summary(filepath: "/path/to/project/src/main.ts")
生成图表
- 创建基本项目结构图：
generate_diagram(style: "directory", maxDepth: 3, outputPath: "diagrams/project-structure", outputFormat: "mmd")
- 生成具有依赖关系的 HTML 图表：
generate_diagram(style: "hybrid", maxDepth: 2, minImportance: 5, showDependencies: true, outputPath: "diagrams/important-files", outputFormat: "html")
- 自定义图表布局：
generate_diagram(style: "dependency", layout: { direction: "LR", nodeSpacing: 50, rankSpacing: 70 }, outputPath: "diagrams/dependencies", outputFormat: "html")
使用文件监视
- 为您的项目启用文件监视：
- 检查当前文件监视状态：
get_file_watching_status()
- 更新文件监视配置：
update_file_watching_config(config: {
debounceMs: 500,
autoRebuildTree: true,
watchForNewFiles: true,
watchForDeleted: true,
watchForChanged: true
})
未来的改进
- 添加对更多编程语言的支持
- 添加更复杂的重要性计算算法
- 增强图表自定义选项
- 支持将图表导出为其他格式
执照
本项目遵循 GNU 通用公共许可证 v3 (GPL-3.0)。完整许可证文本请参阅LICENSE文件。