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.

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

Copyright (c) 2026 admica. All rights reserved. See LICENSE.