finder_search_files

Search for files by name in macOS Finder to locate documents, media, or applications using AppleScript automation.

Instructions

[Finder and file operations] Search for files by name

Input Schema

TableJSON Schema

Name	Required	Description	Default
`query`	Yes	Search term
`location`	No	Search location (default: home folder)	~

Implementation Reference

src/categories/finder.ts:56-74 (handler)

Handler function for the 'search_files' script (registered as 'finder_search_files'). Generates AppleScript that searches for files whose name contains the query in the hardcoded '/Users/joshrutkowski/Downloads' folder and returns their POSIX paths.

script: (args) => `
  set searchPath to "/Users/joshrutkowski/Downloads"
  tell application "Finder"
    try
      set theFolder to POSIX file searchPath as alias
      set theFiles to every file of folder theFolder whose name contains "${args.query}"
      set resultList to ""
      repeat with aFile in theFiles
        set resultList to resultList & (POSIX path of (aFile as alias)) & return
      end repeat
      if resultList is "" then
        return "No files found matching '${args.query}'"
      end if
      return resultList
    on error errMsg
      return "Failed to search files: " & errMsg
    end try
  end tell
`,

src/categories/finder.ts:41-55 (schema)

JSON Schema defining the input parameters for the finder_search_files tool: required 'query' string and optional 'location' string (note: location is defined but not used in the handler).

schema: {
  type: "object",
  properties: {
    query: {
      type: "string",
      description: "Search term",
    },
    location: {
      type: "string",
      description: "Search location (default: home folder)",
      default: "~",
    },
  },
  required: ["query"],
},

src/framework.ts:221-232 (registration)

In the ListTools handler, tools are dynamically registered by flattening category scripts and naming them as '{category}_{script}', creating 'finder_search_files' from finder.search_files.

this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: this.categories.flatMap((category) =>
    category.scripts.map((script) => ({
      name: `${category.name}_${script.name}`, // Changed from dot to underscore
      description: `[${category.description}] ${script.description}`,
      inputSchema: script.schema || {
        type: "object",
        properties: {},
      },
    })),
  ),
}));

src/framework.ts:248-258 (handler)

Generic tool execution handler locates the 'finder' category and 'search_files' script from tool name 'finder_search_files'.

const category = this.categories.find((c) => c.name === categoryName);
if (!category) {
  this.log("warning", "Category not found", { categoryName });
  throw new McpError(
    ErrorCode.MethodNotFound,
    `Category not found: ${categoryName}`,
  );
}

const script = category.scripts.find((s) => s.name === scriptName);
if (!script) {

src/index.ts:27-27 (registration)
Registers the finder category (containing search_files) with the MCP server framework.
```
server.addCategory(finderCategory);
```

applescript-mcp