FileScopeMCP

Local 2025-08-31 23:28:41 0

A TypeScript tool that ranks files in your codebase by importance, tracks dependencies, and provides file summaries to help understand code structure through Cursor's Model Context Protocol.

x000D ✨ Instantly understand and visualize your codebase structure & dependencies! ✨x000D x000D

x000D x000D x000D x000D

x000D x000D A TypeScript-based tool for ranking files in your codebase by importance, tracking dependencies, and providing summaries to help understand code structure.x000D x000D

Overview_x000D_

x000D This MCP server analyzes your codebase to identify the most important files based on dependency relationships. It generates importance scores (0-10) for each file, tracks bidirectional dependencies, and allows you to add custom summaries for files. All this information is made available to AI tools through Cursor's Model Context Protocol.x000D x000D

Features_x000D_

x000D ? Supercharge your Code Understanding! FileScopeMCP provides insights directly to your AI assistant:x000D x000D - ? File Importance Analysisx000D - Rank files on a 0-10 scale based on their role in the codebase.x000D - Calculate importance using incoming/outgoing dependencies.x000D - Instantly pinpoint the most critical files in your project.x000D - Smart calculation considers file type, location, and name significance.x000D x000D - ? Dependency Trackingx000D - Map bidirectional dependency relationships between files.x000D - Identify which files import a given file (dependents).x000D - See which files are imported by a given file (dependencies).x000D - Distinguish between local and package dependencies.x000D - Multi-language support: Python, JavaScript, TypeScript, C/C++, Rust, Lua, Zig.x000D x000D - ? Visualizationx000D - Generate Mermaid diagrams to visualize file relationships.x000D - Color-coded visualization based on importance scores.x000D - Support for dependency graphs, directory trees, or hybrid views.x000D - HTML output with embedded rendering including theme toggle and responsive design.x000D - Customize diagram depth, filter by importance, and adjust layout options.x000D x000D - ? File Summariesx000D - Add human or AI-generated summaries to any file.x000D - Retrieve stored summaries to quickly grasp file purpose.x000D - Summaries persist across server restarts.x000D x000D - ? Multiple Project Supportx000D - Create and manage multiple file trees for different project areas.x000D - Configure separate trees with distinct base directories.x000D - Switch between different file trees effortlessly.x000D - Cached trees for faster subsequent operations.x000D x000D - ? Persistent Storagex000D - All data automatically saved to disk in JSON format.x000D - Load existing file trees without rescanning the filesystem.x000D - Track when file trees were last updated.x000D x000D

Installation_x000D_

x000D 1. Clone this repository_x000D_ 2. Build the project:x000D x000D The build script will install all node dependencies and generate mcp.json for you.x000D x000D Windows:x000D bash_x000D_ build.bat_x000D_x000D x000D Copy the generated mcp.json configuration to your project's .cursor directory:x000D x000D json_x000D_ {_x000D_ "mcpServers": {_x000D_ "FileScopeMCP": {_x000D_ "command": "node",_x000D_ "args": ["<build script sets this>/mcp-server.js","--base-dir=C:/Users/admica/my/project/base"],_x000D_ "transport": "stdio",_x000D_ "disabled": false,_x000D_ "alwaysAllow": []_x000D_ }_x000D_ }_x000D_ }_x000D_x000D x000D Linux: (Cursor in Windows, but your project is in Linux WSL, then put the MCP in Linux and build)x000D bash_x000D_ build.sh_x000D_x000D x000D json_x000D_ {_x000D_ "mcpServers": {_x000D_ "FileScopeMCP": {_x000D_ "command": "wsl",_x000D_ "args": ["-d", "Ubuntu-24.04", "/home/admica/FileScopeMCP/run.sh"],_x000D_ "transport": "stdio",_x000D_ "disabled": false,_x000D_ "alwaysAllow": []_x000D_ }_x000D_ }_x000D_ }_x000D_x000D 4. Update the arg path --base-dir to your project's base path.x000D x000D

How It Works_x000D_

x000D

Dependency Detection_x000D_

x000D The tool scans source code for import statements and other language-specific patterns:x000D - Python: import and from ... import statements_x000D_ - JavaScript/TypeScript: import statements and require() calls_x000D_ - C/C++: #include directives_x000D_ - Rust: use and mod statements_x000D_ - Lua: require statements_x000D_ - Zig: @import directives_x000D_ x000D

Importance Calculation_x000D_

x000D Files are assigned importance scores (0-10) based on a weighted formula that considers:x000D - Number of files that import this file (dependents)x000D - Number of files this file imports (dependencies)x000D - File type and extension (with TypeScript/JavaScript files getting higher base scores)x000D - Location in the project structure (files in src/ are weighted higher)x000D - File naming (files like 'index', 'main', 'server', etc. get additional points)x000D x000D A file that is central to the codebase (imported by many files) will have a higher score.x000D x000D

Diagram Generation_x000D_

x000D The system uses a three-phase approach to generate valid Mermaid syntax:x000D 1. Collection Phase: Register all nodes and relationships_x000D_ 2. Node Definition Phase: Generate definitions for all nodes before any references_x000D_ 3. Edge Generation Phase: Create edges between defined nodes_x000D_ x000D This ensures all diagrams have valid syntax and render correctly. HTML output includes:x000D - Responsive design that works on any device_x000D_ - Light/dark theme toggle with system preference detection_x000D_ - Client-side Mermaid rendering for optimal performance_x000D_ - Timestamp of generation_x000D_ x000D

Path Normalization_x000D_

x000D The system handles various path formats to ensure consistent file identification:x000D - Windows and Unix path formats_x000D_ - Absolute and relative paths_x000D_ - URL-encoded paths_x000D_ - Cross-platform compatibility_x000D_ x000D

File Storage_x000D_

x000D All file tree data is stored in JSON files with the following structure:x000D - Configuration metadata (filename, base directory, last updated timestamp)x000D - Complete file tree with dependencies, dependents, importance scores, and summaries_x000D_ x000D

Technical Details_x000D_

x000D - TypeScript/Node.js: Built with TypeScript for type safety and modern JavaScript features_x000D_ - Model Context Protocol: Implements the MCP specification for integration with Cursor_x000D_ - Mermaid.js: Uses Mermaid syntax for diagram generation_x000D_ - JSON Storage: Uses simple JSON files for persistence_x000D_ - Path Normalization: Cross-platform path handling to support Windows and Unix_x000D_ - Caching: Implements caching for faster repeated operations_x000D_ x000D

Available Tools_x000D_

x000D The MCP server exposes the following tools:x000D x000D

File Tree Management_x000D_

x000D - list_saved_trees: List all saved file trees_x000D_ - create_file_tree: Create a new file tree configuration for a specific directory_x000D_ - select_file_tree: Select an existing file tree to work with_x000D_ - delete_file_tree: Delete a file tree configuration_x000D_ x000D

File Analysis_x000D_

x000D - list_files: List all files in the project with their importance rankings_x000D_ - get_file_importance: Get detailed information about a specific file, including dependencies and dependents_x000D_ - find_important_files: Find the most important files in the project based on configurable criteria_x000D_ - read_file_content: Read the content of a specific file_x000D_ - recalculate_importance: Recalculate importance values for all files based on dependencies_x000D_ x000D

File Summaries_x000D_

x000D - get_file_summary: Get the stored summary of a specific file_x000D_ - set_file_summary: Set or update the summary of a specific file_x000D_ x000D

File Watching_x000D_

x000D - toggle_file_watching: Toggle file watching on/off_x000D_ - get_file_watching_status: Get the current status of file watching_x000D_ - update_file_watching_config: Update file watching configuration_x000D_ x000D

Diagram Generation_x000D_

x000D - generate_diagram: Create Mermaid diagrams with customizable options_x000D_ - Output formats: Mermaid text (.mmd) or HTML with embedded rendering_x000D_ - Diagram styles: default, dependency, directory, or hybrid views_x000D_ - Filter options: max depth, minimum importance threshold_x000D_ - Layout options: direction (TB, BT, LR, RL), node spacing, rank spacing_x000D_ x000D

Usage Examples_x000D_

x000D The easiest way to get started is to enable this mcp in cursor and tell cursor to figure it out and use it. As soon as the mcp starts, it builds an initial json tree. Tell an LLM to make summaries of all your important files and use the mcp's set_file_summary to add them.x000D x000D

Analyzing a Project_x000D_

x000D 1. Create a file tree for your project:x000D _x000D_ create_file_tree(filename: "my-project.json", baseDirectory: "/path/to/project")_x000D_x000D x000D 2. Find the most important files:x000D _x000D_ find_important_files(limit: 5, minImportance: 5)_x000D_x000D x000D 3. Get detailed information about a specific file:x000D _x000D_ get_file_importance(filepath: "/path/to/project/src/main.ts")_x000D_x000D x000D

Working with Summaries_x000D_

x000D 1. Read a file's content to understand it:x000D _x000D_ read_file_content(filepath: "/path/to/project/src/main.ts")_x000D_x000D x000D 2. Add a summary to the file:x000D _x000D_ 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.")_x000D_x000D x000D 3. Retrieve the summary later:x000D _x000D_ get_file_summary(filepath: "/path/to/project/src/main.ts")_x000D_x000D x000D

Generating Diagrams_x000D_

x000D 1. Create a basic project structure diagram:x000D _x000D_ generate_diagram(style: "directory", maxDepth: 3, outputPath: "diagrams/project-structure", outputFormat: "mmd")_x000D_x000D x000D 2. Generate an HTML diagram with dependency relationships:x000D _x000D_ generate_diagram(style: "hybrid", maxDepth: 2, minImportance: 5, showDependencies: true, outputPath: "diagrams/important-files", outputFormat: "html")_x000D_x000D x000D 3. Customize the diagram layout:x000D _x000D_ generate_diagram(style: "dependency", layout: { direction: "LR", nodeSpacing: 50, rankSpacing: 70 }, outputPath: "diagrams/dependencies", outputFormat: "html")_x000D_x000D x000D

Using File Watching_x000D_

x000D 1. Enable file watching for your project:x000D _x000D_ toggle_file_watching()_x000D_x000D x000D 2. Check the current file watching status:x000D _x000D_ get_file_watching_status()_x000D_x000D x000D 3. Update file watching configuration:x000D _x000D_ update_file_watching_config(config: { _x000D_ debounceMs: 500, _x000D_ autoRebuildTree: true,_x000D_ watchForNewFiles: true,_x000D_ watchForDeleted: true,_x000D_ watchForChanged: true_x000D_ })_x000D_x000D x000D

Future Improvements_x000D_

x000D - Add support for more programming languages_x000D_ - Add more sophisticated importance calculation algorithms_x000D_ - Enhance diagram customization options_x000D_ - Support for exporting diagrams to additional formats_x000D_ x000D

License_x000D_

x000D This project is licensed under the GNU General Public License v3 (GPL-3.0). See the LICENSE file for the full license text.x000D

[
  {
    "description": "List all saved file trees",
    "inputSchema": {
      "type": "object"
    },
    "name": "list_saved_trees"
  },
  {
    "description": "Delete a file tree configuration",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "filename": {
          "description": "Name of the JSON file to delete",
          "type": "string"
        }
      },
      "required": [
        "filename"
      ],
      "type": "object"
    },
    "name": "delete_file_tree"
  },
  {
    "description": "Create or load a file tree configuration",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "baseDirectory": {
          "description": "Base directory to scan for files",
          "type": "string"
        },
        "filename": {
          "description": "Name of the JSON file to store the file tree",
          "type": "string"
        }
      },
      "required": [
        "filename",
        "baseDirectory"
      ],
      "type": "object"
    },
    "name": "create_file_tree"
  },
  {
    "description": "Select an existing file tree to work with",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "filename": {
          "description": "Name of the JSON file containing the file tree",
          "type": "string"
        }
      },
      "required": [
        "filename"
      ],
      "type": "object"
    },
    "name": "select_file_tree"
  },
  {
    "description": "List all files in the project with their importance rankings",
    "inputSchema": {
      "type": "object"
    },
    "name": "list_files"
  },
  {
    "description": "Get the importance ranking of a specific file",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "filepath": {
          "description": "The path to the file to check",
          "type": "string"
        }
      },
      "required": [
        "filepath"
      ],
      "type": "object"
    },
    "name": "get_file_importance"
  },
  {
    "description": "Find the most important files in the project",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "limit": {
          "description": "Number of files to return (default: 10)",
          "type": "number"
        },
        "minImportance": {
          "description": "Minimum importance score (0-10)",
          "type": "number"
        }
      },
      "type": "object"
    },
    "name": "find_important_files"
  },
  {
    "description": "Get the summary of a specific file",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "filepath": {
          "description": "The path to the file to check",
          "type": "string"
        }
      },
      "required": [
        "filepath"
      ],
      "type": "object"
    },
    "name": "get_file_summary"
  },
  {
    "description": "Set the summary of a specific file",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "filepath": {
          "description": "The path to the file to update",
          "type": "string"
        },
        "summary": {
          "description": "The summary text to set",
          "type": "string"
        }
      },
      "required": [
        "filepath",
        "summary"
      ],
      "type": "object"
    },
    "name": "set_file_summary"
  },
  {
    "description": "Read the content of a specific file",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "filepath": {
          "description": "The path to the file to read",
          "type": "string"
        }
      },
      "required": [
        "filepath"
      ],
      "type": "object"
    },
    "name": "read_file_content"
  },
  {
    "description": "Manually set the importance ranking of a specific file",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "filepath": {
          "description": "The path to the file to update",
          "type": "string"
        },
        "importance": {
          "description": "The importance value to set (0-10)",
          "maximum": 10,
          "minimum": 0,
          "type": "number"
        }
      },
      "required": [
        "filepath",
        "importance"
      ],
      "type": "object"
    },
    "name": "set_file_importance"
  },
  {
    "description": "Recalculate importance values for all files based on dependencies",
    "inputSchema": {
      "type": "object"
    },
    "name": "recalculate_importance"
  },
  {
    "description": "List all file paths in the current file tree",
    "inputSchema": {
      "type": "object"
    },
    "name": "debug_list_all_files"
  },
  {
    "description": "Generate a Mermaid diagram for the current file tree",
    "inputSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "additionalProperties": false,
      "properties": {
        "layout": {
          "additionalProperties": false,
          "properties": {
            "direction": {
              "enum": [
                "TB",
                "BT",
                "LR",
                "RL"
              ],
              "type": "string"
            },
            "nodeSpacing": {
              "maximum": 100,
              "minimum": 10,
              "type": "number"
            },
            "rankSpacing": {
              "maximum": 100,
              "minimum": 10,
              "type": "number"
            }
          },
          "type": "object"
        },
        "maxDepth": {
          "description": "Maximum depth for directory trees (1-10)",
          "type": "number"
        },
        "minImportance": {
          "description": "Only show files above this importance (0-10)",
          "type": "number"
        },
        "outputFile": {
          "description": "Optional output file name for the diagram",
          "type": "string"
        },
        "outputFormat": {
          "description": "Output format (mmd or png)",
          "enum": [
            "mmd",
            "png"
          ],
          "type": "string"
        },
        "showDependencies": {
          "description": "Whether to show dependency relationships",
          "type": "boolean"
        },
        "style": {
          "description": "Diagram style",
          "enum": [
            "default",
            "dependency",
            "directory",
            "hybrid"
          ],
          "type": "string"
        }
      },
      "required": [
        "style"
      ],
      "type": "object"
    },
    "name": "generate_diagram"
  }
]