MCP File Editor Server

Instructions

Implementation Reference

• src/index.ts:490-515 (handler)

  The execute handler for list_files tool. Validates the directory path, reads the directory contents using fs.readdirSync, determines file/dir type and size, formats output as list.

  execute: async ({ directory_path }) => {
    const absolutePath = validateAbsolutePath(directory_path, 'directory_path');
    validateDirectoryExists(absolutePath);
  
    try {
      const items = fs.readdirSync(absolutePath);
      const results: string[] = [];
  
      items.forEach(item => {
        const itemPath = path.join(absolutePath, item);
        const stats = fs.statSync(itemPath);
        const type = stats.isDirectory() ? '[DIR]' : '[FILE]';
        const size = stats.isFile() ? `(${stats.size} bytes)` : '';
        results.push(`${type} ${item} ${size}`.trim());
      });
  
      if (results.length === 0) {
        return `Directory "${absolutePath}" is empty.`;
      }
  
      return results.join('\n');
    } catch (error: any) {
      if (error instanceof UserError) throw error;
      throw new UserError(`Error listing directory "${absolutePath}": ${error.message}`);
    }
  }

• src/index.ts:487-489 (schema)

  Input schema using Zod: requires absolute directory_path as string.

  parameters: z.object({
    directory_path: z.string().describe('Absolute path to the directory to list')
  }),

• src/index.ts:484-516 (registration)

  Registration of the list_files tool via server.addTool, including name, description, schema, and handler.

  server.addTool({
    name: 'list_files',
    description: 'List all files and subdirectories in a given directory.',
    parameters: z.object({
      directory_path: z.string().describe('Absolute path to the directory to list')
    }),
    execute: async ({ directory_path }) => {
      const absolutePath = validateAbsolutePath(directory_path, 'directory_path');
      validateDirectoryExists(absolutePath);
  
      try {
        const items = fs.readdirSync(absolutePath);
        const results: string[] = [];
  
        items.forEach(item => {
          const itemPath = path.join(absolutePath, item);
          const stats = fs.statSync(itemPath);
          const type = stats.isDirectory() ? '[DIR]' : '[FILE]';
          const size = stats.isFile() ? `(${stats.size} bytes)` : '';
          results.push(`${type} ${item} ${size}`.trim());
        });
  
        if (results.length === 0) {
          return `Directory "${absolutePath}" is empty.`;
        }
  
        return results.join('\n');
      } catch (error: any) {
        if (error instanceof UserError) throw error;
        throw new UserError(`Error listing directory "${absolutePath}": ${error.message}`);
      }
    }
  });

• src/utils.ts:12-20 (helper)

  Helper function validateAbsolutePath used in list_files to ensure directory_path is absolute.

  export function validateAbsolutePath(filePath: string, parameterName: string = 'path'): string {
    if (!path.isAbsolute(filePath)) {
      throw new UserError(
        `The ${parameterName} must be an absolute path. You provided a relative path: "${filePath}". ` +
        `Please provide the full absolute path (e.g., "/home/user/file.txt" on Linux/Mac or "C:\\Users\\user\\file.txt" on Windows).`
      );
    }
    return filePath;
  }

• src/utils.ts:57-80 (helper)

  Helper function validateDirectoryExists used in list_files to check if the directory exists and is accessible.

  export function validateDirectoryExists(dirPath: string): void {
    try {
      const stats = fs.statSync(dirPath);
      if (!stats.isDirectory()) {
        throw new UserError(
          `The path "${dirPath}" exists but is not a directory. Please ensure you're providing the path to a directory.`
        );
      }
    } catch (error: any) {
      if (error.code === 'ENOENT') {
        throw new UserError(
          `Directory not found: "${dirPath}". Please verify that the directory exists and the path is correct.`
        );
      } else if (error.code === 'EACCES') {
        throw new UserError(
          `Permission denied: Cannot access directory "${dirPath}". Please check directory permissions.`
        );
      } else {
        throw new UserError(
          `Error accessing directory "${dirPath}": ${error.message}`
        );
      }
    }
  }