FileScopeMCP（模型上下文协议）服务器
✨ 立即了解并可视化您的代码库结构和依赖关系！✨
基于 TypeScript 的工具，用于按重要性对代码库中的文件进行排序、跟踪依赖关系并提供摘要以帮助理解代码结构。
概述
此 MCP 服务器会分析您的代码库，根据依赖关系识别最重要的文件。它会为每个文件生成重要性分数 (0-10)，跟踪双向依赖关系，并允许您为文件添加自定义摘要。所有这些信息都通过 Cursor 的模型上下文协议提供给 AI 工具。
Related MCP server: SourceSage MCP
特征
🚀增强你的代码理解能力！ FileScopeMCP 直接向你的 AI 助手提供洞察：
🎯 文件重要性分析
根据文件在代码库中的作用，按 0-10 的等级对文件进行排名。
使用传入/传出依赖关系计算重要性。
立即查明项目中最重要的文件。
智能计算考虑文件类型、位置和名称意义。
🔗 依赖跟踪
映射文件之间的双向依赖关系。
确定哪些文件导入给定文件（从属文件）。
查看给定文件导入了哪些文件（依赖项）。
区分本地依赖和包依赖。
多语言支持：Python、JavaScript、TypeScript、C/C++、Rust、Lua、Zig。
📊 可视化
生成美人鱼图来可视化文件关系。
根据重要性分数进行颜色编码的可视化。
支持依赖图、目录树或混合视图。
带有嵌入式渲染的 HTML 输出，包括主题切换和响应式设计。
自定义图表深度、按重要性过滤并调整布局选项。
📝 文件摘要
向任何文件添加人工或人工智能生成的摘要。
检索存储的摘要以快速掌握文件用途。
摘要在服务器重启后仍然存在。
📚 多项目支持
为不同的项目区域创建和管理多个文件树。
使用不同的基目录配置单独的树。
轻松在不同的文件树之间切换。
缓存树以便更快地进行后续操作。
💾 持久存储
所有数据以 JSON 格式自动保存到磁盘。
无需重新扫描文件系统即可加载现有文件树。
跟踪文件树的最后更新时间。
安装
克隆此存储库
构建项目：
构建脚本将安装所有节点依赖项并为您生成 mcp.json。
视窗：
build.bat将生成的 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": [] } } }Linux：（光标在 Windows 中，但您的项目在 Linux WSL 中，然后将 MCP 放入 Linux 中并构建）
build.sh{ "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")
使用文件监视
为您的项目启用文件监视：
toggle_file_watching()检查当前文件监视状态：
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文件。
