Data · MODEL CONTEXT PROTOCOL
admica FileScopeMCP
Analyzes your codebase identifying important files based on dependency relationships. Generates diagrams and importance scores per file, helping AI assistants understand the codebase. Automatically parses popular programming languages such as Python, C, C++, Rust, Zig, Lua.
连接能力
admica FileScopeMCP 为 AI Agent 提供什么
- **🎯 File Importance Analysis**
- Rank files on a 0-10 scale based on their role in the codebase.
- Calculate importance using incoming/outgoing dependencies.
- Instantly pinpoint the most critical files in your project.
- Smart calculation considers file type, location, and name significance.
- **🔗 Dependency Tracking**
- Map bidirectional dependency relationships between files.
- Identify which files import a given file (dependents).
- See which files are imported by a given file (dependencies).
- Distinguish between local and package dependencies.
- Multi-language support: Python, JavaScript, TypeScript, C/C++, Rust, Lua, Zig.
- **📊 Visualization**
- Generate Mermaid diagrams to visualize file relationships.
- Color-coded visualization based on importance scores.
- Support for dependency graphs, directory trees, or hybrid views.
- HTML output with embedded rendering including theme toggle and responsive design.
- Customize diagram depth, filter by importance, and adjust layout options.
- **📝 File Summaries**
- Add human or AI-generated summaries to any file.
- Retrieve stored summaries to quickly grasp file purpose.
- Summaries persist across server restarts.
- **📚 Multiple Project Support**
- Create and manage multiple file trees for different project areas.
- Configure separate trees with distinct base directories.
- Switch between different file trees effortlessly.
- Cached trees for faster subsequent operations.
- **💾 Persistent Storage**
- All data automatically saved to disk in JSON format.
- Load existing file trees without rescanning the filesystem.
- Track when file trees were last updated.
- Clone this repository
- Build the project:
- Update the arg path --base-dir to your project's base path.
- Python: `import` and `from ... import` statements
- JavaScript/TypeScript: `import` statements and `require()` calls
- C/C++: `#include` directives
- Rust: `use` and `mod` statements
- Lua: `require` statements
- Zig: `@import` directives
- Number of files that import this file (dependents)
- Number of files this file imports (dependencies)
- File type and extension (with TypeScript/JavaScript files getting higher base scores)
- Location in the project structure (files in `src/` are weighted higher)
- File naming (files like 'index', 'main', 'server', etc. get additional points)
- Collection Phase: Register all nodes and relationships
- Node Definition Phase: Generate definitions for all nodes before any references
- Edge Generation Phase: Create edges between defined nodes
- Responsive design that works on any device
- Light/dark theme toggle with system preference detection
- Client-side Mermaid rendering for optimal performance
- Timestamp of generation
- Windows and Unix path formats
- Absolute and relative paths
- URL-encoded paths
- Cross-platform compatibility
- Configuration metadata (filename, base directory, last updated timestamp)
- Complete file tree with dependencies, dependents, importance scores, and summaries
- **TypeScript/Node.js**: Built with TypeScript for type safety and modern JavaScript features
- **Model Context Protocol**: Implements the MCP specification for integration with Cursor
- **Mermaid.js**: Uses Mermaid syntax for diagram generation
- **JSON Storage**: Uses simple JSON files for persistence
- **Path Normalization**: Cross-platform path handling to support Windows and Unix
- **Caching**: Implements caching for faster repeated operations
- **list_saved_trees**: List all saved file trees
- **create_file_tree**: Create a new file tree configuration for a specific directory
- **select_file_tree**: Select an existing file tree to work with
- **delete_file_tree**: Delete a file tree configuration
- **list_files**: List all files in the project with their importance rankings
- **get_file_importance**: Get detailed information about a specific file, including dependencies and dependents
- **find_important_files**: Find the most important files in the project based on configurable criteria
- **read_file_content**: Read the content of a specific file
- **recalculate_importance**: Recalculate importance values for all files based on dependencies
- **get_file_summary**: Get the stored summary of a specific file
- **set_file_summary**: Set or update the summary of a specific file
- **toggle_file_watching**: Toggle file watching on/off
- **get_file_watching_status**: Get the current status of file watching
- **update_file_watching_config**: Update file watching configuration
- **generate_diagram**: Create Mermaid diagrams with customizable options
- Output formats: Mermaid text (`.mmd`) or HTML with embedded rendering
- Diagram styles: default, dependency, directory, or hybrid views
- Filter options: max depth, minimum importance threshold
- Layout options: direction (TB, BT, LR, RL), node spacing, rank spacing
- Create a file tree for your project:
- Find the most important files:
- Get detailed information about a specific file:
- Read a file's content to understand it:
- Add a summary to the file:
- Retrieve the summary later:
- Create a basic project structure diagram:
- Generate an HTML diagram with dependency relationships:
- Customize the diagram layout:
- Enable file watching for your project:
- Check the current file watching status:
- Update file watching configuration:
- Add support for more programming languages
- Add more sophisticated importance calculation algorithms
- Enhance diagram customization options
- Support for exporting diagrams to additional formats
安全
MCP 收录不等于安全审核
MCP 服务器可能获得模型上下文、凭据、本地文件或调用外部系统的权限。连接 Agent 前，请检查代码、环境变量、网络行为、软件包来源与维护状态。
README
仓库文档
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.
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.
- 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
- Linux:
git clone https://github.com/admica/FileScopeMCP.git
cd FileScopeMCP
./build.sh # installs deps, compiles, registers with Claude Code./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:
find_important_files(limit: 5)
status()
For a richer install that adds a project priming CLAUDE.md and points to optional hook templates:
npm run install-claude-code # or: npx filescope-install --claude-codeThe 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 <!-- BEGIN filescope --> / <!-- END filescope --> 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 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:
mcp_servers:
filescope:
command: "node"
args: ["/path/to/FileScopeMCP/dist/mcp-server.js"]
timeout: 120Already 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.
Run ./setup-llm.sh for a platform-specific guide to setting up llama.cpp's llama-server — see docs/llm-setup.md for details. On Linux you can also sudo ./setup-llm.sh --install-service to register llama-server as a systemd unit (logs flow to journalctl, OOM-protected, auto-restart on boot). The flag is a no-op under WSL2 since llama-server runs on the Windows host there. Without llama-server entirely, everything else still works (file tracking, dependencies, symbols, call graphs — just no LLM-generated summaries). If your agent runtime already has a local LLM, configure the broker to reuse it instead.
Add to your project's .gitignore:
.filescope/
.filescope-daemon.log
If llama-server is running locally, an optional VictoriaMetrics + vmui stack gives you a single-pane dashboard for VRAM, RAM, swap, throughput, and cumulative work. Total resident footprint ~120 MB, capped via systemd cgroups so a misbehaving exporter can't OOM-kill llama-server.
sudo ./monitoring/install.shBrowse the dashboard at http://<host>:8881/vmui/#/dashboards. See monitoring/ for the layout and uninstall script.
| Tool | What it does |
|---|---|
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) |
npm run build:nexus # one-time build (API + UI)
npm run nexus # starts at http://localhost:1234A read-only web dashboard that connects to every FileScopeMCP repo on your machine:
- Project view — file tree with importance heat colors and staleness indicators, click any file for full metadata
- Dependency graph — interactive Cytoscape.js visualization, filter by directory, click nodes to inspect
- System view — live broker status, per-repo token usage, streaming activity log
- Settings — manage which repos appear, remove or restore from blacklist
Auto-discovers repos by scanning for .filescope/data.db directories. No configuration needed.
For users who want every repo in ~/.filescope/nexus.json watched continuously — not only when an MCP client is open — install the per-repo watchers user unit:
./scripts/nexus.sh install-watchers # writes the unit, enables it, starts it
systemctl --user status filescope-watchers.service
./scripts/nexus.sh uninstall-watchers # symmetric removalThe unit launches scripts/watchers.mjs, which spawns one dist/mcp-server.js --base-dir=<repo> child per registered repo and supervises them (auto-restart on exit, SIGTERM-clean shutdown). The unit Requires=filescope-broker.service — install the broker user unit yourself; this command does not ship one.
Logs: ~/.filescope/watchers.log (supervisor) and ~/.filescope/watcher-logs/*.log (per-repo children).
Your code changes
→ file watcher picks it up
→ AST diff classifies the change (exports? types? body only?)
→ symbols extracted (functions, classes, types, etc.)
→ call-site edges resolved (TS/JS: who calls what)
→ importance scores recalculated
→ staleness cascades to dependents (only if exports/types changed)
→ LLM broker regenerates summaries, concepts, change impact
→ your AI's next query gets fresh answers
Everything lives in .filescope/data.db (SQLite, WAL mode) per project. The broker coordinates LLM work across all your repos via a Unix socket at ~/.filescope/broker.sock.
| Doc | What's in it |
|---|---|
| AGENTS.md | Cross-agent context file — MCP registration, broker config, architecture (read by Hermes, Codex, OpenClaw) |
| FileScopeMCP Skill | Portable skill file — tool reference, workflows, tips for agents using FileScopeMCP |
| LLM Setup | llama.cpp / llama-server installation — Linux/macOS native (default), WSL2+Windows, or remote LAN |
| Configuration | Per-project config, broker config, ignore patterns |
| MCP Clients | Setup for Claude Code, Cursor AI, daemon mode |
| Troubleshooting | Common issues and fixes |
| Internals | Dependency detection, importance formula, symbol extraction, call-site edges, storage |
| LLM Monitoring | Optional VictoriaMetrics + vmui dashboard for the local llama-server |
Copyright (c) 2026 admica. All rights reserved. See LICENSE.
社区