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

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

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

sudo ./monitoring/install.sh

Browse the dashboard at http://<host>: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

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:

./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=<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.