filescopemcp

Analyzes your codebase identifying important files based on dependency relationships. Generates diagrams and importance scores per file, helping AI assistant...

252 stars HTMLAI & Machine Learning Updated Nov 4, 2025

Documentation

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.

Prerequisites

Node.js >= 22 and npm (download)
Build tools for native modules (`better-sqlite3`, `tree-sitter`):
- Linux: `sudo apt install build-essential python3`
- macOS: `xcode-select --install`
- Windows: Visual Studio Build Tools with C++ workload

Quick Start

bash

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:

code

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:

bash

npm run install-claude-code   # or: npx filescope-install --claude-code

The 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 `` / `` 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`:

yaml

mcp_servers:
  filescope:
    command: "node"
    args: ["/path/to/FileScopeMCP/dist/mcp-server.js"]
    timeout: 120

Already 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`:

code

.filescope/
.filescope-daemon.log

LLM 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.

bash

sudo ./monitoring/install.sh

Browse the dashboard at `http://:8881/vmui/#/dashboards`. See monitoring/ for the layout and uninstall script.

MCP Tools

Tool	What it does
`status`	Broker connection, queue depth, LLM progress, watcher state
`find_important_files`	Top files by importance score with dependency counts
`get_file_summary`	Everything about a file: summary, concepts, change impact, exports, deps, staleness
`list_files`	Full file tree (no args) or flat top-N by importance (with `maxItems`)
`find_symbol`	Resolve a symbol name to file + line range; supports prefix match via trailing `*`
`find_callers`	Find all symbols that call a named symbol (TS/JS call graph)
`find_callees`	Find all symbols that a named symbol calls (TS/JS call graph)
`search`	Search file metadata across symbols, summaries, purpose, and paths
`list_changed_since`	Files changed since a timestamp or git SHA
`get_communities`	Louvain-clustered file groups by import coupling
`detect_cycles`	Find circular dependency chains
`get_cycles_for_file`	Cycles involving a specific file
`scan_all`	Queue files for LLM summarization via the broker
`set_base_directory`	Point at a different project
`set_file_summary`	Manually set or override a file's LLM summary
`set_file_importance`	Manually set a file's importance score (0-10)
`exclude_and_remove`	Drop files/patterns from tracking (destructive)

Nexus Dashboard

bash

npm run build:nexus  # one-time build (API + UI)
npm run nexus        # starts at http://localhost:1234

A 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:

bash

./scripts/nexus.sh install-watchers     # writes the unit, enables it, starts it
systemctl --user status filescope-watchers.service
./scripts/nexus.sh uninstall-watchers   # symmetric removal

The unit launches `scripts/watchers.mjs`, which spawns one `dist/mcp-server.js --base-dir=` 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

code

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 answers

Everything 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
AGENTS.md	Cross-agent context file — MCP registration, broker config, architecture (read by Hermes, Codex, OpenClaw)
FileScopeMCP Skill	Portable skill file — tool reference, workflows, tips for agents using FileScopeMCP
LLM Setup	llama.cpp / llama-server installation — Linux/macOS native (default), WSL2+Windows, or remote LAN
Configuration	Per-project config, broker config, ignore patterns
MCP Clients	Setup for Claude Code, Cursor AI, daemon mode
Troubleshooting	Common issues and fixes
Internals	Dependency detection, importance formula, symbol extraction, call-site edges, storage
LLM Monitoring	Optional VictoriaMetrics + vmui dashboard for the local llama-server

License

Frequently asked questions

What is filescopemcp?

filescopemcp is Analyzes your codebase identifying important files based on dependency relationships. Generates diagrams and importance scores per file, helping AI assistant...