@j0hanz/filesystem-mcp 1.19.0 → 2.0.0

package/dist/tools/move-file.js

@@ -1,178 +0,0 @@
-import { cp, mkdir, rename, rm, stat } from 'node:fs/promises';
-import { basename, dirname, join, resolve, sep } from 'node:path';
-import { withAbort } from '../lib/abort.js';
-import { ErrorCode, formatUnknownErrorMessage, isNodeError, McpError, } from '../lib/errors.js';
-import { Logger } from '../lib/logger.js';
-import { assertAllowedFileAccess, validateExistingPath, validatePathForWrite, } from '../lib/paths.js';
-import { MoveFileInputSchema, MoveFileOutputSchema } from '../schemas.js';
-import { FILE_MOVE_ICONS } from './icons.js';
-import { buildStructuredError, buildToolErrorResponse, buildToolResponse, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, } from './shared.js';
-import { registerStandardTool } from './task-support.js';
-export const MOVE_FILE_TOOL = {
-    name: 'mv',
-    title: 'Move File',
-    description: 'Move or rename a file or directory.',
-    inputSchema: MoveFileInputSchema,
-    outputSchema: MoveFileOutputSchema,
-    annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
-    icons: FILE_MOVE_ICONS,
-    gotchas: [
-        'On POSIX, an existing destination is silently overwritten; on Windows, rename fails with EEXIST if destination exists.',
-    ],
-    taskSupport: 'forbidden',
-};
-function toMoveFailure(source, error, defaultCode = ErrorCode.UNKNOWN) {
-    return {
-        source,
-        error: buildStructuredError(error, defaultCode, source),
-    };
-}
-async function handleMoveError(error, src, validSource, targetPath, movedSources, failed, signal) {
-    if (isNodeError(error) && error.code === 'EXDEV') {
-        try {
-            await withAbort(cp(validSource, targetPath, { recursive: true }), signal);
-        }
-        catch (copyError) {
-            failed.push(toMoveFailure(src, copyError));
-            return;
-        }
-        try {
-            await withAbort(rm(validSource, { recursive: true, force: true }), signal);
-            movedSources.push(validSource);
-        }
-        catch (deleteError) {
-            try {
-                await rm(targetPath, { recursive: true, force: true });
-            }
-            catch {
-                failed.push(toMoveFailure(src, new McpError(ErrorCode.UNKNOWN, `Cross-device move partial: data at both source and destination. ${formatUnknownErrorMessage(deleteError)}`, src)));
-                return;
-            }
-            failed.push(toMoveFailure(src, new McpError(ErrorCode.UNKNOWN, `Cross-device move failed: source not removed. ${formatUnknownErrorMessage(deleteError)}`, src)));
-        }
-    }
-    else {
-        failed.push(toMoveFailure(src, error));
-    }
-}
-async function processSingleMove(src, destIsDirectory, validDest, movedSources, failed, signal) {
-    let validSource;
-    try {
-        validSource = await validateExistingPath(src, signal);
-        assertAllowedFileAccess(src, validSource);
-    }
-    catch (error) {
-        failed.push(toMoveFailure(src, error, ErrorCode.ACCESS_DENIED));
-        return;
-    }
-    const targetPath = destIsDirectory
-        ? join(validDest, basename(validSource))
-        : validDest;
-    if (resolve(validSource) === resolve(targetPath)) {
-        return;
-    }
-    if (resolve(targetPath).startsWith(resolve(validSource) + sep)) {
-        failed.push(toMoveFailure(src, new McpError(ErrorCode.INVALID_INPUT, 'Cannot move a directory into its own subdirectory', src), ErrorCode.INVALID_INPUT));
-        return;
-    }
-    try {
-        await withAbort(rename(validSource, targetPath), signal);
-        movedSources.push(validSource);
-    }
-    catch (error) {
-        await handleMoveError(error, src, validSource, targetPath, movedSources, failed, signal);
-    }
-}
-async function getDestinationStatus(validDest) {
-    try {
-        const stats = await stat(validDest);
-        return stats.isDirectory();
-    }
-    catch (error) {
-        if (isNodeError(error) && error.code !== 'ENOENT') {
-            throw error;
-        }
-    }
-    return false;
-}
-function formatMoveMessage(moved, failed, destination) {
-    const movedItemStr = `item${moved === 1 ? '' : 's'}`;
-    const failedItemStr = `item${failed === 1 ? '' : 's'}`;
-    if (failed > 0) {
-        return `Moved ${moved} ${movedItemStr}; failed to move ${failed} ${failedItemStr}`;
-    }
-    return `Successfully moved ${moved} ${movedItemStr} to ${destination}`;
-}
-async function handleMoveFile(args, signal) {
-    const sources = args.sources ?? (args.source ? [args.source] : []);
-    if (sources.length === 0) {
-        throw new McpError(ErrorCode.INVALID_INPUT, 'No sources provided.');
-    }
-    const validDest = await validatePathForWrite(args.destination, signal);
-    const destIsDirectory = await getDestinationStatus(validDest);
-    if (sources.length > 1 && !destIsDirectory) {
-        throw new McpError(ErrorCode.INVALID_INPUT, 'Destination must be an existing directory for multiple sources.');
-    }
-    if (!destIsDirectory) {
-        await withAbort(mkdir(dirname(validDest), { recursive: true }), signal);
-    }
-    const movedSources = [];
-    const failed = [];
-    for (const src of sources) {
-        await processSingleMove(src, destIsDirectory, validDest, movedSources, failed, signal);
-    }
-    const message = formatMoveMessage(movedSources.length, failed.length, args.destination);
-    const movedSource = sources.length === 1 ? movedSources[0] : undefined;
-    const failedSuffix = failed.length > 0 ? ` (${failed.length} failed)` : '';
-    Logger.info(`mv: ${movedSources.length} item(s) → ${args.destination}${failedSuffix}`);
-    if (movedSources.length === 0 && failed.length > 0) {
-        const firstFailure = failed[0];
-        if (firstFailure) {
-            throw new McpError(firstFailure.error.code, message, firstFailure.error.path);
-        }
-    }
-    return buildToolResponse(message, {
-        ok: failed.length === 0,
-        ...(movedSource ? { source: movedSource } : {}),
-        sources: movedSources,
-        destination: validDest,
-        ...(failed.length > 0 ? { failed } : {}),
-    });
-}
-export function registerMoveFileTool(server, options = {}) {
-    const handler = (args, ctx) => executeToolWithDiagnostics({
-        toolName: 'mv',
-        ctx,
-        outputSchema: MoveFileOutputSchema,
-        timedSignal: {},
-        context: { path: args.source ?? args.sources?.[0] },
-        run: async (signal) => {
-            const result = await handleMoveFile(args, signal);
-            void ctx.log?.('info', `mv: ${args.source ?? args.sources?.join(', ') ?? ''} \u2192 ${args.destination}`);
-            return result;
-        },
-        onError: (error) => buildToolErrorResponse(error, ErrorCode.UNKNOWN, args.source ?? args.sources?.[0]),
-    });
-    registerStandardTool(server, MOVE_FILE_TOOL, handler, options, {
-        progressMessage: (args) => {
-            const dest = basename(args.destination);
-            if (args.source && !args.sources?.length) {
-                return `${MOVE_FILE_TOOL.title}: ${basename(args.source)} → ${dest}`;
-            }
-            const count = (args.source ? 1 : 0) + (args.sources?.length ?? 0);
-            return `${MOVE_FILE_TOOL.title}: ${count} items → ${dest}`;
-        },
-        completionMessage: (args, result) => {
-            const dest = basename(args.destination);
-            if (args.source && !args.sources?.length) {
-                const src = basename(args.source);
-                if (result.isError)
-                    return `${MOVE_FILE_TOOL.title}: ${src} → ${dest} • ${result.errorCode}`;
-            }
-            const count = (args.source ? 1 : 0) + (args.sources?.length ?? 0);
-            if (result.isError)
-                return `${MOVE_FILE_TOOL.title}: ${count} items → ${dest} • ${result.errorCode}`;
-            return `${MOVE_FILE_TOOL.title}: ${count} items → ${dest}`;
-        },
-    });
-}

package/dist/tools/read-multiple.d.ts

@@ -1,4 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/server';
-import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
-export declare const READ_MANY_TOOL: ToolContract;
-export declare function registerReadMultipleFilesTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/read-multiple.js

@@ -1,207 +0,0 @@
-import { basename } from 'node:path';
-import { DEFAULT_SEARCH_TIMEOUT_MS } from '../lib/constants.js';
-import { classifyError, ErrorCode } from '../lib/errors.js';
-import { readMultipleFiles } from '../lib/file-operations/metadata.js';
-import { ReadMultipleFilesInputSchema, ReadMultipleFilesOutputSchema, } from '../schemas.js';
-import { FILE_READ_ICONS } from './icons.js';
-import { buildBatchPathContext, buildResourceLink, buildStructuredError, buildToolErrorResponse, buildToolResponse, createBatchProgressCallbacks, executeToolWithDiagnostics, maybeExternalizeTextContent, READ_ONLY_TOOL_ANNOTATIONS, resolveFinalProgressCurrent, } from './shared.js';
-import { registerStandardTool, reportTaskStatus } from './task-support.js';
-const READ_MANY_TOOL_NAME = 'read_many';
-const FULL_FILE_CONTENTS_DESCRIPTION = 'Full file contents';
-export const READ_MANY_TOOL = {
-    name: READ_MANY_TOOL_NAME,
-    title: 'Read Multiple Files',
-    description: 'Read multiple text files in one request with contents and metadata. ' +
-        'For a single file, use `read`.',
-    inputSchema: ReadMultipleFilesInputSchema,
-    outputSchema: ReadMultipleFilesOutputSchema,
-    annotations: READ_ONLY_TOOL_ANNOTATIONS,
-    icons: FILE_READ_ICONS,
-    taskSupport: 'optional',
-};
-const READ_MANY_TOOL_LABEL = READ_MANY_TOOL.title;
-function buildReadManyResourceName(filePath) {
-    return `read:${basename(filePath)}`;
-}
-function toStructuredReadManyResult(result) {
-    const structuredResult = {
-        path: result.path,
-    };
-    if (result.content !== undefined)
-        structuredResult.content = result.content;
-    if (result.truncated)
-        structuredResult.truncated = true;
-    if (result.resourceUri)
-        structuredResult.resourceUri = result.resourceUri;
-    if (result.head !== undefined)
-        structuredResult.head = result.head;
-    if (result.tail !== undefined)
-        structuredResult.tail = result.tail;
-    if (result.startLine !== undefined) {
-        structuredResult.startLine = result.startLine;
-    }
-    if (result.endLine !== undefined)
-        structuredResult.endLine = result.endLine;
-    if (result.hasMoreLines)
-        structuredResult.hasMoreLines = true;
-    if (result.totalLines !== undefined) {
-        structuredResult.totalLines = result.totalLines;
-    }
-    if (result.linesRead !== undefined) {
-        structuredResult.linesRead = result.linesRead;
-    }
-    if (result.truncationReason) {
-        structuredResult.truncationReason = result.truncationReason;
-    }
-    if (result.error)
-        structuredResult.error = result.error;
-    return structuredResult;
-}
-function resolveReadManyTruncationReason(result) {
-    if (!result.truncated)
-        return undefined;
-    if (result.readMode === 'head')
-        return 'head';
-    if (result.readMode === 'tail')
-        return 'tail';
-    if (result.readMode === 'range')
-        return 'range';
-    return undefined;
-}
-function maybeExternalizeReadManyResult(result, resourceStore) {
-    const truncationReason = resolveReadManyTruncationReason(result);
-    const { error, ...rest } = result;
-    const baseResult = {
-        ...rest,
-        ...(error
-            ? { error: buildStructuredError(error, ErrorCode.UNKNOWN, result.path) }
-            : {}),
-        ...(truncationReason ? { truncationReason } : {}),
-    };
-    if (!result.content) {
-        return baseResult;
-    }
-    const externalized = maybeExternalizeTextContent(resourceStore, result.content, { name: buildReadManyResourceName(result.path), mimeType: 'text/plain' });
-    if (!externalized) {
-        return baseResult;
-    }
-    return {
-        ...baseResult,
-        content: externalized.preview,
-        truncated: true,
-        resourceUri: externalized.entry.uri,
-        truncationReason: 'externalized',
-        expiresAt: externalized.entry.expiresAt,
-    };
-}
-function buildReadManyTextSection(result) {
-    const header = `=== ${result.path} ===`;
-    if (result.error) {
-        return `${header}\nError [${result.error.code}]: ${result.error.message}`;
-    }
-    return `${header}\n${result.content ?? ''}`;
-}
-function buildReadMultipleOptions(args, signal, onReadComplete) {
-    const options = {};
-    if (signal)
-        options.signal = signal;
-    if (args.head !== undefined)
-        options.head = args.head;
-    if (args.tail !== undefined)
-        options.tail = args.tail;
-    if (args.startLine !== undefined)
-        options.startLine = args.startLine;
-    if (args.endLine !== undefined)
-        options.endLine = args.endLine;
-    if (onReadComplete)
-        options.onReadComplete = onReadComplete;
-    return options;
-}
-function buildReadManyResponsePayload(results, resourceStore) {
-    const resourceLinks = [];
-    const structuredResults = [];
-    const textSections = [];
-    let succeeded = 0;
-    for (const result of results) {
-        const mappedResult = maybeExternalizeReadManyResult(result, resourceStore);
-        structuredResults.push(toStructuredReadManyResult(mappedResult));
-        textSections.push(buildReadManyTextSection(mappedResult));
-        if (mappedResult.resourceUri) {
-            resourceLinks.push(buildResourceLink({
-                uri: mappedResult.resourceUri,
-                name: buildReadManyResourceName(mappedResult.path),
-                description: FULL_FILE_CONTENTS_DESCRIPTION,
-                ...(mappedResult.expiresAt
-                    ? { expiresAt: mappedResult.expiresAt }
-                    : {}),
-            }));
-        }
-        if (mappedResult.error === undefined)
-            succeeded += 1;
-    }
-    const total = structuredResults.length;
-    return {
-        resourceLinks,
-        structuredResults,
-        summary: {
-            total,
-            succeeded,
-            failed: total - succeeded,
-        },
-        text: textSections.join('\n\n'),
-    };
-}
-async function handleReadMultipleFiles(args, signal, resourceStore, onReadComplete) {
-    const options = buildReadMultipleOptions(args, signal, onReadComplete);
-    const results = await readMultipleFiles(args.paths, options);
-    const payload = buildReadManyResponsePayload(results, resourceStore);
-    const structured = {
-        ok: true,
-        results: payload.structuredResults,
-        summary: payload.summary,
-    };
-    return buildToolResponse(payload.text, structured, payload.resourceLinks);
-}
-export function registerReadMultipleFilesTool(server, options = {}) {
-    const handler = (args, ctx) => {
-        const primaryPath = args.paths[0] ?? '';
-        return executeToolWithDiagnostics({
-            toolName: READ_MANY_TOOL_NAME,
-            ctx,
-            outputSchema: ReadMultipleFilesOutputSchema,
-            timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
-            context: { path: primaryPath },
-            run: async (signal) => {
-                const context = buildBatchPathContext(args.paths, 'files');
-                const { progress, onItemComplete: rawOnItemComplete } = createBatchProgressCallbacks(ctx, {
-                    toolLabel: READ_MANY_TOOL_LABEL,
-                    context,
-                    totalItems: args.paths.length,
-                    itemVerb: 'read',
-                });
-                let itemsDone = 0;
-                const onItemComplete = () => {
-                    rawOnItemComplete();
-                    itemsDone++;
-                    void reportTaskStatus(`${READ_MANY_TOOL_LABEL}: ${context} [${itemsDone}/${args.paths.length} read]`);
-                };
-                try {
-                    const result = await handleReadMultipleFiles(args, signal, options.resourceStore, onItemComplete);
-                    const sc = result.structuredContent;
-                    const total = sc.summary?.total ?? 0;
-                    const failed = sc.summary?.failed ?? 0;
-                    const suffix = failed ? `${failed} failed` : 'done';
-                    const finalCurrent = resolveFinalProgressCurrent(progress, total);
-                    progress.complete(`${READ_MANY_TOOL_LABEL}: ${context} • ${suffix}`, finalCurrent);
-                    return result;
-                }
-                catch (error) {
-                    progress.fail(`${READ_MANY_TOOL_LABEL}: ${context} • ${classifyError(error)}`);
-                    throw error;
-                }
-            },
-            onError: (error) => buildToolErrorResponse(error, ErrorCode.NOT_FILE, primaryPath),
-        });
-    };
-    registerStandardTool(server, READ_MANY_TOOL, handler, options);
-}

package/dist/tools/shared.d.ts

@@ -1,172 +0,0 @@
-import type { ContentBlock, Icon, LoggingLevel, Notification, RequestMeta, ServerContext } from '@modelcontextprotocol/server';
-import { z } from 'zod';
-import { ErrorCode } from '../lib/errors.js';
-import type { ResourceStore } from '../lib/resource-store.js';
-import type { FileInfo } from '../config.js';
-export { type ToolContract } from './contract.js';
-export declare const READ_ONLY_TOOL_ANNOTATIONS: {
-    readonly readOnlyHint: true;
-    readonly idempotentHint: true;
-    readonly destructiveHint: false;
-    readonly openWorldHint: false;
-};
-export declare const DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS: {
-    readonly readOnlyHint: false;
-    readonly idempotentHint: false;
-    readonly destructiveHint: true;
-    readonly openWorldHint: false;
-};
-export declare const IDEMPOTENT_WRITE_TOOL_ANNOTATIONS: {
-    readonly readOnlyHint: false;
-    readonly idempotentHint: true;
-    readonly destructiveHint: false;
-    readonly openWorldHint: false;
-};
-export type TaskSupportLevel = 'optional' | 'required' | 'forbidden';
-export declare function resolveToolTaskSupportLevel(topLevelTaskSupport: unknown, executionTaskSupport: unknown): TaskSupportLevel | undefined;
-export declare function maybeStripStructuredContentFromResult<T extends object>(result: T): T;
-type ResourceEntry = ReturnType<ResourceStore['putText']>;
-export declare function maybeExternalizeTextContent(resourceStore: ResourceStore | undefined, content: string, params: {
-    name: string;
-    mimeType?: string;
-}): {
-    entry: ResourceEntry;
-    preview: string;
-} | undefined;
-export declare function buildResourceLink(params: {
-    uri: string;
-    name: string;
-    mimeType?: string;
-    description?: string;
-    expiresAt?: string;
-}): ContentBlock;
-export declare function buildStructuredError(error: unknown, defaultCode: ErrorCode, path?: string): {
-    code: ErrorCode;
-    message: string;
-    path?: string;
-    suggestion?: string;
-};
-export declare function buildToolResponse<T>(text: string, structuredContent: T, extraContent?: ContentBlock[]): {
-    content: ContentBlock[];
-    structuredContent: T;
-};
-export type ToolResponse<T> = ReturnType<typeof buildToolResponse<T>> & {
-    isError?: never;
-} & Record<string, unknown>;
-interface ToolErrorResponse extends Record<string, unknown> {
-    content: ContentBlock[];
-    isError: true;
-    errorCode: ErrorCode;
-}
-export type ToolResult<T> = ToolResponse<T> | ToolErrorResponse;
-export declare function withValidatedArgs<Args, Result>(schema: z.ZodType<Args>, handler: (args: Args, ctx: ToolContext) => Promise<ToolResult<Result>>): (args: unknown, ctx: ToolContext | ServerContext) => Promise<ToolResult<Result>>;
-/**
- * App-level tracing metadata passed through {@linkcode RequestMeta}.
- * These fields are preserved by the SDK's loose `RequestMeta` type.
- */
-interface TracingMeta {
-    traceparent?: string | undefined;
-    tracestate?: string | undefined;
-    baggage?: string | undefined;
-}
-export interface ToolContext {
-    signal?: AbortSignal;
-    sessionId?: string;
-    _meta?: (RequestMeta & TracingMeta) | undefined;
-    sendNotification?: (notification: Notification) => Promise<void>;
-    log?: (level: LoggingLevel, data: unknown, logger?: string) => Promise<void>;
-}
-export declare function toToolContext(ctx?: ToolContext | ServerContext): ToolContext;
-export interface IconInfo {
-    src: string;
-    mimeType: string;
-}
-export declare function withDefaultIcons<T extends object>(tool: T, iconInfo: IconInfo | undefined): T & {
-    icons?: Icon[];
-};
-export interface ToolRegistrationOptions {
-    resourceStore?: ResourceStore;
-    isInitialized?: () => boolean;
-    serverIcon?: string;
-    iconInfo?: IconInfo;
-}
-interface FileInfoPayload {
-    name: string;
-    path: string;
-    type: FileInfo['type'];
-    size: number;
-    tokenEstimate?: number;
-    created: string;
-    modified: string;
-    accessed: string;
-    permissions: string;
-    isHidden: boolean;
-    mimeType?: string;
-    symlinkTarget?: string;
-}
-export declare function buildFileInfoPayload(info: FileInfo): FileInfoPayload;
-interface ToolExecutionOptions<T> {
-    toolName: string;
-    ctx: ToolContext;
-    outputSchema?: z.ZodType<T>;
-    run: (signal: AbortSignal | undefined) => ToolResponse<T> | Promise<ToolResponse<T>>;
-    onError: (error: unknown) => ToolResult<T>;
-    context?: Record<string, unknown>;
-    timedSignal?: {
-        timeoutMs?: number;
-    };
-}
-export declare function executeToolWithDiagnostics<T>(options: ToolExecutionOptions<T>): Promise<ToolResult<T>>;
-export declare function buildToolErrorResponse(error: unknown, defaultCode: ErrorCode, path?: string): ToolErrorResponse;
-export declare function createProgressReporter(ctx: ToolContext): (progress: {
-    total?: number;
-    current: number;
-    message?: string;
-}) => void;
-export declare function notifyProgress(ctx: ToolContext, progress: {
-    current: number;
-    total?: number;
-    message?: string;
-}): void;
-interface ToolProgressSession {
-    update: (progress: {
-        current: number;
-        total?: number;
-        message: string;
-    }) => void;
-    increment: (messageForCurrent: (current: number) => string) => void;
-    complete: (message: string, minimumCurrent?: number) => void;
-    fail: (message: string, minimumCurrent?: number) => void;
-    getCurrent: () => number;
-}
-interface BatchProgressCallbacks {
-    progress: ToolProgressSession;
-    onItemComplete: () => void;
-}
-export declare function createToolProgressSession(ctx: ToolContext, startMessage: string, initialTotal?: number): ToolProgressSession;
-export declare function createBatchProgressCallbacks(ctx: ToolContext, params: {
-    toolLabel: string;
-    context: string;
-    totalItems: number;
-    itemVerb: string;
-}): BatchProgressCallbacks;
-export declare function resolveFinalProgressCurrent(progress: ToolProgressSession, ...candidates: number[]): number;
-export declare function wrapToolHandler<Args, Result>(handler: (args: Args, ctx: ToolContext) => Promise<ToolResult<Result>>, options: {
-    guard?: (() => boolean) | undefined;
-    progressMessage?: (args: Args) => string;
-    completionMessage?: (args: Args, result: ToolResult<Result>) => string | undefined;
-}): (args: Args, ctx?: ToolContext | ServerContext) => Promise<ToolResult<Result>>;
-/**
- * Returns `pathValue` if non-empty; otherwise resolves to the single allowed
- * directory from module-level state managed by `RootsManager`. Throws when the
- * path is ambiguous (multiple roots) or when no roots are configured.
- *
- * NOTE: Depends on `getAllowedDirectories()` which reads module-level state
- * updated by `RootsManager`. Ensure the server is initialized before calling.
- * 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;
-export declare function truncateProgressPattern(pattern: string, maxLength?: number): string;