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, Cursor AI, or as a standalone daemon. Supports 12 languages out of the box.

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 Python, JS/TS, C/C++, Rust, Go, Ruby, Lua, Zig, PHP, C#, Java. Finds circular dependencies too.

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.

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

That's it. Open a Claude Code session in any project and FileScopeMCP auto-initializes. Try:

find_important_files(limit: 5)
status()

Want AI summaries? Run ./setup-llm.sh for a platform-specific guide to setting up llama.cpp's llama-server — see docs/llm-setup.md for details. Without it, everything else still works.

Add to your project's .gitignore:

.filescope/
.filescope-daemon.log

MCP Tools

Tool	What it does
find_important_files	Top files by importance score
get_file_summary	Everything about a file: summary, concepts, change impact, deps, staleness
list_files	Full file tree with importance
detect_cycles	Find circular dependency chains
status	Broker connection, queue depth, LLM progress, watcher state
scan_all	Queue entire codebase for LLM processing
set_base_directory	Point at a different project
set_file_summary / set_file_importance	Manual overrides
exclude_and_remove	Drop files/patterns from tracking
get_cycles_for_file	Cycles involving a specific file

Nexus Dashboard

npm run nexus       # opens 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.

How It Works

Your code changes
    → file watcher picks it up
    → AST diff classifies the change (exports? types? body only?)
    → 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
LLM Setup	llama.cpp / llama-server installation — local, WSL2+Windows, or remote
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, cascade engine, storage

License

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