filescope-mcp

name	filescope-mcp
description	Codebase intelligence via FileScopeMCP — symbol lookup, dependency mapping, importance ranking, and semantic search. Use when navigating unfamiliar code, planning refactors, assessing change impact, or finding entry points in a large project.
version	1.0.0
author	admica
license	All Rights Reserved
metadata	{"hermes":{"tags":["codebase","navigation","dependencies","symbols","mcp"],"category":"development"}}

FileScopeMCP Tool Guide

FileScopeMCP is an MCP server that indexes your codebase and exposes it as tools. This skill teaches you when and how to use each tool effectively.

Getting Oriented in a New Codebase

Start here when you enter an unfamiliar project:

1. status() — verify FileScopeMCP is initialized and healthy. Check file count, broker state, last update time.
2. find_important_files(maxItems: 10) — see the top 10 most critical files. These are your entry points.
3. get_file_summary(filepath) — read the summary of each important file. Gives you: what it does, what it depends on, what depends on it, exported symbols.

This three-step sequence gives you a working mental model in seconds.

Tool Reference

Navigation Tools

find_symbol(name, kind?, exportedOnly?, maxItems?) Resolve a symbol name to its file + line range. Exact case-sensitive match. Trailing * enables prefix match.

• Use when you know a function/class name but not where it lives
• kind accepts: function, class, interface, type, enum, const, module, struct
• exportedOnly defaults true — pass false to find private helpers
• maxItems clamped to [1, 500], default 50
• Example: find_symbol("processFile") → {path: "src/coordinator.ts", startLine: 142, endLine: 198}

search(query, maxItems?) Semantic search across symbols, summaries, purposes, and paths. Ranked results.

• Use when you have a concept ("authentication", "rate limiting") but no exact name
• Searches LLM-generated summaries, so it understands intent not just strings
• Example: search("dependency cycle detection") → files related to circular imports

get_file_summary(filepath) Full intelligence on one file: summary, importance, dependencies (with edge types), dependents (with import lines), exported symbols, concepts, change impact, staleness.

• Use before editing any file to understand its role and blast radius
• importLines in dependents tells you exactly where each consumer imports from this file

Dependency Analysis

find_callers(name, filePath?, maxItems?) Every symbol that calls the named symbol. Case-sensitive exact match.

• Use before renaming or changing a function's signature
• filePath disambiguates when multiple files define the same name
• Currently supports TS/JS call-site edges

find_callees(name, filePath?, maxItems?) Every symbol the named symbol calls.

• Use to understand what a function depends on before modifying it
• Helps trace execution flow through the codebase

detect_cycles() All circular dependency groups in the project.

• Use to identify tightly-coupled modules before refactoring
• Returns cycle groups (arrays of file paths)

get_cycles_for_file(filepath) Cycles involving one specific file.

• Use when you suspect a file is part of a circular dependency

get_communities(file_path?) Louvain-clustered file communities — groups of tightly coupled files.

• Use to understand module boundaries and which files change together
• Filter to one file's community to see its neighborhood

Project-Level Tools

list_files(maxItems?) All tracked files. Without maxItems: nested directory tree. With maxItems: flat list sorted by importance.

• Use for broad project overview
• Prefer find_important_files when you only need the top N

find_important_files(maxItems?, minImportance?) Top files by importance with dependency counts and staleness flags.

• Use to find critical files and check if their metadata is stale

list_changed_since(since, maxItems?) Files changed since a timestamp or git SHA.

• Use after multi-file edits to see what changed
• Accepts ISO-8601 (2026-04-23T10:00:00Z) or git SHA (860fe61)

Mutation Tools

set_base_directory(path) Point FileScopeMCP at a different project directory. Re-initializes everything.

• Use when switching between projects in one session

set_file_importance(filepath, importance) Override auto-calculated importance (0-10).

• Use when the algorithm undervalues a critical config or entrypoint

set_file_summary(filepath, summary) Override LLM-generated summary.

• Use when auto-summary is wrong or you want custom annotations

scan_all(min_importance?, remaining_only?) Queue files for LLM summarization. Requires active broker + LLM backend.

• remaining_only: true skips already-summarized files (incremental scan)
• Use after first setup or major codebase changes

exclude_and_remove(filepath) Permanently exclude a file/pattern from tracking. DESTRUCTIVE — cannot be undone without re-scan.

• Use for generated files, build artifacts, false positives
• Persists pattern to .filescope/config.json (excludePatterns array). For .gitignore-style commit-able rules, hand-edit .filescopeignore instead.

Common Workflows

"What calls this function and what would break if I change it?"

find_callers("functionName")       → list of callers
get_file_summary("path/to/file")   → see dependents with import lines

"I need to understand this module before editing it"

get_file_summary("src/coordinator.ts")  → summary, deps, dependents, exports
find_callees("mainExportedFn")      → what it calls internally
get_communities("src/coordinator.ts")   → its architectural neighborhood

"Where should I add this new feature?"

search("authentication middleware")  → find related files by concept
find_important_files(maxItems: 5)    → see the highest-traffic files
get_file_summary("likely-file.ts")   → verify it's the right place

"What changed since my last session?"

list_changed_since("abc1234")        → files changed since that commit
status()                             → check for stale summaries
scan_all(remaining_only: true)       → refresh any unsummarized files

"Is there a circular dependency problem?"

detect_cycles()                      → all cycle groups
get_cycles_for_file("suspect.ts")    → cycles involving one file

Tips

• Call status() first if tools return NOT_INITIALIZED — the server may need set_base_directory.
• find_symbol is faster than grep for finding where something is defined.
• search understands concepts because it searches LLM summaries, not just text.
• get_file_summary is your single best tool — use it before editing anything.
• unresolvedCount in caller/callee results means stale edges exist — run scan_all to refresh.
• The broker must be connected for scan_all to work. Check status() for broker state.