FileScopeMCP Server

How to use

You work with an MCP client to connect to the FileScopeMCP server and access file importance, dependencies, and summaries. Start by configuring a file tree for your project, then query for the most important files, inspect dependencies, and add summaries for key files. Use the generated diagrams to visualize relationships and quickly understand where critical files sit in your codebase.

How to install

Prerequisites: you need Node.js installed on your system. You may also use a UNIX-like shell for convenience if you are on Windows or Linux.

Step 1: Prepare your environment by obtaining the FileScopeMCP setup with build scripts available for Windows and Linux.

Step 2: Build the project to generate the server bundle and configuration mapping.

Windows users may run the build script and then configure MCP to start the server from the generated bundle.

Step 3: Create the MCP connection configuration for your Cursor client. Use the following stdio connection to run the local server via Node.js after building the project.

{
  "mcpServers": {
    "FileScopeMCP": {
      "command": "node",
      "args": ["<build script sets this>/mcp-server.js","--base-dir=C:/Users/admica/my/project/base"],
      "transport": "stdio",
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Linux users can run the Linux build script and then connect using the provided WSL-based start command.

{
  "mcpServers": {
    "FileScopeMCP": {
      "command": "wsl",
      "args": ["-d", "Ubuntu-24.04", "/home/admica/FileScopeMCP/run.sh"],
      "transport": "stdio",
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Additional setup notes

If you already built the project, ensure the base directory path in the command matches your actual project location. The FileScopeMCP server will initialize a file tree and start collecting data for analysis.

Configuration and usage notes

The server stores data in JSON format on disk and supports multiple project workspaces. You can switch between file trees for different project areas and use the available tools to list files, inspect importance, read file content, and manage summaries.

Using the FileScopeMCP, you can generate Mermaid diagrams to visualize dependencies and directory structures, and you can filter diagrams by depth and importance to focus on critical parts of your codebase.

Security and best practices

Limit access to the MCP server to trusted clients and monitor any changes to file trees or summaries. Keep summaries concise and aligned with the project goals to avoid clutter in the AI context.

fileImportance

Analyzes and scores files on a 0-10 scale based on their role, dependencies, location, and common naming patterns to help identify central files in the project.

dependencyTracking

Maps bidirectional relationships between files, showing dependents (files that import a given file) and dependencies (files imported by a given file), including local vs package dependencies.

visualization

Generates Mermaid diagrams and HTML reports to visualize the file graph, with options for different views and depth limits.

fileSummaries

Allows adding and retrieving human or AI-generated summaries for files, with persistence across server restarts.

projectManagement

Supports multiple file trees for different project areas, enabling easy switching and caching for faster operations.

persistence

Stores all data on disk in JSON format, enabling quick reloads of existing file trees and tracking last updated timestamps.