@j0hanz/filesystem-mcp 1.19.0 → 2.0.0

package/dist/tools/search-files.js

@@ -1,182 +1,183 @@
-import { basename, relative } from 'node:path';
-import { DEFAULT_EXCLUDE_PATTERNS, DEFAULT_SEARCH_TIMEOUT_MS, } from '../lib/constants.js';
-import { classifyError, ErrorCode } from '../lib/errors.js';
-import { searchFiles } from '../lib/file-operations/search.js';
-import { formatOperationSummary, joinLines } from '../config.js';
-import { SearchFilesInputSchema, SearchFilesOutputSchema } from '../schemas.js';
-import { DIRECTORY_ICONS } from './icons.js';
-import { buildToolErrorResponse, buildToolResponse, createProgressReporter, decodeOffsetCursor, encodeOffsetCursor, executeToolWithDiagnostics, notifyProgress, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, truncateProgressPattern, } from './shared.js';
-import { registerStandardTool } from './task-support.js';
-export const SEARCH_FILES_TOOL = {
-    name: 'find',
-    title: 'Find Files',
-    description: 'Find files by glob pattern (e.g. `**/*.ts`). Returns matching files with metadata. ' +
-        'For content search, use `grep`. For bulk edits, pass the same glob to `search_and_replace`.',
-    inputSchema: SearchFilesInputSchema,
-    outputSchema: SearchFilesOutputSchema,
-    annotations: READ_ONLY_TOOL_ANNOTATIONS,
-    icons: DIRECTORY_ICONS,
-    nuances: ['Respects `.gitignore` unless `includeIgnored=true`.'],
-    taskSupport: 'optional',
-};
-function buildTruncatedReason(summary) {
-    if (!summary.truncated)
-        return undefined;
-    if (summary.stoppedReason === 'timeout')
-        return 'timeout';
-    if (summary.stoppedReason === 'maxFiles')
-        return `max files (${summary.filesScanned})`;
-    return `max results (${summary.matched})`;
-}
+import * as z from 'zod/v4';
+import { SearchStoppedReasonSchema } from '../core/concurrency.js';
+import { createFirstPage, readNextPage } from '../core/cursor.js';
+import { ErrorCode } from '../core/errors.js';
+import { formatCount, truncateProgressPattern } from '../core/fmt.js';
+import { DEFAULT_EXCLUDE_PATTERNS } from '../core/glob.js';
+import { toPosixRelative } from '../core/path.js';
+import { CursorSchema, includeHiddenField, includeIgnoredField, maxDepthField, NextCursorSchema, NonNegInt, OptionalPath, SafeGlobPattern, } from '../core/schema.js';
+import { searchFiles } from '../core/search.js';
+import { putJsonResource } from '../core/store.js';
+import { DEFAULT_SEARCH_RESULTS, DEFAULT_SEARCH_TIMEOUT_MS, MAX_SEARCH_RESULTS, } from '../core/util.js';
+import { defineTool } from './define.js';
+// ---------------------------------------------------------------------------
+const SearchFilesInputSchema = z.strictObject({
+    path: OptionalPath.describe('Base directory to search under (default: first allowed root)'),
+    pattern: SafeGlobPattern.describe('Glob pattern to match file paths (e.g. **/*.ts, src/**/*.js)'),
+    maxResults: z
+        .uint32()
+        .min(1)
+        .max(MAX_SEARCH_RESULTS)
+        .optional()
+        .default(DEFAULT_SEARCH_RESULTS)
+        .describe('Maximum number of matching files to return per page'),
+    includeIgnored: includeIgnoredField(),
+    includeHidden: includeHiddenField(),
+    sortBy: z
+        .enum(['name', 'path'])
+        .optional()
+        .default('path')
+        .describe('Sort order: path = full path (default), name = basename only'),
+    maxDepth: maxDepthField(),
+    cursor: CursorSchema,
+});
+const SearchFilesOutputSchema = z.strictObject({
+    root: z.string().describe('Resolved base directory used as the search root'),
+    results: z
+        .array(z.strictObject({
+        path: z.string().describe('File path relative to the search root'),
+    }))
+        .describe('Matched files ordered by sortBy'),
+    totalMatches: NonNegInt.optional().describe('Total number of matching files found'),
+    filesScanned: NonNegInt.optional().describe('Total number of files examined during the search'),
+    skippedInaccessible: NonNegInt.optional().describe('Files skipped due to permission or access errors'),
+    stoppedReason: SearchStoppedReasonSchema.describe('Why the search ended early: maxResults = result cap reached, timeout = time limit hit or the request was cancelled. Absent when the scan ran to completion.'),
+    resourceUri: z
+        .string()
+        .optional()
+        .describe('URI to the full results JSON in the resource store; first page only, when results are paginated'),
+    nextCursor: NextCursorSchema,
+});
 function buildRelativeResults(basePath, displayResults) {
     const relativeResults = [];
     for (const entry of displayResults) {
         relativeResults.push({
-            path: relative(basePath, entry.path),
-            size: entry.size,
-            modified: entry.modified?.toISOString(),
+            path: toPosixRelative(basePath, entry.path),
         });
     }
     return relativeResults;
 }
-function computeNextCursor(summary, displayResultsCount, cursorOffset) {
-    if (summary.truncated && displayResultsCount > 0) {
-        return encodeOffsetCursor(cursorOffset + displayResultsCount);
-    }
-    return undefined;
+function searchFilesQueryKey(args, basePath) {
+    return JSON.stringify({
+        method: 'find_files',
+        path: basePath,
+        pattern: args.pattern,
+        includeIgnored: args.includeIgnored,
+        includeHidden: args.includeHidden,
+        sortBy: args.sortBy,
+        maxDepth: args.maxDepth,
+    });
 }
-function applySummaryFields(structured, summary, nextCursor) {
-    if (summary.truncated)
-        structured.truncated = true;
-    if (summary.skippedInaccessible)
-        structured.skippedInaccessible = summary.skippedInaccessible;
-    if (summary.stoppedReason)
-        structured.stoppedReason = summary.stoppedReason;
-    if (nextCursor !== undefined)
-        structured.nextCursor = nextCursor;
+function searchFilesOutput(results, metadata, nextCursor) {
+    return {
+        root: metadata.root,
+        results: [...results],
+        totalMatches: metadata.totalMatches,
+        filesScanned: metadata.filesScanned,
+        ...(metadata.skippedInaccessible ? { skippedInaccessible: metadata.skippedInaccessible } : {}),
+        ...(metadata.stoppedReason !== undefined ? { stoppedReason: metadata.stoppedReason } : {}),
+        ...(metadata.resourceUri ? { resourceUri: metadata.resourceUri } : {}),
+        ...(nextCursor !== undefined ? { nextCursor } : {}),
+    };
 }
-async function handleSearchFiles(args, signal, onProgress) {
-    const basePath = resolvePathOrRoot(args.path);
+async function handleSearchFiles(args, ctx) {
+    const requestedBasePath = ctx.fs.pathGuard.resolvePathOrRoot(args.path);
+    const queryKey = searchFilesQueryKey(args, requestedBasePath);
+    if (args.cursor !== undefined) {
+        const paged = readNextPage({
+            store: ctx.pageStore,
+            queryKey,
+            cursor: args.cursor,
+            pageSize: args.maxResults,
+        });
+        // First page only — see the same note in list.ts: the overflow entry expires
+        // on ResourceStore's clock, not this snapshot's.
+        const { resourceUri: _firstPageOnly, ...pageMetadata } = paged.metadata;
+        return {
+            structured: searchFilesOutput(paged.page, pageMetadata, paged.nextCursor),
+        };
+    }
+    const basePath = await ctx.fs.pathGuard.validateExistingDirectory(requestedBasePath);
     const excludePatterns = args.includeIgnored ? [] : DEFAULT_EXCLUDE_PATTERNS;
-    const cursorOffset = args.cursor !== undefined ? decodeOffsetCursor(args.cursor) : 0;
-    const pageSize = args.maxResults;
-    const fetchMax = cursorOffset + pageSize;
     const searchOptions = {
-        maxResults: fetchMax,
+        maxResults: MAX_SEARCH_RESULTS,
         includeHidden: args.includeHidden,
         sortBy: args.sortBy,
         respectGitignore: !args.includeIgnored,
+        ...(args.maxDepth !== undefined ? { maxDepth: args.maxDepth } : {}),
+        signal: ctx.signal,
     };
-    if (args.maxDepth !== undefined)
-        searchOptions.maxDepth = args.maxDepth;
-    if (onProgress)
-        searchOptions.onProgress = onProgress;
-    if (signal)
-        searchOptions.signal = signal;
-    const result = await searchFiles(basePath, args.pattern, excludePatterns, searchOptions);
-    const allResults = result.results;
-    let displayResults = allResults;
-    if (cursorOffset > 0)
-        displayResults = allResults.slice(cursorOffset);
-    const nextCursor = computeNextCursor(result.summary, displayResults.length, cursorOffset);
-    const relativeResults = buildRelativeResults(result.basePath, displayResults);
-    const structured = {
-        ok: true,
-        root: basePath,
-        results: relativeResults,
+    const result = await searchFiles(basePath, args.pattern, excludePatterns, searchOptions, ctx.fs.pathGuard);
+    const relativeResults = buildRelativeResults(result.basePath, result.results);
+    // Store the full result set so a caller can fetch all matching files by URI
+    // when the response is incomplete: `nextCursor` covers the multi-page case,
+    // and `summary.truncated` covers a single page that already hit the hard result
+    // cap (no nextCursor, but more matches exist beyond the cap).
+    let resourceUri;
+    let link;
+    if (ctx.resourceStore !== undefined &&
+        (relativeResults.length > args.maxResults || result.summary.truncated)) {
+        const stored = putJsonResource(ctx.resourceStore, `${args.pattern} files`, relativeResults);
+        resourceUri = stored.entry.uri;
+        link = stored.link;
+    }
+    const metadata = {
+        root: result.basePath,
         totalMatches: result.summary.matched,
         filesScanned: result.summary.filesScanned,
+        ...(result.summary.skippedInaccessible
+            ? { skippedInaccessible: result.summary.skippedInaccessible }
+            : {}),
+        ...(result.summary.stoppedReason !== undefined && result.summary.stoppedReason !== 'maxFiles'
+            ? { stoppedReason: result.summary.stoppedReason }
+            : {}),
+        ...(resourceUri ? { resourceUri } : {}),
     };
-    applySummaryFields(structured, result.summary, nextCursor);
-    const truncatedReason = buildTruncatedReason(result.summary);
-    const summaryOptions = {
-        truncated: result.summary.truncated,
-    };
-    if (truncatedReason)
-        summaryOptions.truncatedReason = truncatedReason;
-    const textLines = [];
-    if (relativeResults.length === 0) {
-        textLines.push('No matches');
-    }
-    else {
-        textLines.push(`Found ${relativeResults.length}:`);
-        for (const entry of relativeResults) {
-            textLines.push(`  ${entry.path}`);
-        }
-    }
-    let text = joinLines(textLines) + formatOperationSummary(summaryOptions);
-    if (nextCursor) {
-        text += `\n[Next page available. Use cursor: "${nextCursor}"]`;
-    }
-    return buildToolResponse(text, structured);
-}
-export function registerSearchFilesTool(server, options = {}) {
-    const handler = (args, ctx) => executeToolWithDiagnostics({
-        toolName: 'find',
-        ctx,
-        outputSchema: SearchFilesOutputSchema,
-        timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
-        context: { path: args.path ?? '.' },
-        run: async (signal) => {
-            const rawScopeLabel = args.path ? basename(args.path) : '.';
-            const scopeLabel = rawScopeLabel || '.';
-            const { pattern } = args;
-            const truncatedPattern = truncateProgressPattern(pattern);
-            const context = `${truncatedPattern} in ${scopeLabel}`;
-            let progressCursor = 0;
-            notifyProgress(ctx, {
-                current: 0,
-                message: `${SEARCH_FILES_TOOL.title}: ${truncatedPattern}`,
-            });
-            const baseReporter = createProgressReporter(ctx);
-            const progressWithMessage = ({ current, total, }) => {
-                if (current > progressCursor)
-                    progressCursor = current;
-                baseReporter({
-                    current,
-                    ...(total !== undefined ? { total } : {}),
-                    message: `${SEARCH_FILES_TOOL.title}: ${truncatedPattern} [${current} files]`,
-                });
-            };
-            try {
-                const result = await handleSearchFiles(args, signal, progressWithMessage);
-                const sc = result.structuredContent;
-                const { totalMatches = 0, stoppedReason } = sc;
-                let suffix;
-                if (totalMatches === 0) {
-                    suffix = 'No matches';
-                }
-                else {
-                    suffix = `${totalMatches} ${totalMatches === 1 ? 'match' : 'matches'}`;
-                    if (stoppedReason === 'timeout') {
-                        suffix += ' [timeout]';
-                    }
-                    else if (stoppedReason === 'maxResults') {
-                        suffix += ' [max results]';
-                    }
-                    else if (stoppedReason === 'maxFiles') {
-                        suffix += ' [max files]';
-                    }
-                }
-                const finalCurrent = Math.max((sc.filesScanned ?? 0) + 1, progressCursor + 1);
-                notifyProgress(ctx, {
-                    current: finalCurrent,
-                    total: finalCurrent,
-                    message: `${SEARCH_FILES_TOOL.title}: ${context} • ${suffix}`,
-                });
-                return result;
-            }
-            catch (error) {
-                const finalCurrent = Math.max(progressCursor + 1, 1);
-                notifyProgress(ctx, {
-                    current: finalCurrent,
-                    total: finalCurrent,
-                    message: `${SEARCH_FILES_TOOL.title}: ${context} • ${classifyError(error)}`,
-                });
-                throw error;
-            }
-        },
-        onError: (error) => buildToolErrorResponse(error, ErrorCode.UNKNOWN, args.path),
+    const paged = createFirstPage({
+        store: ctx.pageStore,
+        queryKey,
+        items: relativeResults,
+        metadata,
+        pageSize: args.maxResults,
     });
-    registerStandardTool(server, SEARCH_FILES_TOOL, handler, options);
+    return {
+        structured: searchFilesOutput(paged.page, metadata, paged.nextCursor),
+        ...(link !== undefined ? { link } : {}),
+    };
 }
+export const SEARCH_FILES = defineTool({
+    name: 'find_files',
+    title: 'Find Files',
+    description: 'Find files matching a glob pattern. Returns matched paths with optional metadata. ' +
+        'Pagination cursors reference a query-bound snapshot that expires after 60 seconds. ' +
+        'For content search use search_text; for bulk regex replacements use replace_text with the same glob.',
+    input: SearchFilesInputSchema,
+    output: SearchFilesOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        destructiveHint: false,
+        openWorldHint: false,
+    },
+    timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS,
+    defaultErrorCode: ErrorCode.UNKNOWN,
+    progress: (args) => ({
+        label: 'Find',
+        subject: truncateProgressPattern(args.pattern),
+    }),
+    progressDone: (_args, result) => ({
+        detail: formatCount(result.totalMatches ?? 0, 'match', 'matches'),
+    }),
+    accessPaths: (args) => (args.path ? [args.path] : []),
+    run: async (args, ctx) => {
+        const { structured, link } = await handleSearchFiles(args, ctx);
+        const text = structured.results.length > 0
+            ? structured.results.map((r) => r.path).join('\n')
+            : `No files matching '${args.pattern}'`;
+        if (link) {
+            return { structured, text, resources: [link] };
+        }
+        return { structured, text };
+    },
+});
+//# sourceMappingURL=search-files.js.map

package/dist/tools/search-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-files.js","sourceRoot":"","sources":["../../src/tools/search-files.ts"],"names":[],"mappings":"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","sourcesContent":["import * as z from 'zod/v4';\n\nimport { SearchStoppedReasonSchema } from '../core/concurrency.js';\nimport { createFirstPage, readNextPage } from '../core/cursor.js';\nimport { ErrorCode } from '../core/errors.js';\nimport { formatCount, truncateProgressPattern } from '../core/fmt.js';\nimport { DEFAULT_EXCLUDE_PATTERNS } from '../core/glob.js';\nimport { toPosixRelative } from '../core/path.js';\nimport {\n  CursorSchema,\n  includeHiddenField,\n  includeIgnoredField,\n  maxDepthField,\n  NextCursorSchema,\n  NonNegInt,\n  OptionalPath,\n  SafeGlobPattern,\n} from '../core/schema.js';\nimport { searchFiles } from '../core/search.js';\nimport { putJsonResource } from '../core/store.js';\nimport {\n  DEFAULT_SEARCH_RESULTS,\n  DEFAULT_SEARCH_TIMEOUT_MS,\n  MAX_SEARCH_RESULTS,\n} from '../core/util.js';\nimport { defineTool, type ToolCtx } from './define.js';\n\n// ---------------------------------------------------------------------------\n\nconst SearchFilesInputSchema = z.strictObject({\n  path: OptionalPath.describe('Base directory to search under (default: first allowed root)'),\n  pattern: SafeGlobPattern.describe('Glob pattern to match file paths (e.g. **/*.ts, src/**/*.js)'),\n  maxResults: z\n    .uint32()\n    .min(1)\n    .max(MAX_SEARCH_RESULTS)\n    .optional()\n    .default(DEFAULT_SEARCH_RESULTS)\n    .describe('Maximum number of matching files to return per page'),\n  includeIgnored: includeIgnoredField(),\n  includeHidden: includeHiddenField(),\n  sortBy: z\n    .enum(['name', 'path'])\n    .optional()\n    .default('path')\n    .describe('Sort order: path = full path (default), name = basename only'),\n  maxDepth: maxDepthField(),\n  cursor: CursorSchema,\n});\n\nconst SearchFilesOutputSchema = z.strictObject({\n  root: z.string().describe('Resolved base directory used as the search root'),\n  results: z\n    .array(\n      z.strictObject({\n        path: z.string().describe('File path relative to the search root'),\n      }),\n    )\n    .describe('Matched files ordered by sortBy'),\n  totalMatches: NonNegInt.optional().describe('Total number of matching files found'),\n  filesScanned: NonNegInt.optional().describe('Total number of files examined during the search'),\n  skippedInaccessible: NonNegInt.optional().describe(\n    'Files skipped due to permission or access errors',\n  ),\n  stoppedReason: SearchStoppedReasonSchema.describe(\n    'Why the search ended early: maxResults = result cap reached, timeout = time limit hit or the request was cancelled. Absent when the scan ran to completion.',\n  ),\n  resourceUri: z\n    .string()\n    .optional()\n    .describe(\n      'URI to the full results JSON in the resource store; first page only, when results are paginated',\n    ),\n  nextCursor: NextCursorSchema,\n});\n\nfunction buildRelativeResults(\n  basePath: string,\n  displayResults: readonly { path: string }[],\n): NonNullable<z.infer<typeof SearchFilesOutputSchema>['results']> {\n  const relativeResults: NonNullable<z.infer<typeof SearchFilesOutputSchema>['results']> = [];\n  for (const entry of displayResults) {\n    relativeResults.push({\n      path: toPosixRelative(basePath, entry.path),\n    });\n  }\n  return relativeResults;\n}\n\ntype SearchFileResult = NonNullable<z.infer<typeof SearchFilesOutputSchema>['results']>[number];\n\ninterface SearchFilesPageMetadata {\n  readonly root: string;\n  readonly totalMatches: number;\n  readonly filesScanned: number;\n  readonly skippedInaccessible?: number;\n  readonly stoppedReason?: z.infer<typeof SearchFilesOutputSchema>['stoppedReason'];\n  readonly resourceUri?: string;\n}\n\nfunction searchFilesQueryKey(\n  args: z.infer<typeof SearchFilesInputSchema>,\n  basePath: string,\n): string {\n  return JSON.stringify({\n    method: 'find_files',\n    path: basePath,\n    pattern: args.pattern,\n    includeIgnored: args.includeIgnored,\n    includeHidden: args.includeHidden,\n    sortBy: args.sortBy,\n    maxDepth: args.maxDepth,\n  });\n}\n\nfunction searchFilesOutput(\n  results: readonly SearchFileResult[],\n  metadata: SearchFilesPageMetadata,\n  nextCursor: string | undefined,\n): z.infer<typeof SearchFilesOutputSchema> {\n  return {\n    root: metadata.root,\n    results: [...results],\n    totalMatches: metadata.totalMatches,\n    filesScanned: metadata.filesScanned,\n    ...(metadata.skippedInaccessible ? { skippedInaccessible: metadata.skippedInaccessible } : {}),\n    ...(metadata.stoppedReason !== undefined ? { stoppedReason: metadata.stoppedReason } : {}),\n    ...(metadata.resourceUri ? { resourceUri: metadata.resourceUri } : {}),\n    ...(nextCursor !== undefined ? { nextCursor } : {}),\n  };\n}\n\nasync function handleSearchFiles(\n  args: z.infer<typeof SearchFilesInputSchema>,\n  ctx: ToolCtx,\n): Promise<{\n  structured: z.infer<typeof SearchFilesOutputSchema>;\n  link?: ReturnType<typeof putJsonResource>['link'];\n}> {\n  const requestedBasePath = ctx.fs.pathGuard.resolvePathOrRoot(args.path);\n  const queryKey = searchFilesQueryKey(args, requestedBasePath);\n  if (args.cursor !== undefined) {\n    const paged = readNextPage<SearchFileResult, SearchFilesPageMetadata>({\n      store: ctx.pageStore,\n      queryKey,\n      cursor: args.cursor,\n      pageSize: args.maxResults,\n    });\n    // First page only — see the same note in list.ts: the overflow entry expires\n    // on ResourceStore's clock, not this snapshot's.\n    const { resourceUri: _firstPageOnly, ...pageMetadata } = paged.metadata;\n    return {\n      structured: searchFilesOutput(paged.page, pageMetadata, paged.nextCursor),\n    };\n  }\n\n  const basePath = await ctx.fs.pathGuard.validateExistingDirectory(requestedBasePath);\n  const excludePatterns = args.includeIgnored ? [] : DEFAULT_EXCLUDE_PATTERNS;\n  const searchOptions: Parameters<typeof searchFiles>[3] = {\n    maxResults: MAX_SEARCH_RESULTS,\n    includeHidden: args.includeHidden,\n    sortBy: args.sortBy,\n    respectGitignore: !args.includeIgnored,\n    ...(args.maxDepth !== undefined ? { maxDepth: args.maxDepth } : {}),\n    signal: ctx.signal,\n  };\n  const result = await searchFiles(\n    basePath,\n    args.pattern,\n    excludePatterns,\n    searchOptions,\n    ctx.fs.pathGuard,\n  );\n  const relativeResults = buildRelativeResults(result.basePath, result.results);\n\n  // Store the full result set so a caller can fetch all matching files by URI\n  // when the response is incomplete: `nextCursor` covers the multi-page case,\n  // and `summary.truncated` covers a single page that already hit the hard result\n  // cap (no nextCursor, but more matches exist beyond the cap).\n  let resourceUri: string | undefined;\n  let link: ReturnType<typeof putJsonResource>['link'] | undefined;\n  if (\n    ctx.resourceStore !== undefined &&\n    (relativeResults.length > args.maxResults || result.summary.truncated)\n  ) {\n    const stored = putJsonResource(ctx.resourceStore, `${args.pattern} files`, relativeResults);\n    resourceUri = stored.entry.uri;\n    link = stored.link;\n  }\n\n  const metadata: SearchFilesPageMetadata = {\n    root: result.basePath,\n    totalMatches: result.summary.matched,\n    filesScanned: result.summary.filesScanned,\n    ...(result.summary.skippedInaccessible\n      ? { skippedInaccessible: result.summary.skippedInaccessible }\n      : {}),\n    ...(result.summary.stoppedReason !== undefined && result.summary.stoppedReason !== 'maxFiles'\n      ? { stoppedReason: result.summary.stoppedReason }\n      : {}),\n    ...(resourceUri ? { resourceUri } : {}),\n  };\n  const paged = createFirstPage<SearchFileResult, SearchFilesPageMetadata>({\n    store: ctx.pageStore,\n    queryKey,\n    items: relativeResults,\n    metadata,\n    pageSize: args.maxResults,\n  });\n  return {\n    structured: searchFilesOutput(paged.page, metadata, paged.nextCursor),\n    ...(link !== undefined ? { link } : {}),\n  };\n}\n\nexport const SEARCH_FILES = defineTool({\n  name: 'find_files',\n  title: 'Find Files',\n  description:\n    'Find files matching a glob pattern. Returns matched paths with optional metadata. ' +\n    'Pagination cursors reference a query-bound snapshot that expires after 60 seconds. ' +\n    'For content search use search_text; for bulk regex replacements use replace_text with the same glob.',\n  input: SearchFilesInputSchema,\n  output: SearchFilesOutputSchema,\n  annotations: {\n    readOnlyHint: true,\n    idempotentHint: true,\n    destructiveHint: false,\n    openWorldHint: false,\n  },\n  timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS,\n  defaultErrorCode: ErrorCode.UNKNOWN,\n  progress: (args) => ({\n    label: 'Find',\n    subject: truncateProgressPattern(args.pattern),\n  }),\n  progressDone: (_args, result) => ({\n    detail: formatCount(result.totalMatches ?? 0, 'match', 'matches'),\n  }),\n  accessPaths: (args) => (args.path ? [args.path] : []),\n  run: async (args, ctx) => {\n    const { structured, link } = await handleSearchFiles(args, ctx);\n    const text =\n      structured.results.length > 0\n        ? structured.results.map((r) => r.path).join('\\n')\n        : `No files matching '${args.pattern}'`;\n    if (link) {\n      return { structured, text, resources: [link] };\n    }\n    return { structured, text };\n  },\n});\n"]}

package/dist/tools/stat.d.ts

@@ -1,4 +1,2 @@
-import type { McpServer } from '@modelcontextprotocol/server';
-import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
-export declare const GET_FILE_INFO_TOOL: ToolContract;
-export declare function registerGetFileInfoTool(server: McpServer, options?: ToolRegistrationOptions): void;
+export declare const GET_FILE_INFO: import("./define.js").DefinedTool;
+//# sourceMappingURL=stat.d.ts.map

package/dist/tools/stat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stat.d.ts","sourceRoot":"","sources":["../../src/tools/stat.ts"],"names":[],"mappings":"AAgMA,eAAO,MAAM,aAAa,mCAkFxB,CAAC"}