finder_get_selection

Retrieve currently selected files and folders in macOS Finder to enable AI agents to access and manage user-selected items for automation tasks.

Instructions

Get currently selected files/folders in Finder

Input Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Implementation Reference

src/index.ts:640-712 (handler)

Main handler for 'finder_get_selection' tool. Executes AppleScript via osascript to get Finder's current selection as alias list, processes stderr for errors, handles empty selection, parses aliases into friendly file/directory names (handling directories and .localized), and returns formatted list of selected items.

case 'finder_get_selection':
  try {
    const command = `osascript -e 'tell application "Finder" to get selection as alias list'`;
    const { stdout, stderr } = await execAsync(command);
    
    if (stderr.trim()) {
      return {
        content: [
          {
            type: 'text',
            text: `Error getting Finder selection: ${stderr.trim()}`,
          },
        ],
      };
    }
    
    const output = stdout.trim();
    if (!output || output === '') {
      return {
        content: [
          {
            type: 'text',
            text: 'No files selected in Finder',
          },
        ],
      };
    }
    
    // Process AppleScript aliases to user-friendly names
    const aliases = output.split(', ');
    const friendlyNames = aliases.map(alias => {
      // Extract filename from alias path
      const pathParts = alias.replace('alias ', '').split(':');
      
      // Check if it's a directory (ends with colon, creates empty last element)
      const isDirectory = alias.endsWith(':');
      
      let filename;
      if (isDirectory) {
        // For directories: take second-to-last element (last is empty from trailing colon)
        filename = pathParts[pathParts.length - 2];
      } else {
        // For files: take last element
        filename = pathParts[pathParts.length - 1];
      }
      
      // Remove .localized suffix if present
      if (filename && filename.endsWith('.localized')) {
        filename = filename.replace('.localized', '');
      }
      
      return isDirectory ? `${filename}/` : filename;
    });
    
    return {
      content: [
        {
          type: 'text',
          text: `Selected items (${friendlyNames.length}):\n${friendlyNames.join('\n')}`,
        },
      ],
    };
  } catch (error: any) {
    return {
      content: [
        {
          type: 'text',
          text: `Error executing Finder selection command: ${error.message}`,
        },
      ],
    };
  }

src/index.ts:52-59 (registration)

Tool registration in ListToolsRequestSchema handler, defines name, description, and empty inputSchema (no parameters required).

{
  name: 'finder_get_selection',
  description: 'Get currently selected files/folders in Finder',
  inputSchema: {
    type: 'object',
    properties: {},
  },
},

src/index.ts:55-58 (schema)
Input schema for finder_get_selection: empty object (no input parameters).
```
inputSchema: {
  type: 'object',
  properties: {},
},
```
tests/verify_tools.ts:69-70 (helper)
Test invocation of finder_get_selection tool, notes it requires manual Finder selection.
```
// finder_get_selection requires manual selection, skipping or expecting empty
await testTool('finder_get_selection');
```

mcp-mac