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); } }