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

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

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

概览

此 MCP 服务器分析您的代码库，根据依赖关系识别最重要的文件。它为每个文件生成重要性评分（0-10），跟踪双向依赖关系，并允许您为文件添加自定义摘要。所有这些信息通过 Cursor 的 Model Context Protocol 提供给 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": ["<build script sets this>/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 为您的项目的基本路径。

工作原理

依赖检测

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

• 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): 实现 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: "应用程序的主要入口点，初始化应用、设置路由并启动服务器。")
   

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 文件获取完整的许可证文本。