# admica/FileScopeMCP [Health: Active]

**Category:** 📊 Data Visualization  
**Repository:** https://github.com/admica/FileScopeMCP  
**GitHub Stars:** 302  
**Views:** 5  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/admica-filescopemcp

## Description
Analyzes your codebase identifying important files based on dependency relationships. Generates diagrams and importance scores, helping AI assistants understand the codebase.

## Tools
Capabilities this server exposes over MCP:

- **status** — Broker connection, queue depth, LLM progress, watcher state
- **find_important_files** — Top files by importance score with dependency counts
- **get_file_summary** — Everything about a file: summary, concepts, change impact, exports, deps, staleness
- **list_files** — Full file tree (no args) or flat top-N by importance (with `maxItems`)
- **find_symbol** — Resolve a symbol name to file + line range; supports prefix match via trailing `*
- **find_callers** — Find all symbols that call a named symbol (TS/JS call graph)
- **find_callees** — Find all symbols that a named symbol calls (TS/JS call graph)
- **search** — Search file metadata across symbols, summaries, purpose, and paths
- **list_changed_since** — Files changed since a timestamp or git SHA
- **get_communities** — Louvain-clustered file groups by import coupling
- **detect_cycles** — Find circular dependency chains
- **get_cycles_for_file** — Cycles involving a specific file
- **scan_all** — Queue files for LLM summarization via the broker
- **set_base_directory** — Point at a different project
- **set_file_summary** — Manually set or override a file's LLM summary
- **set_file_importance** — Manually set a file's importance score (0-10)
- **exclude_and_remove** — Drop files/patterns from tracking (destructive)

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "filescopemcp": {
    "command": "npx",
    "args": ["-y","filescope-install"]
  }
}
```

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/admica-filescopemcp/readme_