FileScope MCP server for AI agents

FileScopeMCP is a TypeScript-based tool that analyzes your codebase to identify important files based on dependency relationships. It generates importance scores, tracks bidirectional dependencies, and allows you to add custom summaries for files, making this information available to AI tools through Cursor's Model Context Protocol.

Installation

Prerequisites

Node.js (v18 or later)
Git

Setup Steps

Clone the repository:

git clone https://github.com/admica/FileScopeMCP.git

Build the project:

For Windows:
```
build.bat
```
For Linux:
```
build.sh
```

Configure your Cursor editor by adding the generated mcp.json to your project's .cursor directory:

For Windows:

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

For Linux (WSL):

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

Update the --base-dir argument to point to your project's base path.

Usage

Managing File Trees

Create a new file tree for your project:

create_file_tree(filename: "my-project.json", baseDirectory: "/path/to/project")

List all saved file trees:

list_saved_trees()

Select an existing file tree to work with:

select_file_tree(filename: "my-project.json")

Analyzing Files

Find the most important files in your project:

find_important_files(limit: 5, minImportance: 5)

Get detailed information about a specific file:

get_file_importance(filepath: "/path/to/project/src/main.ts")

List all files with their importance rankings:

list_files()

Working with File Summaries

Read a file's content:

read_file_content(filepath: "/path/to/project/src/main.ts")

Add or update a file summary:

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.")

Retrieve a file summary:

get_file_summary(filepath: "/path/to/project/src/main.ts")

Generating Diagrams

Create a directory structure diagram:

generate_diagram(style: "directory", maxDepth: 3, outputPath: "diagrams/project-structure", outputFormat: "mmd")

Generate an HTML diagram showing dependencies:

generate_diagram(style: "hybrid", maxDepth: 2, minImportance: 5, showDependencies: true, outputPath: "diagrams/important-files", outputFormat: "html")

Customize diagram layout:

generate_diagram(style: "dependency", layout: { direction: "LR", nodeSpacing: 50, rankSpacing: 70 }, outputPath: "diagrams/dependencies", outputFormat: "html")

File Watching

Enable or disable file watching:

toggle_file_watching()

Check file watching status:

get_file_watching_status()

Update file watching configuration:

update_file_watching_config(config: { 
  debounceMs: 500, 
  autoRebuildTree: true,
  watchForNewFiles: true,
  watchForDeleted: true,
  watchForChanged: true
})

Supported Languages

FileScopeMCP can detect dependencies in these languages:

Python
JavaScript/TypeScript
C/C++
Rust
Lua
Zig

Quick Start with AI Integration

The simplest way to get started is to enable this MCP in Cursor and instruct the AI to use it. When the MCP starts, it automatically builds an initial JSON tree. You can then ask the AI to generate summaries for your important files and use the set_file_summary function to add them.

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.