FileScopeMCP is a Model Context Protocol (MCP) server designed to enhance AI model understanding of codebase structure and dependencies. This TypeScript-based tool analyzes your project, assigning importance scores to files based on their role and connections within the codebase. It tracks bidirectional dependencies across multiple languages like Python, JavaScript, and C++, enabling AI models to quickly identify critical files and their relationships.

Key features include generating Mermaid diagrams for visualizing file relationships, allowing developers to add custom summaries for files, and supporting multiple project configurations. FileScopeMCP seamlessly integrates with AI tools via the MCP, providing context-aware information to improve code understanding and generation. By offering insights into file importance and dependencies, FileScopeMCP empowers developers to navigate complex projects more efficiently and leverage AI assistance more effectively. The server stores all data in JSON format for persistence and easy access.

File Importance Analysis

FileScopeMCP analyzes a codebase to rank files based on their importance, assigning scores from 0 to 10. This ranking is determined by considering both incoming and outgoing dependencies, file type, location within the project structure, and file naming conventions. Files that are imported by many other files, located in key directories like src/, or have names like index or main receive higher scores. This feature helps AI models quickly identify the most critical files in a project, enabling them to focus on the core logic and architecture.

For example, in a large React application, the App.tsx file, which imports numerous components and modules, would likely receive a high importance score. Similarly, a utils.py file in a Python project, containing commonly used functions, would also be ranked highly. This allows AI tools to prioritize these files when generating summaries, suggesting code improvements, or performing other code-related tasks. The importance calculation algorithm provides a nuanced understanding of each file's role, going beyond simple line counts or file sizes.

Dependency Tracking

FileScopeMCP meticulously tracks bidirectional dependencies between files, identifying which files import a given file (dependents) and which files are imported by that file (dependencies). It distinguishes between local and package dependencies and supports multiple languages, including Python, JavaScript, TypeScript, C/C++, Rust, Lua, and Zig. This feature provides AI models with a comprehensive understanding of the relationships between different parts of the codebase, enabling them to reason about code changes, identify potential conflicts, and suggest refactoring opportunities.

Consider a scenario where a developer modifies a function in a shared utility file. With dependency tracking, an AI model can quickly identify all files that depend on this utility file and assess the potential impact of the change. It can then generate a list of files that need to be tested or updated to ensure compatibility. This feature is particularly valuable in large, complex projects where understanding the ripple effects of code changes can be challenging. The tool uses static analysis of import statements and language-specific patterns to accurately map these relationships.

Visual Codebase Structure

FileScopeMCP generates Mermaid diagrams to visualize file relationships, using color-coding based on importance scores. It supports dependency graphs, directory trees, and hybrid views, outputting HTML with embedded rendering, a theme toggle, and responsive design. Diagrams can be customized by depth and importance. This feature allows developers and AI models to quickly grasp the overall structure of a codebase, identify key modules, and understand the relationships between different components.

For instance, a developer can use FileScopeMCP to generate a directory tree diagram of their project, highlighting the most important files in different colors. This visual representation can help them quickly identify areas of the codebase that require attention or refactoring. Similarly, an AI model can use the diagram to understand the project's architecture and generate more accurate and relevant code suggestions. The system uses a three-phase approach to generate valid Mermaid syntax, ensuring that all diagrams render correctly.

File Summaries

FileScopeMCP allows users to add human or AI-generated summaries to any file, storing these summaries for quick retrieval. These summaries persist across server restarts, providing a persistent knowledge base about the codebase. This feature enables AI models to quickly grasp the purpose of individual files, understand their role in the overall system, and generate more accurate and relevant code suggestions.

Imagine a scenario where a developer has added a summary to a complex algorithm implementation, explaining its purpose, inputs, and outputs. When an AI model encounters this file, it can retrieve the summary and use it to understand the algorithm's functionality without having to analyze the code itself. This can significantly speed up the code understanding process and improve the accuracy of AI-powered code analysis and generation tools. The summaries are stored in JSON format, making them easily accessible and modifiable.