FileScopeMCP

What admica/FileScopeMCP MCP server does

The admica/FileScopeMCP MCP server gives coding agents a structured view of a local project. It tracks files, imports, exports, symbols, summaries, importance scores, and staleness. Agents can use this metadata to identify central files, inspect a file’s dependencies and change impact, locate symbols, and examine TypeScript or JavaScript call relationships.

Importance scores range from 0 to 10 and are based on dependency relationships, exports, and file location. The server also groups files into import-coupled communities and detects circular dependency chains. It supports TypeScript, JavaScript, Python, C, C++, Rust, Go, Ruby, Lua, Zig, PHP, C#, and Java, although the extraction method varies by language.

How it works

A local watcher observes the configured project and updates metadata when files change. TypeScript and JavaScript changes use AST-level diffing; other processing can use LLM analysis. Tree-sitter provides AST-based dependency extraction for TypeScript, JavaScript, Python, C, C++, and Rust, while Go, Ruby, Lua, Zig, PHP, C#, and Java use regular-expression-based import detection.

The optional broker places LLM work in a priority queue and sends requests to llama.cpp’s llama-server or another OpenAI-compatible HTTP API. Interactive work is prioritized over background summarization. Without an LLM service, file tracking, dependency analysis, symbol extraction, and call graphs still function, but generated summaries are unavailable.

Setup and configuration

The project requires Node.js 22 or newer, npm, and native build tools for dependencies including better-sqlite3 and tree-sitter. The documented setup flow clones the repository and runs ./build.sh; this installs dependencies, builds the project, and attempts to register it with Claude Code. The build can still complete if the Claude CLI is not installed.

A project can be selected through set_base_directory. The repository also documents direct registration for local agent runtimes using Node and dist/mcp-server.js. Optional LLM setup is handled separately with ./setup-llm.sh. Generated project data can be excluded from version control using .filescope/ and .filescope-daemon.log entries in .gitignore.

Tools and capabilities

The admica/FileScopeMCP MCP server exposes tools for:

• Checking broker, queue, LLM, and watcher state with status.
• Ranking files, listing the file tree, and reading detailed file summaries.
• Resolving symbols and finding callers or callees in TypeScript and JavaScript.
• Searching metadata across paths, symbols, summaries, and stated purpose.
• Listing files changed since a timestamp or Git SHA.
• Inspecting import communities and circular dependencies.
• Queueing files for summarization and manually updating summaries or importance scores.
• Excluding and removing tracked files or patterns.

An optional Nexus dashboard runs at localhost:1234 and provides read-only project, dependency graph, broker, and repository views.

Limitations and notes

Call-graph tools are specifically described for TypeScript and JavaScript. Symbol extraction through tree-sitter is listed for TypeScript, JavaScript, Python, Go, and Ruby, while dependency extraction has different coverage and precision across languages. LLM-generated summaries require a configured local or compatible HTTP LLM service. The exclude_and_remove operation is destructive, so it should be used with care.

The Nexus multi-repository watcher setup is documented for Linux systemd environments. Native modules may require platform-specific compiler tooling before installation succeeds.