Local Explorer MCP

/**
 * Zod schema for local_find_files 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_FIND_FILES_DESCRIPTION = `METADATA SEARCH - Find files by name, time, size, permissions

PURPOSE: Find specific files, recent changes. Search by metadata (name, time, size). Does NOT search contents.

USE_WHEN: Know filename/pattern | Need time-based search | Want size filtering
AVOID: Know content patterns → RIPGREP | Need contents → FETCH_CONTENT

DECISION_TREE:
  3. SEARCH FILES BY NAME
   └─► FIND_FILES (name, modifiedWithin, filesPerPage=20)
       ├─► Default: sorted by modification time (most recent first), 20 files per page
       ├─► modifiedWithin="7d" → Recent changes (UNIQUE: ONLY time-based tool)
       ├─► sizeGreater="1M" → Find large files
       ├─► Found → FETCH_CONTENT (read)
       └─► Empty → VIEW_STRUCTURE (explore)

WORKFLOW: Metadata filter → Read (FETCH_CONTENT) → Search (RIPGREP)

PAGINATION (AUTOMATIC):
  - Files ALWAYS sorted by modification time (most recent first)
  - 20 files per page (configurable 1-100)
  - Use filePageNumber to navigate pages

UNIQUE_FEATURES:
  - modifiedWithin="7d" - ONLY tool with time-based search
  - sizeGreater="1M" - Find large files
  - permissions="755" - Unix permissions
  - Always sorted by date automatically

KEY_PARAMS:
  - filesPerPage: 20 (default, max 100)
  - filePageNumber: Page number (default 1)
  - name: "*.js" (case-sensitive), iname: "*.JS" (case-insensitive)
  - names: ["*.ts","*.tsx"] (OR logic)
  - type: "f" (file), "d" (dir), "l" (symlink)
  - modifiedWithin: "7d"|"2h"|"30m", modifiedBefore: "30d"
  - sizeGreater/sizeLess: "10M"|"100k"|"1G"
  - excludeDir: ["node_modules",".git","dist"]

OPTIMIZATION:
  - Bulk queries: queries=[{name:"*.ts"},{name:"*.test.*"}] - faster
  - details=false (default) - shows paths only (still sorted)
  - Default pagination prevents token overflow

GOTCHAS:
  - ALWAYS sorted by modification time (most recent first)
  - Time: "7d" NOT "7 days"
  - Size: "10M" NOT "10MB"
  - permissions: "755" NOT "rwxr-xr-x"

NEXT_STEP:
  hasResults → FETCH_CONTENT (STRONG) | RIPGREP (MODERATE)
  empty → VIEW_STRUCTURE | Broaden: iname, increase maxDepth

EXAMPLES:
  modifiedWithin="7d", type="f"  # Recent files (sorted by date)
  name="*.js", sizeGreater="1M"  # Large JS files (sorted by date)
  name="*.ts", filesPerPage=10, filePageNumber=2  # Page 2
  queries=[{name:"*.ts"},{name:"*.tsx"}]  # Bulk`;

/**
 * Find files query schema
 */
export const FindFilesQuerySchema = BaseQuerySchema.extend({
  path: z.string().describe('Starting directory (required)'),

  maxDepth: z
    .number()
    .min(1)
    .max(10)
    .optional()
    .describe('Max depth (1-10, default 5)'),
  minDepth: z
    .number()
    .min(0)
    .max(10)
    .optional()
    .describe('Min depth (0-10)'),

  name: z.string().optional().describe('Name pattern (*.js, *config*)'),
  iname: z.string().optional().describe('Case-insensitive name pattern'),
  names: z
    .array(z.string())
    .optional()
    .describe('Multiple patterns OR logic (["*.ts", "*.js"])'),
  pathPattern: z.string().optional().describe('Path pattern'),
  regex: z.string().optional().describe('Regex pattern'),
  regexType: z
    .enum(['posix-egrep', 'posix-extended', 'posix-basic'])
    .optional()
    .describe('Regex type (default: posix-egrep)'),

  type: z
    .enum(['f', 'd', 'l', 'b', 'c', 'p', 's'])
    .optional()
    .describe('Type: f=file, d=dir, l=symlink'),

  empty: z.boolean().optional().describe('Empty files/dirs only'),

  modifiedWithin: z
    .string()
    .optional()
    .describe('Modified within (7d, 2h, 30m)'),
  modifiedBefore: z
    .string()
    .optional()
    .describe('Modified before (30d)'),
  accessedWithin: z
    .string()
    .optional()
    .describe('Accessed within (1d)'),

  sizeGreater: z
    .string()
    .optional()
    .describe('Size > (10M, 100k, 1G)'),
  sizeLess: z
    .string()
    .optional()
    .describe('Size < (1M, 500k)'),

  permissions: z
    .string()
    .optional()
    .describe('Permission pattern (755, 644)'),
  executable: z.boolean().optional().describe('Executable only'),
  readable: z.boolean().optional().describe('Readable only'),
  writable: z.boolean().optional().describe('Writable only'),

  excludeDir: z
    .array(z.string())
    .optional()
    .describe('Exclude dirs (["node_modules", ".git"])'),

  limit: z
    .number()
    .min(1)
    .max(10000)
    .optional()
    .describe('Max results (1-10000, default 1000)'),
  details: z
    .boolean()
    .default(false)
    .describe('Include size/perms (default false)'),

  filesPerPage: z
    .number()
    .int()
    .min(1)
    .max(100)
    .optional()
    .default(20)
    .describe('Number of files per page (default 20, max 100). Files sorted by modification time (most recent first).'),
  filePageNumber: z
    .number()
    .int()
    .min(1)
    .optional()
    .default(1)
    .describe('File page number to retrieve (1-based, default 1). Use with filesPerPage for pagination.'),

  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 result sets)'),
});

/**
 * Bulk find files schema
 */
export const BulkFindFilesSchema = createBulkQuerySchema(
  TOOL_NAMES.LOCAL_FIND_FILES,
  FindFilesQuerySchema
);

export type FindFilesQuery = z.infer<typeof FindFilesQuerySchema>;
export type BulkFindFilesQuery = z.infer<typeof BulkFindFilesSchema>;