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

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

License

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