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 Ollama (or any OpenAI-compatible 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

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? Set up Ollama with ./setup-llm.sh — see docs/ollama-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
Ollama Setup	LLM installation — local, WSL, 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