TypeScript MCP server that scans a codebase, calculates per-file importance from dependency graphs, stores results in JSON and exposes analysis/visualisation tools (Mermaid diagrams, summaries, file watching) through Model Context Protocol.
https://github.com/admica/FileScopeMCPYou know the drill. You inherit a new project, join a team, or dive into an open source codebase. First few hours? Clicking through random files, trying to figure out what actually matters. Which files are the architectural pillars? Which ones can you safely ignore?
FileScopeMCP ends that exploration phase. This MCP server analyzes your entire codebase in seconds, ranks every file by importance, maps all dependencies, and feeds that context directly to your AI assistant.
Every time you open an unfamiliar codebase, you're essentially playing detective. You're scanning file names, looking for main.py or index.ts, checking imports, trying to mentally build a dependency map. That's not development work—that's archaeology.
FileScopeMCP treats your codebase like a graph problem and solves it algorithmically. It calculates importance scores (0-10) for every file based on dependency relationships, file location, naming patterns, and connection centrality. The files that matter most bubble to the top automatically.
Smart File Ranking: Every file gets an importance score. The entry points, core modules, and architectural anchors score highest. Utility files and one-off scripts score lower. No more guessing which files to read first.
Bidirectional Dependency Mapping: See exactly which files import what, and which files are imported by what. Supports Python, TypeScript/JavaScript, C/C++, Rust, Lua, Zig, C#, and Java out of the box.
Visual Architecture: Generate Mermaid diagrams that show your codebase structure at a glance. Color-coded by importance, filterable by depth, exportable to HTML with interactive themes.
AI Integration: All this analysis flows directly to your AI assistant through Cursor's MCP protocol. Ask "what are the most important files in this project?" and get ranked answers with context.
Instead of spending 30 minutes clicking through directories to understand a React app's structure, you run FileScopeMCP and immediately see that src/App.tsx (score: 8.5) is your main component, src/api/client.ts (score: 7.2) handles all network logic, and src/utils/helpers.ts (score: 3.1) can wait.
For debugging? Ask your AI assistant "show me files that depend on the authentication module" and get an exact list instead of running grep commands and parsing results manually.
When onboarding to a Python service with 200+ files, the importance ranking cuts through the noise. You'll focus on the 12 files that actually drive the application instead of getting lost in test fixtures and configuration helpers.
Multiple Project Support: Manage separate analysis trees for different codebases or project areas. Switch between frontend, backend, and mobile analyses seamlessly.
File Watching: Enable automatic reanalysis when your codebase changes. Importance scores and dependency maps stay current as you develop.
Persistent Summaries: Add human or AI-generated summaries to critical files. These persist across restarts and help your AI assistant provide better context.
Cross-Platform: Works on Windows, Linux, and WSL setups. The build scripts handle platform-specific configurations automatically.
Clone the repo, run the build script, and add the generated configuration to your Cursor MCP settings. Point it at your project directory and you're analyzing codebases in under two minutes.
{
"mcpServers": {
"FileScopeMCP": {
"command": "node",
"args": ["path/to/mcp-server.js", "--base-dir=/your/project/path"],
"transport": "stdio"
}
}
}
The moment your MCP server starts, it builds an initial analysis. From there, you can ask your AI assistant to summarize important files, generate dependency diagrams, or explain the codebase architecture based on actual structural analysis rather than surface-level file scanning.
Static analysis at the dependency level reveals architectural truth. A file's importance isn't subjective—it's measurable through connection patterns, naming conventions, and structural position. FileScopeMCP quantifies this and makes it queryable through your existing AI workflow.
You'll spend less time exploring, more time building, and your AI assistant will give better answers because it understands which parts of your codebase actually matter.