FileScopeMCP (Model Context Protocol) Server
** Instantly understand and visualize your codebase structure & dependencies! **
A TypeScript-based tool for ranking files in your codebase by importance, tracking dependencies, and providing summaries to help understand code structure.
Overview
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.
Features
Supercharge your Code Understanding! FileScopeMCP provides insights directly to your AI assistant:
- ** File Importance Analysis**
- ** Dependency Tracking**
- ** Visualization**
- ** File Summaries**
- ** Multiple Project Support**
- ** Persistent Storage**
Installation
- Clone this repository
- Build the project:The build script will install all node dependencies and generate mcp.json for you.Windows:Copy the generated mcp.json configuration to your project's
.cursordirectory:Linux: (Cursor in Windows, but your project is in Linux WSL, then put the MCP in Linux and build)
- Update the arg path --base-dir to your project's base path.
How It Works
Dependency Detection
The tool scans source code for import statements and other language-specific patterns:
- Python:
importandfrom ... importstatements
- JavaScript/TypeScript:
importstatements andrequire()calls
- C/C++:
#includedirectives
- Rust:
useandmodstatements
- Lua:
requirestatements
- Zig:
@importdirectives
Importance Calculation
Files are assigned importance scores (0-10) based on a weighted formula that considers:
- Number of files that import this file (dependents)
- Number of files this file imports (dependencies)
- File type and extension (with TypeScript/JavaScript files getting higher base scores)
- Location in the project structure (files in
src/are weighted higher)
- File naming (files like 'index', 'main', 'server', etc. get additional points)
A file that is central to the codebase (imported by many files) will have a higher score.
Diagram Generation
The system uses a three-phase approach to generate valid Mermaid syntax:
- Collection Phase: Register all nodes and relationships
- Node Definition Phase: Generate definitions for all nodes before any references
- Edge Generation Phase: Create edges between defined nodes
This ensures all diagrams have valid syntax and render correctly. HTML output includes:
- Responsive design that works on any device
- Light/dark theme toggle with system preference detection
- Client-side Mermaid rendering for optimal performance
- Timestamp of generation
Path Normalization
The system handles various path formats to ensure consistent file identification:
- Windows and Unix path formats
- Absolute and relative paths
- URL-encoded paths
- Cross-platform compatibility
File Storage
All file tree data is stored in JSON files with the following structure:
- Configuration metadata (filename, base directory, last updated timestamp)
- Complete file tree with dependencies, dependents, importance scores, and summaries
Technical Details
- TypeScript/Node.js: Built with TypeScript for type safety and modern JavaScript features
- Model Context Protocol: Implements the MCP specification for integration with Cursor
- Mermaid.js: Uses Mermaid syntax for diagram generation
- JSON Storage: Uses simple JSON files for persistence
- Path Normalization: Cross-platform path handling to support Windows and Unix
- Caching: Implements caching for faster repeated operations
Available Tools
The MCP server exposes the following tools:
File Tree Management
- list_saved_trees: List all saved file trees
- create_file_tree: Create a new file tree configuration for a specific directory
- select_file_tree: Select an existing file tree to work with
- delete_file_tree: Delete a file tree configuration
File Analysis
- list_files: List all files in the project with their importance rankings
- get_file_importance: Get detailed information about a specific file, including dependencies and dependents
- find_important_files: Find the most important files in the project based on configurable criteria
- read_file_content: Read the content of a specific file
- recalculate_importance: Recalculate importance values for all files based on dependencies
File Summaries
- get_file_summary: Get the stored summary of a specific file
- set_file_summary: Set or update the summary of a specific file
File Watching
- toggle_file_watching: Toggle file watching on/off
- get_file_watching_status: Get the current status of file watching
- update_file_watching_config: Update file watching configuration
Diagram Generation
- generate_diagram: Create Mermaid diagrams with customizable options
Usage Examples
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.
Analyzing a Project
- Create a file tree for your project:
- Find the most important files:
- Get detailed information about a specific file:
Working with Summaries
- Read a file's content to understand it:
- Add a summary to the file:
- Retrieve the summary later:
Generating Diagrams
- Create a basic project structure diagram:
- Generate an HTML diagram with dependency relationships:
- Customize the diagram layout:
Using File Watching
- Enable file watching for your project:
- Check the current file watching status:
- Update file watching configuration:
Future Improvements
- Add support for more programming languages
- Add more sophisticated importance calculation algorithms
- Enhance diagram customization options
- Support for exporting diagrams to additional formats
License
This project is licensed under the GNU General Public License v3 (GPL-3.0). See the LICENSE file for the full license text.
FileScopeMCP (Model Context Protocol) Server
** Instantly understand and visualize your codebase structure & dependencies! **
A TypeScript-based tool for ranking files in your codebase by importance, tracking dependencies, and providing summaries to help understand code structure.
Overview
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.
Features
Supercharge your Code Understanding! FileScopeMCP provides insights directly to your AI assistant:
- ** File Importance Analysis**
- ** Dependency Tracking**
- ** Visualization**
- ** File Summaries**
- ** Multiple Project Support**
- ** Persistent Storage**
Installation
- Clone this repository
- Build the project:The build script will install all node dependencies and generate mcp.json for you.Windows:Copy the generated mcp.json configuration to your project's
.cursordirectory:Linux: (Cursor in Windows, but your project is in Linux WSL, then put the MCP in Linux and build)
- Update the arg path --base-dir to your project's base path.
How It Works
Dependency Detection
The tool scans source code for import statements and other language-specific patterns:
- Python:
importandfrom ... importstatements
- JavaScript/TypeScript:
importstatements andrequire()calls
- C/C++:
#includedirectives
- Rust:
useandmodstatements
- Lua:
requirestatements
- Zig:
@importdirectives
Importance Calculation
Files are assigned importance scores (0-10) based on a weighted formula that considers:
- Number of files that import this file (dependents)
- Number of files this file imports (dependencies)
- File type and extension (with TypeScript/JavaScript files getting higher base scores)
- Location in the project structure (files in
src/are weighted higher)
- File naming (files like 'index', 'main', 'server', etc. get additional points)
A file that is central to the codebase (imported by many files) will have a higher score.
Diagram Generation
The system uses a three-phase approach to generate valid Mermaid syntax:
- Collection Phase: Register all nodes and relationships
- Node Definition Phase: Generate definitions for all nodes before any references
- Edge Generation Phase: Create edges between defined nodes
This ensures all diagrams have valid syntax and render correctly. HTML output includes:
- Responsive design that works on any device
- Light/dark theme toggle with system preference detection
- Client-side Mermaid rendering for optimal performance
- Timestamp of generation
Path Normalization
The system handles various path formats to ensure consistent file identification:
- Windows and Unix path formats
- Absolute and relative paths
- URL-encoded paths
- Cross-platform compatibility
File Storage
All file tree data is stored in JSON files with the following structure:
- Configuration metadata (filename, base directory, last updated timestamp)
- Complete file tree with dependencies, dependents, importance scores, and summaries
Technical Details
- TypeScript/Node.js: Built with TypeScript for type safety and modern JavaScript features
- Model Context Protocol: Implements the MCP specification for integration with Cursor
- Mermaid.js: Uses Mermaid syntax for diagram generation
- JSON Storage: Uses simple JSON files for persistence
- Path Normalization: Cross-platform path handling to support Windows and Unix
- Caching: Implements caching for faster repeated operations
Available Tools
The MCP server exposes the following tools:
File Tree Management
- list_saved_trees: List all saved file trees
- create_file_tree: Create a new file tree configuration for a specific directory
- select_file_tree: Select an existing file tree to work with
- delete_file_tree: Delete a file tree configuration
File Analysis
- list_files: List all files in the project with their importance rankings
- get_file_importance: Get detailed information about a specific file, including dependencies and dependents
- find_important_files: Find the most important files in the project based on configurable criteria
- read_file_content: Read the content of a specific file
- recalculate_importance: Recalculate importance values for all files based on dependencies
File Summaries
- get_file_summary: Get the stored summary of a specific file
- set_file_summary: Set or update the summary of a specific file
File Watching
- toggle_file_watching: Toggle file watching on/off
- get_file_watching_status: Get the current status of file watching
- update_file_watching_config: Update file watching configuration
Diagram Generation
- generate_diagram: Create Mermaid diagrams with customizable options
Usage Examples
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.
Analyzing a Project
- Create a file tree for your project:
- Find the most important files:
- Get detailed information about a specific file:
Working with Summaries
- Read a file's content to understand it:
- Add a summary to the file:
- Retrieve the summary later:
Generating Diagrams
- Create a basic project structure diagram:
- Generate an HTML diagram with dependency relationships:
- Customize the diagram layout:
Using File Watching
- Enable file watching for your project:
- Check the current file watching status:
- Update file watching configuration:
Future Improvements
- Add support for more programming languages
- Add more sophisticated importance calculation algorithms
- Enhance diagram customization options
- Support for exporting diagrams to additional formats
License
This project is licensed under the GNU General Public License v3 (GPL-3.0). See the LICENSE file for the full license text.