FileScopeMCP is a TypeScript-based tool that analyzes codebases to identify and rank files by importance based on dependency relationships. It generates importance scores, dependency maps, and file summaries, making this information accessible to AI assistants via Cursor's Model Context Protocol (MCP). This enables developers and AI tools to quickly understand complex code structures, pinpoint critical files, and navigate projects more effectively.

How It Works

The tool employs a multi-language parser to detect import statements and language-specific dependency patterns across Python, JavaScript/TypeScript, C/C++, Rust, Lua, Zig, C#, and Java. File importance is calculated using a weighted formula considering incoming/outgoing dependencies, file type, project location, and naming conventions. Generated diagrams leverage Mermaid.js syntax through a three-phase process (Collection, Node Definition, Edge Generation) for valid output, with options for HTML rendering, theme toggling, and responsive design. Path normalization ensures consistent file identification across different operating systems and formats. All analyzed data is persisted to disk in JSON format for efficient caching and retrieval.

Quick Start & Requirements

Installation involves cloning the repository and running a build script (build.bat for Windows, build.sh for Linux/WSL) which installs Node.js dependencies and generates mcp.json. This configuration file must be copied to the project's .cursor directory and the --base-dir argument updated to the project's root path. A Node.js/TypeScript runtime environment is required. Integration is primarily designed for Cursor IDE.

Highlighted Details

• File Importance Analysis: Ranks files on a 0-10 scale based on dependency depth and breadth.
• Dependency Tracking: Maps bidirectional relationships, distinguishing local from package imports.
• Multi-Language Support: Parses popular languages including Python, C/C++, Rust, Zig, Lua, JavaScript/TypeScript, C#, and Java.
• Visualization: Generates Mermaid diagrams (Mermaid text or HTML) with customizable styles (dependency, directory, hybrid), depth, and importance filtering.
• File Summaries: Allows adding and retrieving human or AI-generated summaries for files, persisting across restarts.
• Multi-Project Support: Manages and switches between multiple distinct project trees.
• File Watching: Includes options to toggle and configure automatic updates upon file changes.

Maintenance & Community

No specific details regarding contributors, sponsorships, community channels (e.g., Discord/Slack), or roadmaps were found in the provided README.

Licensing & Compatibility

This project is licensed under the GNU General Public License v3 (GPL-3.0). This copyleft license may impose restrictions on linking with closed-source software or distributing modified versions, requiring derived works to also be open-sourced under GPL-3.0.

Limitations & Caveats

The primary integration point appears to be Cursor IDE via the Model Context Protocol, which may limit standalone usability. The GPL-3.0 license necessitates careful consideration for commercial or closed-source integration. While supporting numerous languages, the effectiveness of importance calculation and diagram generation is dependent on the complexity and structure of the codebase.