Internals

Technical details on how FileScopeMCP works under the hood.

Dependency Detection

Import patterns detected per language:

Language	Patterns
Python	import, from ... import
JavaScript / TypeScript	import, require(), dynamic import()
C / C++	#include
Rust	use, mod
Go	import with go.mod module resolution
Ruby	require, require_relative with .rb probing
Lua	require
Zig	@import
PHP	require, require_once, include, include_once, use
C#	using
Java	import

Importance Calculation

Scores (0-10) from a weighted formula. The algorithm is versioned via importance_algorithm_version in kv_state — when the formula changes (new file types, weight tweaks, etc.), the coordinator auto-busts every file's cached score on the next init so reads never return values computed by an older version.

Factor	Max contribution
Incoming dependents (files that import this file)	+3
Outgoing dependencies (files this file imports)	+2
Package dependencies imported	+1
Location (src/, app/, lib/, core/ weighted higher)	varies
Significant names (index, main, server, app, config, types, Makefile, CMakeLists, etc., case-insensitive)	varies

File-type base scores (additive, current as of the latest algorithm version):

Extension(s)	Base score
.ts, .tsx	+3
.js, .jsx, .mjs, .cjs	+2
.py, .go, .rb, .php	+2
.c, .cpp, .cc, .cxx, .h, .hpp, .hh, .hxx	+2
.sh, .sql	+1
package.json, tsconfig.json, etc. (config JSON)	+3; other .json +1
README.md (any case)	+2; other .md +1
go.mod	+3
Gemfile	+3

Autonomous Update Pipeline

When a file event fires:

1. Debounce — events coalesced per filePath:eventType key (default 2s)
2. Mutex — all mutations serialized through AsyncMutex
3. Semantic change detection — tree-sitter AST diff (TS/JS) or LLM-powered diff (all other languages) classifies the change
4. Incremental update — re-parses the changed file, diffs dependency lists, patches reverse-dependency map, recalculates importance
5. Cascade engine — BFS propagates staleness to transitive dependents if exports/types changed; body-only changes affect only the changed file
6. LLM broker — picks up stale files and regenerates summaries, concepts, and change impact in priority order

Freshness Validation

Two complementary strategies:

• Startup sweep — runs once at initialization. Compares every tracked file against the filesystem to detect adds, deletes, and modifications that occurred while the server was offline.
• Per-file mtime check — when you call get_file_summary, the system compares current mtime against the last recorded value. If changed, the file is immediately flagged stale and queued for re-analysis.

Symbol Extraction

Tree-sitter AST parsing extracts top-level symbols (functions, classes, interfaces, types, enums, consts, modules, structs) from source files. Symbols are stored in the symbols table with name, kind, start/end line, export status, and owning file path.

Extraction runs per-language:

Language	Kinds extracted	Export rule
TypeScript / JavaScript	function, class, interface, type, enum, const	export keyword
Python	function, class (top-level only, decorator-aware)	!name.startsWith('_')
Go	function, method, struct, interface, type, const	Uppercase first char
Ruby	function, class, module, const	Always exported (no keyword)

Ruby attr_accessor / attr_reader / attr_writer are not indexed (synthesized at runtime, not in AST). Reopened Ruby classes produce multiple symbol rows with the same name.

Call-Site Edges (TS/JS)

For TypeScript and JavaScript files, a second AST pass over the already-parsed tree extracts call expressions and resolves them to symbol-level edges in the symbol_dependencies table:

1. Local resolution — callee name matches a symbol defined in the same file (confidence 1.0)
2. Imported resolution — callee name matches a symbol imported from another file, verified against the DB (confidence 0.8)
3. Unresolvable — silently discarded (no edge created)

Barrel files (index.ts etc.) are excluded to prevent over-matching. Ambiguous names (same name imported from multiple files) are discarded. Self-calls (recursion) are filtered from query results.

Call-site edges for Python, Go, and Ruby are not yet implemented.

Community Detection

Louvain clustering on the local import graph groups tightly-coupled files into communities. Each community is represented by its highest-importance member. Communities are lazily recomputed only when the dependency graph changes (dirty flag tracked in DB).

Cycle Detection

1. Loads all local import edges from SQLite in a single batch query
2. Runs iterative Tarjan's SCC algorithm on the directed dependency graph
3. Filters out trivial SCCs (single files with no self-loop)
4. Returns cycle groups listing all participating files

Storage

All data in .filescope/data.db (SQLite, WAL mode):

Table	Purpose
files	Metadata, staleness flags, summary, concepts, change_impact
file_dependencies	Directed import edges with edge type, confidence, and weight
symbols	Extracted symbols (name, kind, startLine, endLine, isExport) per file
symbol_dependencies	Call-site edges between symbols (caller → callee with confidence)
file_communities	Louvain community assignments
kv_state	Key-value store for bulk migration gates and feature flags
schema_version	Migration versioning

Auto-migration: on first run, any legacy JSON tree files are imported into SQLite automatically. Schema migrations run automatically on startup.

LLM Broker Architecture

The broker is a standalone Node.js process that owns all LLM communication (llama.cpp's llama-server or any OpenAI-compatible HTTP API):

• IPC — Unix domain socket at ~/.filescope/broker.sock, NDJSON protocol
• Queue — in-memory priority queue (importance DESC, created_at ASC)
• Tiers — interactive (tier 1) > cascade (tier 2) > background (tier 3)
• Dedup — one pending job per file+type per repo, latest content wins
• Timeout — jobTimeoutMs, schema default 120 s; shipped broker.default.json template overrides to 300 s, so fresh installs run at 5 min until the user edits the field
• Auto-spawn — first MCP instance spawns the broker if broker.sock is missing
• Stats — per-repo token totals persisted to ~/.filescope/stats.json