admica/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**, **Hermes Agent**, **Codex**, **OpenClaw**, **Cursor AI**, or as a standalone daemon. Supports TypeScript, JavaScript, Python, C, C++, Rust, Go, Ruby, Lua, Zig, PHP, C#, and Java.
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 all supported languages. AST-level extraction (tree-sitter) for TS/JS, Python, C, C++, and Rust; regex-based for Go, Ruby, Lua, Zig, PHP, C#, and Java. Finds circular dependencies too.
**Symbol intelligence** — extracts functions, classes, interfaces, types, enums, consts, modules, and structs via tree-sitter for TypeScript, JavaScript, Python, Go, and Ruby. find_symbol resolves names to file + line range. find_callers and find_callees map the call graph for TS/JS so your AI can answer "who calls this function?" before refactoring.
**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.
Prerequisites
- **Node.js >= 22** and npm (download)
- **Build tools** for native modules (better-sqlite3, tree-sitter):
- Linux: sudo apt install build-essential python3
- macOS: xcode-select --install
- Windows: Visual Studio Build Tools with C++ workload
Quick Start
./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 other MCP clients.
Open a Claude Code session in any project and FileScopeMCP auto-initializes. The MCP tools appear automatically — your AI can call them directly during conversation:
Opinionated Claude Code install (recommended)
For a richer install that adds a project priming CLAUDE.md and points to optional hook templates:
The command is layered, not invasive — it never auto-writes to your .claude/settings.json. Hook templates are documented at docs/claude-code-hooks.md; paste them into your settings if and when you want them. The CLAUDE.md primer is wrapped in / markers so it can be cleanly added, replaced, or removed without touching surrounding content. See ROADMAP.md Phase 1 for the design rationale.
Agent Runtimes (Hermes, Codex, OpenClaw)
Agent runtimes discover FileScopeMCP via the repo's AGENTS.md, which includes MCP registration config, broker/LLM setup, and a pointer to the portable skill file at skills/filescope-mcp/SKILL.md.
**Hermes** — add to ~/.hermes/config.yaml:
**Already have a local LLM running?** Point the broker at it — edit ~/.filescope/broker.json and set baseURL to your LLM's endpoint. See AGENTS.md for details.