FileScopeMCP

FileScopeMCP is a codebase analysis tool for AI programming assistants, with the core goal of enabling AI to obtain accurate answers when answering questions about code without reading the source code. It achieves this by monitoring code, ranking files by importance, mapping dependencies, and continuously updating AI-generated summaries in the background.

Main Capabilities

• Importance Ranking: Each file receives a score from 0-10 based on the number of dependents, exported content, and its location, allowing the LLM to see key files first.
• Dependency Mapping: Supports bidirectional import tracking for all supported languages. Uses AST-level extraction (tree-sitter) for TypeScript/JavaScript, Python, C, C++, and Rust; uses regex-based extraction for Go, Ruby, Lua, Zig, PHP, C#, and Java. It can also detect circular dependencies.
• Symbol Intelligence: Extracts functions, classes, interfaces, types, enums, constants, modules, and structs for TypeScript, JavaScript, Python, Go, and Ruby via tree-sitter.find_symbol Can resolve names to files and line ranges;find_callers and find_callees map call graphs for TS/JS, helping AI answer "who calls this function" before refactoring.
• Continuous Updates: A file watcher plus semantic change detection, with metadata automatically updated. AST-level diffing is performed for TS/JS, while other languages use LLM-driven analysis, reprocessing only the parts that actually changed.
• LLM Agent: A background process coordinates all AI work through llama.cpp's llama-server (or any OpenAI-compatible HTTP API). A priority queue ensures interactive queries take precedence over background processing, and it can run on a single GPU.
• Nexus Dashboard: A Web UI at localhost:1234 that enables visual exploration of the codebase across all repositories, including interactive dependency graphs, file detail panels, live agent activity, and health monitoring for each repository.

Usage

Requirements

• Node.js >= 22 and npm
• Build tools for native modules (better-sqlite3, tree-sitter):
  • Linux:sudo apt install build-essential python3
  • macOS：xcode-select --install
  • Windows: Install Visual Studio Build Tools with the C++ workload

Installation and Registration

Running ./build.sh will register FileScopeMCP globally through claude mcp add --scope user (idempotent; can be rerun with npm run register-mcp ). If the claude CLI is missing, the build will still succeed—for other MCP clients, see docs/mcp-clients.md.

Open a Claude Code session in any project, and FileScopeMCP will initialize automatically. MCP tools will appear automatically, and AI can call them directly in the conversation.

Other Integrations

• Agent Runtimes (Hermes, Codex, OpenClaw): Discover FileScopeMCP through the repository's AGENTS.md, which contains the MCP registration configuration, agent/LLM settings, and a portable skill file pointing to skills/filescope-mcp/SKILL.md. Hermes can be added to ~/.hermes/config.yaml.
• Existing Local LLM: Edit ~/.filescope/broker.json and set baseURL to the LLM endpoint to reuse it.
• LLM Summaries (Optional): Run ./setup-llm.sh to get platform-specific llama-server setup guidance. On Linux, you can also sudo ./setup-llm.sh --install-service Register llama-server as a systemd unit. Without llama-server, file tracking, dependencies, symbols, and call graphs still work, just without LLM-generated summaries.

Data Storage

Each project's data is stored in .filescope/data.db (SQLite, WAL mode). The broker coordinates LLM work across all repositories via the Unix socket ~/.filescope/broker.sock.

Multi-Repository Watcher (Linux systemd only)

For users who want all repositories in ~/.filescope/nexus.json to be continuously watched, a per-repository watcher user unit can be installed. This unit starts scripts/watchers.mjs, spawns one dist/mcp-server.js --base-dir=<repo> subprocess for each registered repository, and supervises them (automatic restart on exit, clean shutdown on SIGTERM). Logs are located at ~/.filescope/watchers.log and ~/.filescope/watcher-logs/*.log.

Use Cases

• Let AI coding assistants quickly understand large or unfamiliar codebases
• Analyze function call relationships before refactoring
• Visually explore multi-repository dependency structures
• Run LLM summary generation on a local GPU

Limitations

• Requires Node.js >= 22 and native module build tools
• The LLM summary feature requires llama-server or an OpenAI-compatible API
• The multi-repository watcher only supports Linux systemd
• Dependency extraction for some languages (Go, Ruby, Lua, Zig, PHP, C#, Java) is regex-based rather than AST-based
• Symbol extraction only supports TypeScript, JavaScript, Python, Go, Ruby
• Call graph mapping only supports TS/JS
• Copyright is owned by admica; see LICENSE for specific licensing terms