FileScopeMCP (模型上下文协议) 服务器

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

<!-- 在此处添加徽章（例如，许可证、版本、构建状态） --> <!-- 添加其他徽章 -->

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

概述

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

特性

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

• 🎯 文件重要性分析

  • 根据文件在代码库中的作用，按 0-10 的等级对文件进行排名。
  • 使用传入/传出依赖关系计算重要性。
  • 立即查明项目中最重要的文件。
  • 智能计算会考虑文件类型、位置和名称的重要性。

• 🔗 依赖关系跟踪

  • 映射文件之间的双向依赖关系。
  • 识别哪些文件导入给定文件（依赖项）。
  • 查看给定文件导入了哪些文件（依赖关系）。
  • 区分本地依赖项和包依赖项。
  • 多语言支持：Python、JavaScript、TypeScript、C/C++、Rust、Lua、Zig。

• 📊 可视化

  • 生成 Mermaid 图表以可视化文件关系。
  • 基于重要性评分的颜色编码可视化。
  • 支持依赖关系图、目录树或混合视图。
  • 具有嵌入式渲染的 HTML 输出，包括主题切换和响应式设计。
  • 自定义图表深度，按重要性过滤，并调整布局选项。

• 📝 文件摘要

  • 向任何文件添加人工或 AI 生成的摘要。
  • 检索存储的摘要以快速掌握文件用途。
  • 摘要在服务器重启后仍然存在。

• 📚 多项目支持

  • 为不同的项目区域创建和管理多个文件树。
  • 使用不同的基本目录配置单独的树。
  • 轻松切换不同的文件树。
  • 缓存树以加快后续操作。

• 💾 持久存储

  • 所有数据自动以 JSON 格式保存到磁盘。
  • 加载现有的文件树，而无需重新扫描文件系统。
  • 跟踪文件树上次更新的时间。

安装

1. 克隆此存储库

2. 构建项目：

   构建脚本将安装所有 node 依赖项并为您生成 mcp.json。

   Windows:

   build.bat
   

   将生成的 mcp.json 配置文件复制到项目的 .cursor 目录：

   {
     "mcpServers": {
       "FileScopeMCP": {
         "command": "node",
         "args": ["<构建脚本设置的路径>/mcp-server.js","--base-dir=C:/Users/admica/my/project/base"],
         "transport": "stdio",
         "disabled": false,
         "alwaysAllow": []
       }
     }
   }
   

   Linux: (Cursor 在 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. 更新 arg 路径 --base-dir 到您的项目基本路径。

工作原理

依赖关系检测

该工具扫描源代码中的 import 语句和其他特定于语言的模式：

• 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 输出包括：

• 适用于任何设备的响应式设计
• 具有系统首选项检测的浅色/深色主题切换
• 客户端 Mermaid 渲染以获得最佳性能
• 生成时间戳

路径规范化

系统处理各种路径格式以确保一致的文件标识：

• Windows 和 Unix 路径格式
• 绝对路径和相对路径
• URL 编码的路径
• 跨平台兼容性

文件存储

所有文件树数据都存储在具有以下结构的 JSON 文件中：

• 配置元数据（文件名、基本目录、上次更新时间戳）
• 具有依赖关系、依赖项、重要性评分和摘要的完整文件树

技术细节

• TypeScript/Node.js: 使用 TypeScript 构建，以实现类型安全和现代 JavaScript 功能
• 模型上下文协议: 实现 MCP 规范以与 Cursor 集成
• 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: 创建具有可自定义选项的 Mermaid 图表
  • 输出格式：Mermaid 文本 (.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 General Public License v3 (GPL-3.0) 获得许可。 有关完整的许可证文本，请参见 LICENSE 文件。