faf_read

Instructions

Implementation Reference

• src/handlers/fileHandler.ts:95-158 (handler)

  The main handler function for faf_read: validates the path with PathValidator, checks file size, reads the file with a 30-second timeout, and returns the file content with metadata (duration, file size, resolved path).

  export async function handleFafRead(args: any): Promise<CallToolResult> {
    const startTime = Date.now();
    
    try {
      const { path: filePath } = args;
      
      // Validate path
      const pathValidation = PathValidator.validate(filePath);
      if (!pathValidation.valid) {
        return {
          content: [{
            type: 'text',
            text: `❌ Security error: ${pathValidation.error}`
          }],
          isError: true
        };
      }
      
      // Check file size
      const sizeValidation = await PathValidator.checkFileSize(filePath);
      if (!sizeValidation.valid) {
        return {
          content: [{
            type: 'text',
            text: `❌ ${sizeValidation.error}`
          }],
          isError: true
        };
      }
      
      // Read file with timeout
      const content = await Promise.race([
        fs.readFile(filePath, 'utf8'),
        new Promise<never>((_, reject) => 
          setTimeout(() => reject(new Error('Read timeout (30s)')), 30000)
        )
      ]);
      
      const duration = Date.now() - startTime;
      const stats = await fs.stat(filePath);
      
      return {
        content: [{
          type: 'text',
          text: content
        }],
        metadata: {
          duration_ms: duration,
          file_size: stats.size,
          file_path: path.resolve(filePath),
          message: `✅ Read ${stats.size} bytes in ${duration}ms`
        }
      };
      
    } catch (error: any) {
      return {
        content: [{
          type: 'text',
          text: `❌ Failed to read file: ${error.message}`
        }],
        isError: true
      };
    }
  }

• src/handlers/fileHandler.ts:55-68 (schema)

  Tool schema definition for faf_read: defines the tool name, description, and input schema requiring a single 'path' string parameter.

  export const fafReadTool: Tool = {
    name: 'faf_read',
    description: 'Read content from any file on the local filesystem',
    inputSchema: {
      type: 'object',
      properties: {
        path: {
          type: 'string',
          description: 'Absolute or relative file path to read'
        }
      },
      required: ['path']
    }
  };

• src/handlers/tool-types.ts:157-159 (schema)

  TypeScript interface FafReadArgs defining the typed arguments for faf_read with a required 'path' field.

  export interface FafReadArgs {
    path: string;
  }

• src/handlers/tools.ts:282-283 (registration)

  Routing in FafToolHandler that dispatches 'faf_read' to the fileHandlers.faf_read (handleFafRead) function.

  case 'faf_read':
    return await fileHandlers.faf_read(args);

• src/types/tool-visibility.ts:385-390 (registration)

  Visibility metadata for faf_read: classified as an 'advanced' tool in the 'file' category.

  faf_read: {
    name: 'faf_read',
    visibility: 'advanced',
    category: 'file',
    description: 'Read .faf file contents',
  },