STARWARCLOUD STARWAR.AI
返回市场
文件范围MCP

文件范围MCP

作者：admica259 星标更新：2025-09-05
安装使用来源：spider==github.com

项目介绍

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

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

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

构建状态 Node.js 许可证: GPL v3

<!-- 添加其他徽章 -->

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

概述

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

功能

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

  • 🎯 文件重要性分析

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

  • 🔗 依赖关系追踪

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

  • 📊 可视化

    • 生成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": {
    "FileScopeMMCP": {
    "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 指令
  • C#: using 指令
  • Java: 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）、节点间距、等级间距

使用示例

最简单的方法是启用此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
})

测试

现在包含了一个测试框架（Vitest）。初步单元测试涵盖了路径规范化、glob-to-regexp转换以及特定平台的路径处理。

运行测试和检查覆盖率：

npm test
npm run coverage

最近改进

  • 改进了排除逻辑，忽略隐藏的虚拟环境（如.venv）和其他常见的不需要的目录。这有助于保持依赖图干净且相关。
  • 测试框架
  • 增加了更多编程语言

未来改进

  • 添加更复杂的计算重要性的算法
  • 增强图表定制选项
  • 支持导出图表到其他格式

许可证

本项目根据GNU通用公共许可证v3（GPL-3.0）授权。查看LICENSE文件获取完整的许可证文本。