@j0hanz/filesystem-mcp 1.7.1 → 1.7.3

package/dist/resources/tool-catalog.js

@@ -9,21 +9,21 @@ diff_files (patch text) -> apply_patch.patch
 
 ## Search Strategy
 
-- Use \`find\` for glob-based file discovery.
-- Use \`grep\` for content-based searches.
-- Use \`search_and_replace\` ONLY for bulk replacements, not for discovery.
+- Use \`find\` for glob file discovery.
+- Use \`grep\` for text search.
+- Use \`search_and_replace\` only for replacement, never discovery.
 
 ## Write Strategy
 
-- Use \`edit\` for precise, single-occurrence string replacements in existing files.
-- Use \`write\` to create new files or completely overwrite existing content.
-- Use \`search_and_replace\` for bulk regex replacements across multiple files.
+- Use \`edit\` for precise, first-occurrence replacements in existing files.
+- Use \`write\` to create files or overwrite full contents.
+- Use \`search_and_replace\` for bulk multi-file replacements.
 
 ## Patch Management
 
-- Always generate a patch with \`diff_files\` first.
-- Always use \`dryRun: true\` with \`apply_patch\` to verify changes.
-- \`apply_patch\` works on unified diff format.
+- Generate patches with \`diff_files\` first.
+- Run \`apply_patch\` with \`dryRun: true\` before writing.
+- \`apply_patch\` accepts unified diffs only.
 </tool_selection_guide>
 `;
 export function buildToolCatalog() {

package/dist/resources/tool-info.js

@@ -37,10 +37,10 @@ export function buildCoreContextPack() {
 }
 export function getSharedConstraints() {
     return [
-        'Allowed roots only (negotiated via CLI).',
-        'Sensitive files denylisted by default.',
-        `Max file size (${Math.floor(MAX_TEXT_FILE_SIZE / 1024 / 1024)}MB) & search results (${MAX_SEARCH_RESULTS} files, ${DEFAULT_SEARCH_CONTENT_RESULTS} lines) enforced.`,
-        'If a response includes `resourceUri`, call `resources/read` immediately — results expire on process restart.',
+        'Use allowed roots only (provided by CLI negotiation).',
+        'Sensitive paths are denylisted by default.',
+        `Limits are enforced: max file size ${Math.floor(MAX_TEXT_FILE_SIZE / 1024 / 1024)}MB; search caps ${MAX_SEARCH_RESULTS} files and ${DEFAULT_SEARCH_CONTENT_RESULTS} lines.`,
+        'If a response includes `resourceUri`, call `resources/read` immediately; cached results expire on process restart.',
     ];
 }
 export function buildToolInfo(name) {
@@ -49,7 +49,7 @@ export function buildToolInfo(name) {
         return undefined;
     const lines = [`## ${entry.name}`, '', entry.description];
     if (entry.annotations && entry.annotations.length > 0) {
-        lines.push('', `**Annotations:** ${entry.annotations.join(', ')}`);
+        lines.push('', `**Hints:** ${entry.annotations.join(', ')}`);
     }
     if (entry.nuances && entry.nuances.length > 0) {
         lines.push('', '**Nuances:**');

package/dist/resources/workflows.js

@@ -1,33 +1,33 @@
 export function buildWorkflowGuide() {
     return `<workflows>
 ### A: EXPLORE
-Use when: navigating an unfamiliar directory or reading file content.
-1. \`roots\` (List allowed paths).
-2. \`ls\` (files) | \`tree\` (structure).
-3. \`stat\` | \`stat_many\` (size/type check).
-4. \`read\` | \`read_many\` (content).
-   > **Strict:** Never guess paths. Resolve first.
+Use when: you need directory layout or file content.
+1. \`roots\` (list allowed paths).
+2. \`ls\` (flat view) or \`tree\` (recursive view).
+3. \`stat\` or \`stat_many\` (type and size checks).
+4. \`read\` or \`read_many\` (read content).
+   > **Strict:** Resolve paths first. Never guess.
 
 ### B: SEARCH
-Use when: locating files by name pattern or by content match.
+Use when: you need files by pattern or content.
 1. \`find\` (glob candidates).
-2. \`grep\` (content search).
-3. \`read\` (verify context).
-   > **Strict:** Use \`grep\` for content search, not \`find\`.
+2. \`grep\` (content matches).
+3. \`read\` (verify matched context).
+   > **Strict:** Do content search with \`grep\`, not \`find\`.
 
 ### C: EDIT
-Use when: modifying existing files or reorganizing the filesystem.
-1. \`edit\` (precise string match).
-2. \`search_and_replace\` (bulk regex/glob).
-3. \`mv\` | \`rm\` (file layout).
-4. \`mkdir\` (create dirs).
+Use when: you need to modify files or layout.
+1. \`edit\` (targeted string replacement).
+2. \`search_and_replace\` (bulk replacements).
+3. \`mv\` or \`rm\` (layout changes).
+4. \`mkdir\` (directory creation).
    > **Strict:** Confirm destructive ops (\`write\`, \`mv\`, \`rm\`, bulk replace).
 
 ### D: PATCH
-Use when: applying structured diffs produced by \`diff_files\`.
+Use when: applying unified diffs from \`diff_files\`.
 1. \`diff_files\` (generate).
 2. \`apply_patch\` (dryRun: true).
 3. \`apply_patch\` (dryRun: false).
-   > **Tip:** Pass \`diff_files\` output directly into \`apply_patch\`.
+   > **Tip:** Feed \`diff_files\` output directly to \`apply_patch\`.
 </workflows>`;
 }

package/dist/schemas.js

@@ -18,6 +18,9 @@ function isSafeGlobPattern(value) {
 const MAX_PATH_LENGTH = 4096;
 const DESC_PATH_ROOT = 'Base directory (default: root). Absolute path required if multiple roots exist. Examples: "src", "src/components"';
 const DESC_PATH_REQUIRED = 'Absolute path to file or directory. Examples: "src/index.ts", "README.md"';
+function defaultFalseBoolean(description) {
+    return z.boolean().optional().default(false).describe(description);
+}
 const PathSchemaBase = z
     .string()
     .max(MAX_PATH_LENGTH, `Path too long (max ${MAX_PATH_LENGTH} chars)`);
@@ -109,16 +112,8 @@ const OperationSummarySchema = z.strictObject({
 });
 export const ListDirectoryInputSchema = z.strictObject({
     path: OptionalPathSchema.describe(DESC_PATH_ROOT),
-    includeHidden: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Include hidden items (starting with .)'),
-    includeIgnored: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Include ignored items (node_modules, .git, etc).'),
+    includeHidden: defaultFalseBoolean('Include hidden items (starting with .)'),
+    includeIgnored: defaultFalseBoolean('Include ignored items (node_modules, .git, etc).'),
     maxDepth: z
         .number()
         .int({ error: 'Must be integer' })
@@ -143,11 +138,7 @@ export const ListDirectoryInputSchema = z.strictObject({
         .max(1000, 'Max 1000 chars')
         .optional()
         .describe('Optional glob pattern filter (e.g. "**/*.ts")'),
-    includeSymlinkTargets: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Resolve and include symlink targets in results'),
+    includeSymlinkTargets: defaultFalseBoolean('Resolve and include symlink targets in results'),
     cursor: z
         .string()
         .optional()
@@ -174,16 +165,8 @@ export const SearchFilesInputSchema = z.strictObject({
         .optional()
         .default(DEFAULT_SEARCH_RESULTS)
         .describe(`Max results (1-${MAX_SEARCH_RESULTS}). Default: ${DEFAULT_SEARCH_RESULTS}`),
-    includeIgnored: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Include ignored items (node_modules, etc).'),
-    includeHidden: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Include hidden items (starting with .)'),
+    includeIgnored: defaultFalseBoolean('Include ignored items (node_modules, etc).'),
+    includeHidden: defaultFalseBoolean('Include hidden items (starting with .)'),
     sortBy: SearchFilesSortSchema.optional()
         .default('path')
         .describe('Sort by path, name, size, or modified'),
@@ -217,16 +200,8 @@ export const TreeInputSchema = z.strictObject({
         .optional()
         .default(DEFAULT_TREE_ENTRIES)
         .describe(`Max entries. Default: ${DEFAULT_TREE_ENTRIES}`),
-    includeHidden: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Include hidden items (starting with .)'),
-    includeIgnored: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Include ignored items. Disables .gitignore.'),
+    includeHidden: defaultFalseBoolean('Include hidden items (starting with .)'),
+    includeIgnored: defaultFalseBoolean('Include ignored items. Disables .gitignore.'),
 });
 export const SearchContentInputSchema = z.strictObject({
     path: OptionalPathSchema.describe(DESC_PATH_ROOT),
@@ -235,21 +210,9 @@ export const SearchContentInputSchema = z.strictObject({
         .min(1, 'Pattern required')
         .max(1000, 'Max 1000 chars')
         .describe('Literal text to search for by default; treated as RE2 regex when isRegex is true.'),
-    isRegex: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Treat pattern as a RE2 regular expression. RE2 does not support lookahead, lookbehind, or backreferences.'),
-    caseSensitive: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Case-sensitive matching (default: false — searches are case-insensitive).'),
-    wholeWord: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Match whole words only'),
+    isRegex: defaultFalseBoolean('Treat pattern as a RE2 regular expression. RE2 does not support lookahead, lookbehind, or backreferences.'),
+    caseSensitive: defaultFalseBoolean('Case-sensitive matching (default: false — searches are case-insensitive).'),
+    wholeWord: defaultFalseBoolean('Match whole words only'),
     contextLines: z
         .number()
         .int({ error: 'Must be integer' })
@@ -273,16 +236,8 @@ export const SearchContentInputSchema = z.strictObject({
         .optional()
         .default('**/*')
         .describe('Glob for candidate files (e.g. "**/*.ts")'),
-    includeHidden: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Include hidden items (starting with .)'),
-    includeIgnored: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Include ignored items (node_modules, etc).'),
+    includeHidden: defaultFalseBoolean('Include hidden items (starting with .)'),
+    includeIgnored: defaultFalseBoolean('Include ignored items (node_modules, etc).'),
 });
 export const ReadFileInputSchema = z
     .strictObject({
@@ -511,16 +466,8 @@ export const EditFileInputSchema = z.strictObject({
     }))
         .min(1, 'Min 1 edit required')
         .describe('List of replacements to apply sequentially. Each edit replaces the first occurrence of oldText.'),
-    dryRun: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Preview edits without writing. Check unmatchedEdits in the response to verify all oldText values were found.'),
-    ignoreWhitespace: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Ignore leading/trailing whitespace and treat all whitespace sequences as equivalent when matching oldText.'),
+    dryRun: defaultFalseBoolean('Preview edits without writing. Check unmatchedEdits in the response to verify all oldText values were found.'),
+    ignoreWhitespace: defaultFalseBoolean('Ignore leading/trailing whitespace and treat all whitespace sequences as equivalent when matching oldText.'),
 });
 export const EditFileOutputSchema = z.strictObject({
     ok: z.boolean(),
@@ -562,16 +509,8 @@ export const MoveFileOutputSchema = z.strictObject({
 });
 export const DeleteFileInputSchema = z.strictObject({
     path: RequiredPathSchema.describe(DESC_PATH_REQUIRED),
-    recursive: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Delete non-empty directories'),
-    ignoreIfNotExists: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('No error if missing'),
+    recursive: defaultFalseBoolean('Delete non-empty directories'),
+    ignoreIfNotExists: defaultFalseBoolean('No error if missing'),
 });
 export const DeleteFileOutputSchema = z.strictObject({
     ok: z.boolean(),
@@ -665,16 +604,8 @@ export const SearchAndReplaceInputSchema = z.strictObject({
         .min(1, 'Search pattern required')
         .describe('Text to search for. Matched literally by default; treated as RE2 regex when isRegex is true.'),
     replacement: z.string().describe('Replacement text'),
-    isRegex: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Treat searchPattern as a RE2 regular expression. Supports capture group references ($1, $2) in replacement.'),
-    dryRun: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Preview matches without writing. Check changedFiles and matches in the response before committing.'),
+    isRegex: defaultFalseBoolean('Treat searchPattern as a RE2 regular expression. Supports capture group references ($1, $2) in replacement.'),
+    dryRun: defaultFalseBoolean('Preview matches without writing. Check changedFiles and matches in the response before committing.'),
     includeHidden: z
         .boolean()
         .optional()

package/dist/server/bootstrap.js

@@ -7,7 +7,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { isInitializeRequest, SetLevelRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { registerCompletions } from '../completions.js';
-import { DEFAULT_LOG_LEVEL, REQUIRED_MCP_PROTOCOL_VERSION, } from '../lib/constants.js';
+import { DEFAULT_LOG_LEVEL, parseEnvInt, REQUIRED_MCP_PROTOCOL_VERSION, } from '../lib/constants.js';
 import { formatUnknownErrorMessage } from '../lib/errors.js';
 import { createInMemoryResourceStore } from '../lib/resource-store.js';
 import { pkgInfo } from '../pkg-info.js';
@@ -66,8 +66,8 @@ export async function createServer(options = {}) {
     if (serverInstructions) {
         serverConfig.instructions =
             'filesystem-mcp: Secure local filesystem MCP server. ' +
-                'Always begin with: roots → ls/find → stat → read. Never guess paths. ' +
-                'Full reference: read the internal://instructions resource or invoke the get-help prompt.';
+                'Start with: roots -> ls/find -> stat -> read. Never guess paths. ' +
+                'For full guidance, read internal://instructions or run the get-help prompt.';
     }
     const server = new McpServer(withDefaultIcons({
         name: 'filesystem-mcp',
@@ -104,16 +104,14 @@ export async function startServer(server) {
     rootsManager.registerHandlers(server);
     await rootsManager.recomputeAllowedDirectories();
     await server.connect(transport);
-    const transportAny = transport;
-    const sdkOnClose = transportAny.onclose;
-    transportAny.onclose = () => {
+    const sdkOnClose = transport.onclose;
+    transport.onclose = () => {
         rootsManager.destroy();
         sdkOnClose?.();
     };
     rootsManager.logMissingDirectoriesIfNeeded(server);
 }
-const MAX_REQUEST_BODY_BYTES = parseInt(process.env['FS_CONTEXT_MAX_REQUEST_BYTES'] ?? '', 10) ||
-    4 * 1024 * 1024; // 4 MB default
+const MAX_REQUEST_BODY_BYTES = parseEnvInt('FS_CONTEXT_MAX_REQUEST_BYTES', 4 * 1024 * 1024, 1024, 256 * 1024 * 1024);
 class RequestBodyError extends Error {
     statusCode;
     constructor(message, statusCode) {

package/dist/tools/list-directory.js

@@ -4,7 +4,7 @@ import { DEFAULT_EXCLUDE_PATTERNS } from '../lib/constants.js';
 import { ErrorCode } from '../lib/errors.js';
 import { listDirectory } from '../lib/file-operations/list-directory.js';
 import { ListDirectoryInputSchema, ListDirectoryOutputSchema, } from '../schemas.js';
-import { buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildToolErrorResponse, buildToolResponse, decodeOffsetCursor, encodeOffsetCursor, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 export const LIST_DIRECTORY_TOOL = {
     name: 'ls',
@@ -82,27 +82,9 @@ function buildStructuredListResult(result, nextCursor) {
         ...(nextCursor !== undefined ? { nextCursor } : {}),
     };
 }
-function encodeCursor(offset) {
-    return Buffer.from(JSON.stringify({ offset })).toString('base64url');
-}
-function decodeCursor(cursor) {
-    try {
-        const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf-8'));
-        if (typeof parsed === 'object' &&
-            parsed !== null &&
-            typeof parsed.offset === 'number') {
-            const { offset } = parsed;
-            return Number.isInteger(offset) && offset >= 0 ? offset : 0;
-        }
-    }
-    catch {
-        // ignore malformed cursor
-    }
-    return 0;
-}
 async function handleListDirectory(args, signal) {
     const dirPath = resolvePathOrRoot(args.path);
-    const cursorOffset = args.cursor !== undefined ? decodeCursor(args.cursor) : 0;
+    const cursorOffset = args.cursor !== undefined ? decodeOffsetCursor(args.cursor) : 0;
     const pageSize = args.maxEntries;
     const options = {
         includeHidden: args.includeHidden,
@@ -117,7 +99,7 @@ async function handleListDirectory(args, signal) {
     const result = await listDirectory(dirPath, options);
     const displayEntries = cursorOffset > 0 ? result.entries.slice(cursorOffset) : result.entries;
     const nextCursor = result.summary.truncated && displayEntries.length > 0
-        ? encodeCursor(cursorOffset + displayEntries.length)
+        ? encodeOffsetCursor(cursorOffset + displayEntries.length)
         : undefined;
     const displayResult = { ...result, entries: displayEntries };
     return buildToolResponse(buildListTextResult(displayResult, nextCursor), buildStructuredListResult(displayResult, nextCursor));

package/dist/tools/read-multiple.js

@@ -3,7 +3,7 @@ import { DEFAULT_READ_MANY_MAX_TOTAL_SIZE, DEFAULT_SEARCH_TIMEOUT_MS, } from '..
 import { ErrorCode } from '../lib/errors.js';
 import { readMultipleFiles } from '../lib/file-operations/read-multiple-files.js';
 import { ReadMultipleFilesInputSchema, ReadMultipleFilesOutputSchema, } from '../schemas.js';
-import { buildResourceLink, buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, maybeExternalizeTextContent, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildBatchPathContext, buildResourceLink, buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, maybeExternalizeTextContent, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 export const READ_MULTIPLE_FILES_TOOL = {
     name: 'read_many',
@@ -20,6 +20,23 @@ export const READ_MULTIPLE_FILES_TOOL = {
         'Per-file `truncationReason` can be `head`, `range`, or `externalized`.',
     ],
 };
+function buildReadManyCompletionSuffix(summary) {
+    const total = summary?.total ?? 0;
+    const failed = summary?.failed ?? 0;
+    const succeeded = summary?.succeeded ?? 0;
+    if (failed) {
+        return `${succeeded}/${total} read, ${failed} failed`;
+    }
+    const label = total === 1 ? 'file' : 'files';
+    return `${total} ${label} read`;
+}
+function createReadManyProgressCallbacks(extra, context, totalPaths) {
+    const progress = createToolProgressSession(extra, `🕮 read_many: ${context}`);
+    const onReadComplete = () => {
+        progress.increment((current) => `🕮 read_many: ${context} [${current}/${totalPaths} read]`);
+    };
+    return { progress, onReadComplete };
+}
 function toStructuredReadManyResult(result) {
     const structured = {
         path: result.path,
@@ -134,28 +151,13 @@ export function registerReadMultipleFilesTool(server, options = {}) {
             timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
             context: { path: primaryPath },
             run: async (signal) => {
-                const first = path.basename(args.paths[0] ?? '');
-                const extraPaths = args.paths.length > 1
-                    ? `, ${path.basename(args.paths[1] ?? '')}${args.paths.length > 2 ? '…' : ''}`
-                    : '';
-                const context = `${args.paths.length} files [${first}${extraPaths}]`;
-                const progress = createToolProgressSession(extra, `🕮 read_many: ${context}`);
-                const onReadComplete = () => {
-                    progress.increment((current) => `🕮 read_many: ${context} [${current}/${args.paths.length} read]`);
-                };
+                const context = buildBatchPathContext(args.paths, 'files');
+                const { progress, onReadComplete } = createReadManyProgressCallbacks(extra, context, args.paths.length);
                 try {
                     const result = await handleReadMultipleFiles(args, signal, options.resourceStore, onReadComplete);
                     const sc = result.structuredContent;
+                    const suffix = buildReadManyCompletionSuffix(sc.summary);
                     const total = sc.summary?.total ?? 0;
-                    const failed = sc.summary?.failed ?? 0;
-                    const succeeded = sc.summary?.succeeded ?? 0;
-                    let suffix;
-                    if (failed) {
-                        suffix = `${succeeded}/${total} read, ${failed} failed`;
-                    }
-                    else {
-                        suffix = `${total} files read`;
-                    }
                     const finalCurrent = Math.max(total, progress.getCurrent() + 1);
                     progress.complete(`🕮 read_many: ${context} • ${suffix}`, finalCurrent);
                     return result;

package/dist/tools/search-files.js

@@ -4,26 +4,8 @@ import { DEFAULT_EXCLUDE_PATTERNS, DEFAULT_SEARCH_TIMEOUT_MS, } from '../lib/con
 import { ErrorCode } from '../lib/errors.js';
 import { searchFiles } from '../lib/file-operations/search-files.js';
 import { SearchFilesInputSchema, SearchFilesOutputSchema } from '../schemas.js';
-import { buildToolErrorResponse, buildToolResponse, createProgressReporter, executeToolWithDiagnostics, notifyProgress, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildToolErrorResponse, buildToolResponse, createProgressReporter, decodeOffsetCursor, encodeOffsetCursor, executeToolWithDiagnostics, notifyProgress, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
-function encodeCursor(offset) {
-    return Buffer.from(JSON.stringify({ offset })).toString('base64url');
-}
-function decodeCursor(cursor) {
-    try {
-        const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf-8'));
-        if (typeof parsed === 'object' &&
-            parsed !== null &&
-            typeof parsed.offset === 'number') {
-            const { offset } = parsed;
-            return Number.isInteger(offset) && offset >= 0 ? offset : 0;
-        }
-    }
-    catch {
-        // ignore malformed cursor
-    }
-    return 0;
-}
 export const SEARCH_FILES_TOOL = {
     name: 'find',
     title: 'Find Files',
@@ -43,7 +25,7 @@ export const SEARCH_FILES_TOOL = {
 async function handleSearchFiles(args, signal, onProgress) {
     const basePath = resolvePathOrRoot(args.path);
     const excludePatterns = args.includeIgnored ? [] : DEFAULT_EXCLUDE_PATTERNS;
-    const cursorOffset = args.cursor !== undefined ? decodeCursor(args.cursor) : 0;
+    const cursorOffset = args.cursor !== undefined ? decodeOffsetCursor(args.cursor) : 0;
     const pageSize = args.maxResults;
     const fetchMax = cursorOffset + pageSize;
     const searchOptions = {
@@ -59,7 +41,7 @@ async function handleSearchFiles(args, signal, onProgress) {
     const allResults = result.results;
     const displayResults = cursorOffset > 0 ? allResults.slice(cursorOffset) : allResults;
     const nextCursor = result.summary.truncated && displayResults.length > 0
-        ? encodeCursor(cursorOffset + displayResults.length)
+        ? encodeOffsetCursor(cursorOffset + displayResults.length)
         : undefined;
     const relativeResults = [];
     for (const entry of displayResults) {

package/dist/tools/shared.d.ts

@@ -139,3 +139,6 @@ export declare function wrapToolHandler<Args, Result>(handler: (args: Args, extr
  * See `src/server/roots-manager.ts` for the update lifecycle.
  */
 export declare function resolvePathOrRoot(pathValue: string | undefined): string;
+export declare function encodeOffsetCursor(offset: number): string;
+export declare function decodeOffsetCursor(cursor: string): number;
+export declare function buildBatchPathContext(paths: readonly string[], unitLabel?: string): string;

package/dist/tools/shared.js

@@ -1,3 +1,4 @@
+import * as path from 'node:path';
 import { channel } from 'node:diagnostics_channel';
 import { z } from 'zod';
 import { parseTrueEnvFlag } from '../lib/constants.js';
@@ -403,3 +404,29 @@ export function resolvePathOrRoot(pathValue) {
     }
     return root;
 }
+export function encodeOffsetCursor(offset) {
+    return Buffer.from(JSON.stringify({ offset })).toString('base64url');
+}
+export function decodeOffsetCursor(cursor) {
+    try {
+        const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf-8'));
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            typeof parsed.offset === 'number') {
+            const { offset } = parsed;
+            return Number.isInteger(offset) && offset >= 0 ? offset : 0;
+        }
+    }
+    catch {
+        // ignore malformed cursor
+    }
+    return 0;
+}
+export function buildBatchPathContext(paths, unitLabel = 'paths') {
+    const normalizedLabel = paths.length === 1 ? unitLabel.replace(/s$/i, '') : unitLabel;
+    const first = path.basename(paths[0] ?? '');
+    const extraPaths = paths.length > 1
+        ? `, ${path.basename(paths[1] ?? '')}${paths.length > 2 ? '…' : ''}`
+        : '';
+    return `${paths.length} ${normalizedLabel} [${first}${extraPaths}]`;
+}

package/dist/tools/stat-many.js

@@ -1,10 +1,9 @@
-import * as path from 'node:path';
 import { formatBytes, joinLines } from '../config.js';
 import { DEFAULT_SEARCH_TIMEOUT_MS } from '../lib/constants.js';
 import { ErrorCode } from '../lib/errors.js';
 import { getMultipleFileInfo } from '../lib/file-operations/file-info.js';
 import { GetMultipleFileInfoInputSchema, GetMultipleFileInfoOutputSchema, } from '../schemas.js';
-import { buildFileInfoPayload, buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildBatchPathContext, buildFileInfoPayload, buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 export const GET_MULTIPLE_FILE_INFO_TOOL = {
     name: 'stat_many',
@@ -16,6 +15,22 @@ export const GET_MULTIPLE_FILE_INFO_TOOL = {
     taskSupport: 'optional',
     nuances: ['Use before read/search when file size/type uncertainty exists.'],
 };
+function buildStatManyCompletionSuffix(summary) {
+    const total = summary?.total ?? 0;
+    const failed = summary?.failed ?? 0;
+    const succeeded = summary?.succeeded ?? 0;
+    if (failed) {
+        return `${succeeded}/${total} OK, ${failed} failed`;
+    }
+    return `${total} OK`;
+}
+function createStatManyProgressCallbacks(extra, context, totalPaths) {
+    const progress = createToolProgressSession(extra, `🕮 stat_many: ${context}`);
+    const onProgress = () => {
+        progress.increment((current) => `🕮 stat_many: ${context} [${current}/${totalPaths} scanned]`);
+    };
+    return { progress, onProgress };
+}
 function formatFileInfoDetail(info) {
     const lines = [
         `${info.name} (${info.type})`,
@@ -74,28 +89,13 @@ export function registerGetMultipleFileInfoTool(server, options = {}) {
             timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
             context: { path: primaryPath },
             run: async (signal) => {
-                const first = path.basename(args.paths[0] ?? '');
-                const extraPaths = args.paths.length > 1
-                    ? `, ${path.basename(args.paths[1] ?? '')}${args.paths.length > 2 ? '…' : ''}`
-                    : '';
-                const context = `${args.paths.length} paths [${first}${extraPaths}]`;
-                const progress = createToolProgressSession(extra, `🕮 stat_many: ${context}`);
-                const onProgress = () => {
-                    progress.increment((current) => `🕮 stat_many: ${context} [${current}/${args.paths.length} scanned]`);
-                };
+                const context = buildBatchPathContext(args.paths);
+                const { progress, onProgress } = createStatManyProgressCallbacks(extra, context, args.paths.length);
                 try {
                     const result = await handleGetMultipleFileInfo(args, signal, onProgress);
                     const sc = result.structuredContent;
+                    const suffix = buildStatManyCompletionSuffix(sc.summary);
                     const total = sc.summary?.total ?? 0;
-                    const failed = sc.summary?.failed ?? 0;
-                    const succeeded = sc.summary?.succeeded ?? 0;
-                    let suffix;
-                    if (failed) {
-                        suffix = `${succeeded}/${total} OK, ${failed} failed`;
-                    }
-                    else {
-                        suffix = `${total} OK`;
-                    }
                     const finalCurrent = Math.max(total, progress.getCurrent() + 1);
                     progress.complete(`🕮 stat_many: ${context} • ${suffix}`, finalCurrent);
                     return result;

package/dist/tools/task-support.js

@@ -20,14 +20,16 @@ function getExperimentalTaskRegistration(server) {
     return tasks;
 }
 function hasTaskToolCapability(server) {
-    const maybeServer = server;
-    const serverRuntime = maybeServer.server;
-    const capabilityGetter = serverRuntime?.getCapabilities;
-    if (typeof capabilityGetter !== 'function') {
+    const serverRecord = server;
+    const { server: serverRuntime } = serverRecord;
+    if (!isRecord(serverRuntime))
+        return true;
+    const { getCapabilities } = serverRuntime;
+    if (typeof getCapabilities !== 'function') {
         // Fallback for tests or custom wrappers that provide only registerTool/experimental.
         return true;
     }
-    const capabilities = capabilityGetter.call(serverRuntime);
+    const capabilities = getCapabilities.call(serverRuntime);
     if (!isRecord(capabilities))
         return false;
     const { tasks } = capabilities;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@j0hanz/filesystem-mcp",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "mcpName": "io.github.j0hanz/filesystem-mcp",
   "description": "MCP Server that enables LLMs to interact with the local filesystem.",
   "type": "module",