11# MCP Tools Reference
22
3- 7 tools available via ` --mcp ` mode (stdio transport).
3+ 15 tools available via ` --mcp ` mode (stdio) or HTTP transport ( ` POST /api/mcp ` ).
44
55## 1. codebase_overview
66
@@ -9,53 +9,59 @@ High-level summary of the entire codebase.
99** Input:** ` { depth?: number } `
1010** Returns:** totalFiles, totalFunctions, totalDependencies, modules (sorted by size), topDependedFiles (top 5 by fanIn), globalMetrics (avgLOC, maxDepth, circularDepCount)
1111
12- ** Use case:** First tool to call. Get the lay of the land before drilling into specifics.
12+ ** Use when:** First exploring a codebase. "What does this project look like?"
13+ ** Not for:** Module details (use get_module_structure) or data flow (use analyze_forces).
1314
1415## 2. file_context
1516
1617Detailed context for a single file.
1718
1819** Input:** ` { filePath: string } ` (relative path)
19- ** Returns:** path, loc, exports, imports (with symbols), dependents (with symbols), metrics (all FileMetrics including churn, complexity, blastRadius, deadExports, hasTests, testFile)
20+ ** Returns:** path, loc, exports, imports (with symbols, isTypeOnly, weight ), dependents (with symbols, isTypeOnly, weight ), metrics (all FileMetrics including churn, complexity, blastRadius, deadExports, hasTests, testFile)
2021
21- ** Use case:** Before modifying a file, understand its role, connections, and risk profile.
22+ ** Use when:** Before modifying a file, understand its role, connections, and risk profile.
23+ ** Not for:** Symbol-level detail (use symbol_context).
2224
2325## 3. get_dependents
2426
25- Blast radius analysis — what breaks if this file changes.
27+ File-level blast radius analysis — what breaks if this file changes.
2628
2729** Input:** ` { filePath: string, depth?: number } ` (default depth: 2)
2830** Returns:** directDependents (with symbols), transitiveDependents (with path through), totalAffected, riskLevel (LOW/MEDIUM/HIGH)
2931
30- ** Use case:** Before refactoring an export, check who consumes it and how deep the impact goes.
32+ ** Use when:** "What breaks if I change this file?" Before refactoring an export.
33+ ** Not for:** Symbol-level impact (use impact_analysis).
3134
3235## 4. find_hotspots
3336
34- Rank files by any metric. The swiss-army knife for codebase analysis.
37+ Rank files by any metric.
3538
3639** Input:** ` { metric: string, limit?: number } ` (default limit: 10)
3740** Metrics:** coupling, pagerank, fan_in, fan_out, betweenness, tension, escape_velocity, churn, complexity, blast_radius, coverage
3841** Returns:** ranked files with score + reason, summary
3942
40- ** Use case:** "What are the most complex files?" → ` metric: "complexity" ` . "What files change most?" → ` metric: "churn" ` . "What files have no tests?" → ` metric: "coverage" ` .
43+ ** Use when:** "What are the riskiest files?" "Which files need tests?" "Most complex files?"
44+ ** Not for:** Module-level analysis (use get_module_structure).
4145
4246## 5. get_module_structure
4347
4448Module-level architecture with cross-module dependencies.
4549
4650** Input:** ` { depth?: number } `
47- ** Returns:** modules (with all ModuleMetrics), crossModuleDeps (from-> to with weight), circularDeps (with severity)
51+ ** Returns:** modules (with all ModuleMetrics), crossModuleDeps (from→ to with weight), circularDeps (with severity)
4852
49- ** Use case:** Understand module boundaries, find tightly coupled modules, identify circular module dependencies.
53+ ** Use when:** Understanding module boundaries, finding tightly coupled modules, identifying circular module dependencies.
54+ ** Not for:** Emergent clusters (use get_clusters) or file-level metrics (use find_hotspots).
5055
5156## 6. analyze_forces
5257
53- Architectural force analysis — tension, bridges, junk drawers, extraction candidates .
58+ Architectural force analysis — module health, misplaced files, bridge files .
5459
5560** Input:** ` { cohesionThreshold?: number, tensionThreshold?: number, escapeThreshold?: number } `
5661** Returns:** moduleCohesion (with verdicts), tensionFiles (with pull details + recommendations), bridgeFiles (with connections), extractionCandidates (with recommendations), summary
5762
58- ** Use case:** Identify architectural problems. Tension files need splitting. Junk drawers need restructuring. Extraction candidates should become packages.
63+ ** Use when:** "What's architecturally wrong?" "Which modules are coupled?" "What files should be moved?"
64+ ** Not for:** File-level metrics (use find_hotspots).
5965
6066## 7. find_dead_exports
6167
@@ -64,17 +70,121 @@ Find unused exports across the codebase.
6470** Input:** ` { module?: string, limit?: number } ` (default limit: 20)
6571** Returns:** totalDeadExports, files (with path, module, deadExports[ ] , totalExports), summary
6672
67- ** Use case:** Clean up dead code. Unused exports increase API surface without value. Safe to remove.
73+ ** Use when:** Cleaning up dead code, reducing API surface.
74+ ** Not for:** Finding used exports (use file_context).
75+
76+ ## 8. get_groups
77+
78+ Top-level directory groups with aggregate metrics.
79+
80+ ** Input:** ` {} `
81+ ** Returns:** groups (rank, name, files, loc, importance%, coupling)
82+
83+ ** Use when:** "What are the main areas of this codebase?" High-level grouping overview.
84+ ** Not for:** Detailed module metrics (use get_module_structure).
85+
86+ ## 9. symbol_context
87+
88+ Callers, callees, and importance metrics for a function, class, or method.
89+
90+ ** Input:** ` { name: string } ` (e.g., 'AuthService', 'getUserById')
91+ ** Returns:** name, file, type, loc, isDefault, complexity, fanIn, fanOut, pageRank, betweenness, callers (with confidence), callees (with confidence)
92+
93+ ** Use when:** "Who calls X?" "Trace this function." "What depends on this symbol?"
94+ ** Not for:** Text search (use search) or file-level dependencies (use get_dependents).
95+
96+ ## 10. search
97+
98+ Search files and symbols by keyword.
99+
100+ ** Input:** ` { query: string, limit?: number } ` (default limit: 20)
101+ ** Returns:** ranked results grouped by file with symbol names, types, LOC, and relevance scores. Suggests alternatives on empty results.
102+
103+ ** Use when:** "Find files related to auth." "Where is getUserById defined?"
104+ ** Not for:** Structured call graph queries (use symbol_context).
105+
106+ ## 11. detect_changes
107+
108+ Detect changed files from git diff with risk metrics.
109+
110+ ** Input:** ` { scope?: "staged" | "unstaged" | "all" } ` (default: all)
111+ ** Returns:** changedFiles, changedSymbols, affectedFiles, fileRiskMetrics (blastRadius, complexity, churn per file)
112+
113+ ** Use when:** Starting a review, triaging changes, "what changed?"
114+ ** Not for:** Symbol-level impact (use impact_analysis).
115+
116+ ## 12. impact_analysis
117+
118+ Symbol-level blast radius with depth-grouped risk labels.
119+
120+ ** Input:** ` { symbol: string } ` (e.g., 'getUserById' or 'UserService.getUserById')
121+ ** Returns:** levels[ ] (depth 1: WILL BREAK, depth 2: LIKELY, depth 3+: MAY NEED TESTING), totalAffected
122+
123+ ** Use when:** "What breaks if I change getUserById?" Symbol-level impact assessment.
124+ ** Not for:** File-level dependencies (use get_dependents).
125+
126+ ## 13. rename_symbol
127+
128+ Read-only reference finder for rename planning.
129+
130+ ** Input:** ` { oldName: string, newName: string, dryRun?: boolean } ` (default dryRun: true)
131+ ** Returns:** references[ ] (file, symbol, confidence), totalReferences. Does not modify files.
132+
133+ ** Use when:** Planning a rename, finding all usages of a symbol.
134+ ** Not for:** Call graph analysis (use symbol_context).
135+
136+ ## 14. get_processes
137+
138+ Trace execution flows from entry points through the call graph.
139+
140+ ** Input:** ` { entryPoint?: string, limit?: number } `
141+ ** Returns:** processes[ ] (name, entryPoint, steps[ ] , depth, modulesTouched), totalProcesses
142+
143+ ** Use when:** "How does this app start?" "Trace request flow." "What are the entry points?"
144+ ** Not for:** Static file dependencies (use get_dependents).
145+
146+ ## 15. get_clusters
147+
148+ Community-detected clusters of related files.
149+
150+ ** Input:** ` { minFiles?: number } `
151+ ** Returns:** clusters[ ] (id, name, files, fileCount, cohesion), totalClusters
152+
153+ ** Use when:** "What files are related?" "Find natural groupings." Discovering emergent groupings that differ from directory structure.
154+ ** Not for:** Directory-based modules (use get_module_structure).
155+
156+ ## MCP Prompts
157+
158+ | Prompt | Description |
159+ | --------| -------------|
160+ | ` detect_impact ` | Guided analysis: impact of changing a symbol — chains impact_analysis + file_context |
161+ | ` generate_map ` | Guided analysis: generate mental map of codebase — chains overview + modules + hotspots |
162+
163+ ## MCP Resources
164+
165+ | Resource | URI | Description |
166+ | ----------| -----| -------------|
167+ | Clusters | ` codebase://clusters ` | Community-detected file clusters |
168+ | Processes | ` codebase://processes ` | Execution flow traces from entry points |
169+ | Setup | ` codebase://setup ` | Onboarding guide with available tools and getting-started hints |
68170
69171## Tool Selection Guide
70172
71173| Question | Tool |
72174| ----------| ------|
73175| "What does this codebase look like?" | ` codebase_overview ` |
74176| "Tell me about file X" | ` file_context ` |
75- | "What breaks if I change X?" | ` get_dependents ` |
177+ | "What breaks if I change file X?" | ` get_dependents ` |
178+ | "What breaks if I change function X?" | ` impact_analysis ` |
76179| "What are the riskiest files?" | ` find_hotspots ` (coupling, churn, or blast_radius) |
77180| "Which files need tests?" | ` find_hotspots ` (coverage) |
78181| "What can I safely delete?" | ` find_dead_exports ` |
79182| "How are modules organized?" | ` get_module_structure ` |
80183| "What's architecturally wrong?" | ` analyze_forces ` |
184+ | "Who calls this function?" | ` symbol_context ` |
185+ | "Find files related to X" | ` search ` |
186+ | "What changed?" | ` detect_changes ` |
187+ | "Find all references to X" | ` rename_symbol ` |
188+ | "How does data flow through the app?" | ` get_processes ` |
189+ | "What files naturally belong together?" | ` get_clusters ` |
190+ | "What are the main areas?" | ` get_groups ` |
0 commit comments