FileScopeMCP（模型上下文协议）服务器

✨ 立即了解并可视化您的代码库结构和依赖关系！✨

基于 TypeScript 的工具，用于按重要性对代码库中的文件进行排序、跟踪依赖关系并提供摘要以帮助理解代码结构。

概述

此 MCP 服务器会分析您的代码库，根据依赖关系识别最重要的文件。它会为每个文件生成重要性分数 (0-10)，跟踪双向依赖关系，并允许您为文件添加自定义摘要。所有这些信息都通过 Cursor 的模型上下文协议提供给 AI 工具。

特征

🚀增强你的代码理解能力！ FileScopeMCP 直接向你的 AI 助手提供洞察：

• 🎯 文件重要性分析
  • 根据文件在代码库中的作用，按 0-10 的等级对文件进行排名。
  • 使用传入/传出依赖关系计算重要性。
  • 立即查明项目中最重要的文件。
  • 智能计算考虑文件类型、位置和名称意义。
• 🔗 依赖跟踪
  • 映射文件之间的双向依赖关系。
  • 确定哪些文件导入给定文件（从属文件）。
  • 查看给定文件导入了哪些文件（依赖项）。
  • 区分本地依赖和包依赖。
  • 多语言支持：Python、JavaScript、TypeScript、C/C++、Rust、Lua、Zig。
• 📊 可视化
  • 生成美人鱼图来可视化文件关系。
  • 根据重要性分数进行颜色编码的可视化。
  • 支持依赖图、目录树或混合视图。
  • 带有嵌入式渲染的 HTML 输出，包括主题切换和响应式设计。
  • 自定义图表深度、按重要性过滤并调整布局选项。
• 📝 文件摘要
  • 向任何文件添加人工或人工智能生成的摘要。
  • 检索存储的摘要以快速掌握文件用途。
  • 摘要在服务器重启后仍然存在。
• 📚 多项目支持
  • 为不同的项目区域创建和管理多个文件树。
  • 使用不同的基目录配置单独的树。
  • 轻松在不同的文件树之间切换。
  • 缓存树以便更快地进行后续操作。
• 💾 持久存储
  • 所有数据以 JSON 格式自动保存到磁盘。
  • 无需重新扫描文件系统即可加载现有文件树。
  • 跟踪文件树的最后更新时间。

安装

1. 克隆此存储库
2. 构建项目：构建脚本将安装所有节点依赖项并为您生成 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": [] } } }
3. 将参数路径 --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 语法：

1. 收集阶段：注册所有节点和关系
2. 节点定义阶段：在任何引用之前为所有节点生成定义
3. 边生成阶段：在定义的节点之间创建边

这可确保所有图表都具有有效的语法并正确呈现。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 方法添加它们。

分析项目

1. 为您的项目创建文件树：
   create_file_tree(filename: "my-project.json", baseDirectory: "/path/to/project")
2. 找到最重要的文件：
   find_important_files(limit: 5, minImportance: 5)
3. 获取特定文件的详细信息：
   get_file_importance(filepath: "/path/to/project/src/main.ts")

使用摘要

1. 阅读文件的内容以了解它：
   read_file_content(filepath: "/path/to/project/src/main.ts")
2. 向文件添加摘要：
   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.")
3. 稍后检索摘要：
   get_file_summary(filepath: "/path/to/project/src/main.ts")

生成图表

1. 创建基本项目结构图：
   generate_diagram(style: "directory", maxDepth: 3, outputPath: "diagrams/project-structure", outputFormat: "mmd")
2. 生成具有依赖关系的 HTML 图表：
   generate_diagram(style: "hybrid", maxDepth: 2, minImportance: 5, showDependencies: true, outputPath: "diagrams/important-files", outputFormat: "html")
3. 自定义图表布局：
   generate_diagram(style: "dependency", layout: { direction: "LR", nodeSpacing: 50, rankSpacing: 70 }, outputPath: "diagrams/dependencies", outputFormat: "html")

使用文件监视

1. 为您的项目启用文件监视：
   toggle_file_watching()
2. 检查当前文件监视状态：
   get_file_watching_status()
3. 更新文件监视配置：
   update_file_watching_config(config: { debounceMs: 500, autoRebuildTree: true, watchForNewFiles: true, watchForDeleted: true, watchForChanged: true })

未来的改进

• 添加对更多编程语言的支持
• 添加更复杂的重要性计算算法
• 增强图表自定义选项
• 支持将图表导出为其他格式

执照

本项目遵循 GNU 通用公共许可证 v3 (GPL-3.0)。完整许可证文本请参阅LICENSE文件。