filesystem-mcp

Instructions

Implementation Reference

• src/handlers/create-directories.ts:185-223 (handler)

  Core handler logic: validates args with Zod, resolves and creates directories recursively using fs.mkdir, handles EEXIST by checking if directory, permission errors, etc., processes multiple paths in parallel with Promise.allSettled, sorts results by input order, returns JSON of results.

  export const handleCreateDirectoriesInternal = async (
    args: unknown,
    deps: CreateDirsDeps,
  ): Promise<McpToolResponse> => {
    let pathsToCreate: string[];
    try {
      // Validate arguments first
      const validatedArgs = parseAndValidateArgs(args);
      pathsToCreate = validatedArgs.paths;
    } catch (error) {
      // If validation fails, re-throw the McpError from parseAndValidateArgs
      if (error instanceof McpError) {
        throw error;
      }
      // Wrap unexpected validation errors
      throw new McpError(
        ErrorCode.InvalidParams,
        `Unexpected error during argument validation: ${error instanceof Error ? error.message : String(error)}`,
      );
    }
  
    // Proceed with validated paths
    const creationPromises = pathsToCreate.map((p) => processSingleDirectoryCreation(p, deps));
    const settledResults = await Promise.allSettled(creationPromises);
  
    const outputResults = processSettledResults(settledResults, pathsToCreate);
  
    // Sort results by original path order for predictability
    const originalIndexMap = new Map(pathsToCreate.map((p, i) => [p.replaceAll('\\', '/'), i]));
    outputResults.sort((a, b) => {
      const indexA = originalIndexMap.get(a.path) ?? Infinity;
      const indexB = originalIndexMap.get(b.path) ?? Infinity;
      return indexA - indexB;
    });
  
    return {
      content: [{ type: 'text', text: JSON.stringify(outputResults, undefined, 2) }],
    };
  };

• src/handlers/create-directories.ts:13-20 (schema)

  Zod input schema: strict object with non-empty array of relative directory paths.

  export const CreateDirsArgsSchema = z
    .object({
      paths: z
        .array(z.string())
        .min(1, { message: 'Paths array cannot be empty' })
        .describe('An array of relative directory paths to create.'),
    })
    .strict();

• src/handlers/index.ts:54-54 (registration)

  Tool definition is registered by inclusion in the allToolDefinitions array exported from handlers/index.ts, which aggregates all tools.

  createDirectoriesToolDefinition,

• src/handlers/create-directories.ts:226-240 (handler)

  Tool definition object exporting the tool name, description, inputSchema reference, and a wrapper handler that injects production dependencies (fs.mkdir, stat, resolvePath, PROJECT_ROOT) before calling the core internal handler.

  export const createDirectoriesToolDefinition = {
    name: 'create_directories',
    description: 'Create multiple specified directories (including intermediate ones).',
    inputSchema: CreateDirsArgsSchema,
    handler: (args: unknown): Promise<McpToolResponse> => {
      // Production handler provides real dependencies
      const productionDeps: CreateDirsDeps = {
        mkdir: fs.mkdir,
        stat: fs.stat,
        resolvePath: resolvePath,
        PROJECT_ROOT: PROJECT_ROOT,
      };
      return handleCreateDirectoriesInternal(args, productionDeps);
    },
  };

• src/handlers/create-directories.ts:134-161 (helper)

  Key helper: processes single directory creation - resolves path, prevents root creation, mkdir recursive, handles EEXIST specially, other errors.

  async function processSingleDirectoryCreation(
    relativePath: string, // Corrected signature: relativePath first
    deps: CreateDirsDeps, // Corrected signature: deps second
  ): Promise<CreateDirResult> {
    const pathOutput = relativePath.replaceAll('\\', '/'); // Normalize for output consistency
    let targetPath = '';
    try {
      targetPath = await deps.resolvePath(relativePath); // Use deps.resolvePath
      if (targetPath === deps.PROJECT_ROOT) {
        // Use deps.PROJECT_ROOT
        return {
          path: pathOutput,
          success: false,
          error: 'Creating the project root is not allowed.',
          resolvedPath: targetPath,
        };
      }
      await deps.mkdir(targetPath, { recursive: true }); // Use deps.mkdir
      return { path: pathOutput, success: true, resolvedPath: targetPath };
    } catch (error: unknown) {
      if (error && typeof error === 'object' && 'code' in error && error.code === 'EEXIST') {
        // Pass deps to handleEexistError
        return await handleEexistError(targetPath, pathOutput, deps);
      }
      // Pass potential McpError from resolvePath or other errors
      return handleDirectoryCreationError(error, pathOutput, targetPath);
    }
  }