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