FileScopeMCP
The FileScopeMCP server helps understand codebase structure and dependencies through these capabilities:
File Tree Management: Create, select, list, and delete file tree configurations for different projects
Dependency Analysis: Track bidirectional dependencies across multiple languages (Python, JS/TS, C/C++, Rust, Lua, Zig)
Importance Handling: Calculate, recalculate, and manually set file importance scores (0-10) based on dependencies
File Operations: List files with importance rankings, find important files, and read file content
File Summaries: Add, retrieve, and persist human or AI-generated summaries for specific files
Visualization: Generate Mermaid diagrams in various styles (dependency, directory, hybrid) with filtering and layout options
Auto-updates: Toggle file watching to automatically update when files change
Persistence: Store all file tree data including dependencies, importance, and summaries in JSON files
Analyzes C/C++ source files by detecting #include directives to map dependencies and calculate importance scores for files in C/C++ projects.
Analyzes JavaScript files by detecting import statements and require() calls to track dependencies and assign importance scores to files in JavaScript projects.
Analyzes Lua source files by detecting require statements to map dependencies and calculate importance scores for files in Lua projects.
Generates Mermaid diagrams to visualize file relationships with color-coded visualization based on importance scores for dependency graphs or directory trees.
Analyzes Python source files by detecting import and from...import statements to map dependencies and calculate importance scores for files in Python projects.
Analyzes Rust source files by detecting use and mod statements to map dependencies and calculate importance scores for files in Rust projects.
Provides enhanced support for TypeScript projects by analyzing import statements, tracking dependencies, and assigning higher base importance scores to TypeScript files.
Analyzes Zig source files by detecting @import directives to map dependencies and calculate importance scores for files in Zig projects.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@FileScopeMCP show me the most important files in my project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
FileScopeMCP
Your AI already knows how to code. Now it knows your codebase.
FileScopeMCP watches your code, ranks every file by importance, maps all dependencies, and keeps AI-generated summaries fresh in the background. When your LLM asks "what does this file do?" — it gets a real answer without reading the source.
Works with Claude Code, Hermes Agent, Codex, OpenClaw, Cursor AI, or as a standalone daemon. Supports TypeScript, JavaScript, Python, C, C++, Rust, Go, Ruby, Lua, Zig, PHP, C#, and Java.
Key Features
Importance ranking — every file scored 0-10 based on how many things depend on it, what it exports, and where it lives. Your LLM sees the critical files first.
Dependency mapping — bidirectional import tracking across all supported languages. AST-level extraction (tree-sitter) for TS/JS, Python, C, C++, and Rust; regex-based for Go, Ruby, Lua, Zig, PHP, C#, and Java. Finds circular dependencies too.
Symbol intelligence — extracts functions, classes, interfaces, types, enums, consts, modules, and structs via tree-sitter for TypeScript, JavaScript, Python, Go, and Ruby. find_symbol resolves names to file + line range. find_callers and find_callees map the call graph for TS/JS so your AI can answer "who calls this function?" before refactoring.
Always fresh — file watcher + semantic change detection means metadata updates automatically. AST-level diffing for TS/JS, LLM-powered analysis for everything else. Only re-processes what actually changed.
LLM broker — a background process coordinates all AI work through llama.cpp's llama-server (or any OpenAI-compatible HTTP API). Priority queue ensures interactive queries beat background processing. Runs on a single GPU.
Nexus dashboard — a web UI at localhost:1234 that lets you visually explore your codebase across all your repos. Interactive dependency graphs, file detail panels, live broker activity, and per-repo health monitoring.
Related MCP server: GonMCPtool
Prerequisites
Node.js >= 22 and npm (download)
Build tools for native modules (
better-sqlite3,tree-sitter):Linux:
sudo apt install build-essential python3macOS:
xcode-select --installWindows: Visual Studio Build Tools with C++ workload
Quick Start
git clone https://github.com/admica/FileScopeMCP.git
cd FileScopeMCP
./build.sh # installs deps, compiles, registers with Claude Code./build.sh registers FileScopeMCP globally via claude mcp add --scope user (idempotent; re-run with npm run register-mcp). If the claude CLI is missing, the build still succeeds — see docs/mcp-clients.md for other MCP clients.
Open a Claude Code session in any project and FileScopeMCP auto-initializes. The MCP tools appear automatically — your AI can call them directly during conversation:
find_important_files(limit: 5)
status()Opinionated Claude Code install (recommended)
For a richer install that adds a project priming CLAUDE.md and points to optional hook templates:
npm run install-claude-code # or: npx filescope-install --claude-codeThe command is layered, not invasive — it never auto-writes to your .claude/settings.json. Hook templates are documented at docs/claude-code-hooks.md; paste them into your settings if and when you want them. The CLAUDE.md primer is wrapped in <!-- BEGIN filescope --> / <!-- END filescope --> markers so it can be cleanly added, replaced, or removed without touching surrounding content. See ROADMAP.md Phase 1 for the design rationale.
Agent Runtimes (Hermes, Codex, OpenClaw)
Agent runtimes discover FileScopeMCP via the repo's AGENTS.md, which includes MCP registration config, broker/LLM setup, and a pointer to the portable skill file at skills/filescope-mcp/SKILL.md.
Hermes — add to ~/.hermes/config.yaml:
mcp_servers:
filescope:
command: "node"
args: ["/path/to/FileScopeMCP/dist/mcp-server.js"]
timeout: 120Already have a local LLM running? Point the broker at it — edit ~/.filescope/broker.json and set baseURL to your LLM's endpoint. See AGENTS.md for details.
LLM Summaries (Optional)
Run ./setup-llm.sh for a platform-specific guide to setting up llama.cpp's llama-server — see docs/llm-setup.md for details. On Linux you can also sudo ./setup-llm.sh --install-service to register llama-server as a systemd unit (logs flow to journalctl, OOM-protected, auto-restart on boot). The flag is a no-op under WSL2 since llama-server runs on the Windows host there. Without llama-server entirely, everything else still works (file tracking, dependencies, symbols, call graphs — just no LLM-generated summaries). If your agent runtime already has a local LLM, configure the broker to reuse it instead.
Add to your project's .gitignore:
.filescope/
.filescope-daemon.logLLM Monitoring (Optional)
If llama-server is running locally, an optional VictoriaMetrics + vmui stack gives you a single-pane dashboard for VRAM, RAM, swap, throughput, and cumulative work. Total resident footprint ~120 MB, capped via systemd cgroups so a misbehaving exporter can't OOM-kill llama-server.
sudo ./monitoring/install.shBrowse the dashboard at http://<host>:8881/vmui/#/dashboards. See monitoring/ for the layout and uninstall script.
MCP Tools
Tool | What it does |
| Broker connection, queue depth, LLM progress, watcher state |
| Top files by importance score with dependency counts |
| Everything about a file: summary, concepts, change impact, exports, deps, staleness |
| Full file tree (no args) or flat top-N by importance (with |
| Resolve a symbol name to file + line range; supports prefix match via trailing |
| Find all symbols that call a named symbol (TS/JS call graph) |
| Find all symbols that a named symbol calls (TS/JS call graph) |
| Search file metadata across symbols, summaries, purpose, and paths |
| Files changed since a timestamp or git SHA |
| Louvain-clustered file groups by import coupling |
| Find circular dependency chains |
| Cycles involving a specific file |
| Queue files for LLM summarization via the broker |
| Point at a different project |
| Manually set or override a file's LLM summary |
| Manually set a file's importance score (0-10) |
| Drop files/patterns from tracking (destructive) |
Nexus Dashboard
npm run build:nexus # one-time build (API + UI)
npm run nexus # starts at http://localhost:1234A read-only web dashboard that connects to every FileScopeMCP repo on your machine:
Project view — file tree with importance heat colors and staleness indicators, click any file for full metadata
Dependency graph — interactive Cytoscape.js visualization, filter by directory, click nodes to inspect
System view — live broker status, per-repo token usage, streaming activity log
Settings — manage which repos appear, remove or restore from blacklist
Auto-discovers repos by scanning for .filescope/data.db directories. No configuration needed.
Multi-Repo Watchers (systemd, Linux only)
For users who want every repo in ~/.filescope/nexus.json watched continuously — not only when an MCP client is open — install the per-repo watchers user unit:
./scripts/nexus.sh install-watchers # writes the unit, enables it, starts it
systemctl --user status filescope-watchers.service
./scripts/nexus.sh uninstall-watchers # symmetric removalThe unit launches scripts/watchers.mjs, which spawns one dist/mcp-server.js --base-dir=<repo> child per registered repo and supervises them (auto-restart on exit, SIGTERM-clean shutdown). The unit Requires=filescope-broker.service — install the broker user unit yourself; this command does not ship one.
Logs: ~/.filescope/watchers.log (supervisor) and ~/.filescope/watcher-logs/*.log (per-repo children).
How It Works
Your code changes
→ file watcher picks it up
→ AST diff classifies the change (exports? types? body only?)
→ symbols extracted (functions, classes, types, etc.)
→ call-site edges resolved (TS/JS: who calls what)
→ importance scores recalculated
→ staleness cascades to dependents (only if exports/types changed)
→ LLM broker regenerates summaries, concepts, change impact
→ your AI's next query gets fresh answersEverything lives in .filescope/data.db (SQLite, WAL mode) per project. The broker coordinates LLM work across all your repos via a Unix socket at ~/.filescope/broker.sock.
Documentation
Doc | What's in it |
Cross-agent context file — MCP registration, broker config, architecture (read by Hermes, Codex, OpenClaw) | |
Portable skill file — tool reference, workflows, tips for agents using FileScopeMCP | |
llama.cpp / llama-server installation — Linux/macOS native (default), WSL2+Windows, or remote LAN | |
Per-project config, broker config, ignore patterns | |
Setup for Claude Code, Cursor AI, daemon mode | |
Common issues and fixes | |
Dependency detection, importance formula, symbol extraction, call-site edges, storage | |
Optional VictoriaMetrics + vmui dashboard for the local llama-server |
License
Copyright (c) 2026 admica. All rights reserved. See LICENSE.
Available Tools
14 toolscreate_file_treeC
Create or load a file tree configuration
Inputs: baseDirectory (required), filename (required).
debug_list_all_filesB
List all file paths in the current file tree
delete_file_treeC
Delete a file tree configuration
Inputs: filename (required).
find_important_filesC
Find the most important files in the project
Inputs: limit, minImportance.
generate_diagramC
Generate a Mermaid diagram for the current file tree
Inputs: style (required), layout, maxDepth, minImportance, +3 more.
get_file_importanceC
Get the importance ranking of a specific file
Inputs: filepath (required).
get_file_summaryC
Get the summary of a specific file
Inputs: filepath (required).
list_filesB
List all files in the project with their importance rankings
list_saved_treesB
List all saved file trees
read_file_contentC
Read the content of a specific file
Inputs: filepath (required).
recalculate_importanceB
Recalculate importance values for all files based on dependencies
select_file_treeC
Select an existing file tree to work with
Inputs: filename (required).
set_file_importanceC
Manually set the importance ranking of a specific file
Inputs: filepath (required), importance (required).
set_file_summaryC
Set the summary of a specific file
Inputs: filepath (required), summary (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Every tool has a clearly distinct purpose with no ambiguity. Tools like 'create_file_tree', 'delete_file_tree', and 'select_file_tree' handle tree management, while 'read_file_content', 'get_file_summary', and 'set_file_summary' focus on file content operations. The separation between listing functions ('debug_list_all_files', 'list_files', 'list_saved_trees') and importance calculations ('get_file_importance', 'set_file_importance', 'recalculate_importance') is well-defined, preventing misselection.
All tool names follow a consistent verb_noun pattern with snake_case throughout. Verbs like 'create', 'delete', 'list', 'get', 'set', 'read', 'find', 'generate', 'select', and 'recalculate' are used predictably with corresponding nouns. There are no deviations in naming conventions, making the tool set highly readable and predictable.
With 14 tools, the count is well-scoped for managing file trees and analyzing file importance in a project. Each tool earns its place by covering distinct aspects such as tree configuration, file listing, content access, importance ranking, and diagram generation. This number is neither too sparse nor overwhelming, fitting the server's purpose effectively.
The tool surface provides complete CRUD/lifecycle coverage for file tree management and file analysis. It includes creation, selection, listing, and deletion of trees, along with operations for reading, summarizing, and setting importance for files. Tools like 'recalculate_importance' and 'generate_diagram' add advanced functionality, leaving no obvious gaps that would cause agent failures in this domain.
Maintenance
Related MCP Connectors
Coding agents in multi-service codebases routinely rebuild existing helpers, trust stale type definitions, and modify API contracts without knowing who consumes them. Carrick solves this by indexing your entire TypeScript ecosystem across service and repository boundaries. By integrating deeply with the TypeScript compiler, Carrick traces every route, type, and cross-service call while recording function behaviour so agents search by intent rather than name. Delivered via MCP for AI agents and LSP for IDEs, Carrick ensures models see existing endpoints and utilities before generating new code. The scanner is source-available and runs from your CLI or CI pipeline.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Codebase intelligence for AI coding agents: graph, git history, docs, decisions, code health.
Related MCP Servers
- FlicenseBqualityDmaintenanceA Model Context Protocol server that helps AI code editors locate TypeScript symbol definitions in codebases, particularly useful for finding original definitions of imported symbols and classes.1-
- AlicenseCqualityDmaintenanceA TypeScript-based Model Context Protocol toolkit that enables AI to interact with code files, manage translations, build projects, and search for files and code content.335MIT
- AlicenseNot gradedqualityDmaintenanceA structural codebase indexer that exposes 18 tools via the Model Context Protocol for AI-assisted code navigation, enabling efficient querying of functions, classes, dependencies, and call chains without reading entire files.214 PyPI63AGPL 3.0
- AlicenseNot gradedqualityFmaintenanceEnables Claude Code to query a TypeScript dependency graph and retrieve the minimal set of files needed for code review, implementation, or debugging.MIT