/**
* Zod schema for local_view_structure tool
*/
import { z } from 'zod';
import { BaseQuerySchema, createBulkQuerySchema } from './baseSchema.js';
import { TOOL_NAMES } from '../constants.js';
/**
* Tool description for MCP registration
*/
export const LOCAL_VIEW_STRUCTURE_DESCRIPTION = `DIRECTORY EXPLORER - Understand codebase organization
PURPOSE: See file organization, sizes, layout. Understand directory context & organization.
USE_WHEN: New codebase | Need structure overview | Don't know where files are
AVOID: Know patterns → RIPGREP | Know filename → FIND_FILES | Need contents → FETCH_CONTENT
DECISION_TREE:
1. UNDERSTAND DIRECTORY STRUCTURE
└─► VIEW_STRUCTURE (depth=1, sortBy="time", entriesPerPage=20)
├─► Default: sorted by time (most recent first), 20 entries per page
├─► sortBy="size" → Find large files
└─► Next: RIPGREP (search) or FIND_FILES (filter)
WORKFLOW: Overview (depth=1) → Drill down (depth=2) → Search (RIPGREP/FIND_FILES)
PAGINATION (AUTOMATIC):
- Entries sorted by modification time (most recent first) by default
- 20 entries per page (configurable 1-100)
- Use entryPageNumber to navigate pages
KEY_PARAMS:
- sortBy: "time" (default), "name", "size", "extension"
- entriesPerPage: 20 (default, max 100)
- entryPageNumber: Page number (default 1)
- treeView: true (default) - Visual tree with file sizes
- depth: 1 (shallow), 2 (subdirs), 3-5 (deep, slower)
- filters: pattern, extensions, filesOnly, directoriesOnly
OPTIMIZATION:
- depth=1-2: Quick overview
- Bulk queries: queries=[{path:"src"},{path:"tests"}] - parallel
- Default pagination prevents token overflow
GOTCHAS:
- Always sorted by time unless sortBy specified
- depth>2 on large dirs → very slow
- node_modules without filters → huge output
- hidden=true for dotfiles
NEXT_STEP:
hasResults → RIPGREP (STRONG) | FIND_FILES modifiedWithin (STRONG)
empty → FIND_FILES type="d" or check parent
EXAMPLES:
path="src", depth=1 # Recent files in src (default sort)
path="src", sortBy="size", details=true # Large files
path="src", entriesPerPage=10, entryPageNumber=2 # Page 2
queries=[{path:"src"},{path:"tests"}] # Parallel`;
/**
* View structure query schema
*/
export const ViewStructureQuerySchema = BaseQuerySchema.extend({
path: z.string().describe('Directory path (required)'),
details: z.boolean().default(false).describe('Show details (perms, size, dates)'),
hidden: z.boolean().default(false).describe('Show hidden files'),
humanReadable: z
.boolean()
.default(true)
.describe('Human-readable sizes (KB, MB, GB)'),
sortBy: z
.enum(['name', 'size', 'time', 'extension'])
.optional()
.default('time')
.describe('Sort by (name/size/time/extension). Default: "time" (most recent first)'),
reverse: z.boolean().optional().describe('Reverse sort'),
entriesPerPage: z
.number()
.int()
.min(1)
.max(100)
.optional()
.default(20)
.describe('Number of entries per page (default 20, max 100). Entries sorted by sortBy parameter.'),
entryPageNumber: z
.number()
.int()
.min(1)
.optional()
.default(1)
.describe('Entry page number to retrieve (1-based, default 1). Use with entriesPerPage for pagination.'),
pattern: z
.string()
.optional()
.describe('Name pattern filter (*.js)'),
directoriesOnly: z.boolean().optional().describe('Directories only'),
filesOnly: z.boolean().optional().describe('Files only'),
extension: z
.string()
.optional()
.describe('Extension filter (js, ts)'),
extensions: z
.array(z.string())
.optional()
.describe('Multiple extensions (["js", "ts", "tsx"])'),
depth: z
.number()
.min(1)
.max(5)
.optional()
.describe('Recursive depth (1-5)'),
recursive: z.boolean().optional().describe('Recursive listing'),
treeView: z.boolean().default(true).describe('Tree visualization (default: true)'),
limit: z
.number()
.min(1)
.max(10000)
.optional()
.describe('Max entries (1-10000, default 1000)'),
summary: z
.boolean()
.default(true)
.describe('Include summary (files, dirs, size)'),
charOffset: z
.number()
.min(0)
.optional()
.describe('Character offset for pagination (start position, default 0)'),
charLength: z
.number()
.min(1)
.max(10000)
.optional()
.describe('Max characters to return per request (max 10,000 recommended for large directories)'),
});
/**
* Bulk view structure schema
*/
export const BulkViewStructureSchema = createBulkQuerySchema(
TOOL_NAMES.LOCAL_VIEW_STRUCTURE,
ViewStructureQuerySchema
);
export type ViewStructureQuery = z.infer<typeof ViewStructureQuerySchema>;
export type BulkViewStructureQuery = z.infer<typeof BulkViewStructureSchema>;
