FileScopeMCP (Model Context Protocol) Server

1# FileScopeMCP (Model Context Protocol) Server
2 
3**✨ Instantly understand and visualize your codebase structure & dependencies! ✨**
4 
5<!-- Add Badges Here (e.g., License, Version, Build Status) -->
6[![Build Status](https://github.com/admica/FileScopeMCP/actions/workflows/build.yml/badge.svg)](https://github.com/admica/FileScopeMCP/actions)
7[![Node.js](https://img.shields.io/badge/node-%3E%3D18.x-green)](https://nodejs.org/)
8[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
9 
10[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/admica/FileScopeMCP)](https://archestra.ai/mcp-catalog/admica__filescopemcp)
11<!-- Add other badges -->
12 
13A TypeScript-based tool for ranking files in your codebase by importance, tracking dependencies, and providing summaries to help understand code structure.
14 
15## Overview
16 
17This 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.
18 
19## Features
20 
21🚀 **Supercharge your Code Understanding!** FileScopeMCP provides insights directly to your AI assistant:
22 
23- **🎯 File Importance Analysis**
24  - Rank files on a 0-10 scale based on their role in the codebase.
25  - Calculate importance using incoming/outgoing dependencies.
26  - Instantly pinpoint the most critical files in your project.
27  - Smart calculation considers file type, location, and name significance.
28 
29- **🔗 Dependency Tracking**
30  - Map bidirectional dependency relationships between files.
31  - Identify which files import a given file (dependents).
32  - See which files are imported by a given file (dependencies).
33  - Distinguish between local and package dependencies.
34  - Multi-language support: Python, JavaScript, TypeScript, C/C++, Rust, Lua, Zig, C#, Java.
35 
36- **📊 Visualization**
37  - Generate Mermaid diagrams to visualize file relationships.
38  - Color-coded visualization based on importance scores.
39  - Support for dependency graphs, directory trees, or hybrid views.
40  - HTML output with embedded rendering including theme toggle and responsive design.
41  - Customize diagram depth, filter by importance, and adjust layout options.
42 
43- **📝 File Summaries**
44  - Add human or AI-generated summaries to any file.
45  - Retrieve stored summaries to quickly grasp file purpose.
46  - Summaries persist across server restarts.
47 
48- **📚 Multiple Project Support**
49  - Create and manage multiple file trees for different project areas.
50  - Configure separate trees with distinct base directories.
51  - Switch between different file trees effortlessly.
52  - Cached trees for faster subsequent operations.
53 
54- **💾 Persistent Storage**
55  - All data automatically saved to disk in JSON format.
56  - Load existing file trees without rescanning the filesystem.
57  - Track when file trees were last updated.
58 
59## Installation
60 
611. Clone this repository
622. Build the project:
63 
64   The build script will install all node dependencies and generate mcp.json for you.
65 
66   Windows:
67   ```bash
68   build.bat
69   ```
70 
71   Copy the generated mcp.json configuration to your project's `.cursor` directory:
72 
73   ```json
74   {
75     "mcpServers": {
76       "FileScopeMCP": {
77         "command": "node",
78         "args": ["<build script sets this>/mcp-server.js","--base-dir=C:/Users/admica/my/project/base"],
79         "transport": "stdio",
80         "disabled": false,
81         "alwaysAllow": []
82       }
83     }
84   }
85   ```
86   
87   Linux: (Cursor in Windows, but your project is in Linux WSL, then put the MCP in Linux and build)
88   ```bash
89   build.sh
90   ```
91   
92   ```json
93   {
94     "mcpServers": {
95       "FileScopeMCP": {
96       "command": "wsl",
97       "args": ["-d", "Ubuntu-24.04", "/home/admica/FileScopeMCP/run.sh"],
98       "transport": "stdio",
99       "disabled": false,
100       "alwaysAllow": []
101       }
102     }
103    }
104    ```
1054. Update the arg path --base-dir to your project's base path.
106 
107## How It Works
108 
109### Dependency Detection
110 
111The tool scans source code for import statements and other language-specific patterns:
112- Python: `import` and `from ... import` statements
113- JavaScript/TypeScript: `import` statements and `require()` calls
114- C/C++: `#include` directives
115- Rust: `use` and `mod` statements
116- Lua: `require` statements
117- Zig: `@import` directives
118- C#: `using` directives
119- Java: `import` statements
120 
121### Importance Calculation
122 
123Files are assigned importance scores (0-10) based on a weighted formula that considers:
124- Number of files that import this file (dependents)
125- Number of files this file imports (dependencies)
126- File type and extension (with TypeScript/JavaScript files getting higher base scores)
127- Location in the project structure (files in `src/` are weighted higher)
128- File naming (files like 'index', 'main', 'server', etc. get additional points)
129 
130A file that is central to the codebase (imported by many files) will have a higher score.
131 
132### Diagram Generation
133 
134The system uses a three-phase approach to generate valid Mermaid syntax:
1351. Collection Phase: Register all nodes and relationships
1362. Node Definition Phase: Generate definitions for all nodes before any references
1373. Edge Generation Phase: Create edges between defined nodes
138 
139This ensures all diagrams have valid syntax and render correctly. HTML output includes:
140- Responsive design that works on any device
141- Light/dark theme toggle with system preference detection
142- Client-side Mermaid rendering for optimal performance
143- Timestamp of generation
144 
145### Path Normalization
146 
147The system handles various path formats to ensure consistent file identification:
148- Windows and Unix path formats
149- Absolute and relative paths
150- URL-encoded paths
151- Cross-platform compatibility
152 
153### File Storage
154 
155All file tree data is stored in JSON files with the following structure:
156- Configuration metadata (filename, base directory, last updated timestamp)
157- Complete file tree with dependencies, dependents, importance scores, and summaries
158 
159## Technical Details
160 
161- **TypeScript/Node.js**: Built with TypeScript for type safety and modern JavaScript features
162- **Model Context Protocol**: Implements the MCP specification for integration with Cursor
163- **Mermaid.js**: Uses Mermaid syntax for diagram generation
164- **JSON Storage**: Uses simple JSON files for persistence
165- **Path Normalization**: Cross-platform path handling to support Windows and Unix
166- **Caching**: Implements caching for faster repeated operations
167 
168## Available Tools
169 
170The MCP server exposes the following tools:
171 
172### File Tree Management
173 
174- **list_saved_trees**: List all saved file trees
175- **create_file_tree**: Create a new file tree configuration for a specific directory
176- **select_file_tree**: Select an existing file tree to work with
177- **delete_file_tree**: Delete a file tree configuration
178 
179### File Analysis
180 
181- **list_files**: List all files in the project with their importance rankings
182- **get_file_importance**: Get detailed information about a specific file, including dependencies and dependents
183- **find_important_files**: Find the most important files in the project based on configurable criteria
184- **read_file_content**: Read the content of a specific file
185- **recalculate_importance**: Recalculate importance values for all files based on dependencies
186 
187### File Summaries
188 
189- **get_file_summary**: Get the stored summary of a specific file
190- **set_file_summary**: Set or update the summary of a specific file
191 
192### File Watching
193 
194- **toggle_file_watching**: Toggle file watching on/off
195- **get_file_watching_status**: Get the current status of file watching
196- **update_file_watching_config**: Update file watching configuration
197 
198### Diagram Generation
199 
200- **generate_diagram**: Create Mermaid diagrams with customizable options
201  - Output formats: Mermaid text (`.mmd`) or HTML with embedded rendering
202  - Diagram styles: default, dependency, directory, or hybrid views
203  - Filter options: max depth, minimum importance threshold
204  - Layout options: direction (TB, BT, LR, RL), node spacing, rank spacing
205 
206## Usage Examples
207 
208The 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.
209 
210### Analyzing a Project
211 
2121. Create a file tree for your project:
213   ```
214   create_file_tree(filename: "my-project.json", baseDirectory: "/path/to/project")
215   ```
216 
2172. Find the most important files:
218   ```
219   find_important_files(limit: 5, minImportance: 5)
220   ```
221 
2223. Get detailed information about a specific file:
223   ```
224   get_file_importance(filepath: "/path/to/project/src/main.ts")
225   ```
226 
227### Working with Summaries
228 
2291. Read a file's content to understand it:
230   ```
231   read_file_content(filepath: "/path/to/project/src/main.ts")
232   ```
233 
2342. Add a summary to the file:
235   ```
236   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.")
237   ```
238 
2393. Retrieve the summary later:
240   ```
241   get_file_summary(filepath: "/path/to/project/src/main.ts")
242   ```
243 
244### Generating Diagrams
245 
2461. Create a basic project structure diagram:
247   ```
248   generate_diagram(style: "directory", maxDepth: 3, outputPath: "diagrams/project-structure", outputFormat: "mmd")
249   ```
250 
2512. Generate an HTML diagram with dependency relationships:
252   ```
253   generate_diagram(style: "hybrid", maxDepth: 2, minImportance: 5, showDependencies: true, outputPath: "diagrams/important-files", outputFormat: "html")
254   ```
255 
2563. Customize the diagram layout:
257   ```
258   generate_diagram(style: "dependency", layout: { direction: "LR", nodeSpacing: 50, rankSpacing: 70 }, outputPath: "diagrams/dependencies", outputFormat: "html")
259   ```
260 
261### Using File Watching
262 
2631. Enable file watching for your project:
264   ```
265   toggle_file_watching()
266   ```
267 
2682. Check the current file watching status:
269   ```
270   get_file_watching_status()
271   ```
272 
2733. Update file watching configuration:
274   ```
275   update_file_watching_config(config: { 
276     debounceMs: 500, 
277     autoRebuildTree: true,
278     watchForNewFiles: true,
279     watchForDeleted: true,
280     watchForChanged: true
281   })
282   ```
283 
284### Testing
285 
286A testing framework (Vitest) is now included. Initial unit tests cover path normalization, glob-to-regexp conversion, and platform-specific path handling.
287 
288To run tests and check coverage:
289 
290```bash
291npm test
292npm run coverage
293```
294 
295### Recent Improvements
296 
297- Improved exclusions logic, ignoring hidden virtual environments (e.g., `.venv`) and other common unwanted directories. This helps keep dependency graphs clean and relevant.
298- Testing framework
299- Added more programming languages
300 
301## Future Improvements
302 
303- Add more sophisticated importance calculation algorithms
304- Enhance diagram customization options
305- Support for exporting diagrams to additional formats
306 
307## License
308 
309This project is licensed under the GNU General Public License v3 (GPL-3.0). See the [LICENSE](LICENSE) file for the full license text.
310