applescript-mcp

Instructions

Implementation Reference

• src/categories/notes.ts:312-392 (handler)

  Handler function for notes_search (notes.search) that generates AppleScript to search notes by query in title or body, optionally in a folder, with limit and includeBody options.

  const { query, folder = "", limit = 5, includeBody = true } = args;
  
  if (folder) {
    return `
      tell application "Notes"
        set folderList to folders whose name is "${folder}"
        if length of folderList > 0 then
          set targetFolder to item 1 of folderList
          set matchingNotes to {}
          set allNotes to notes of targetFolder
          repeat with n in allNotes
            if name of n contains "${query}" or body of n contains "${query}" then
              set end of matchingNotes to n
            end if
          end repeat
          
          set resultCount to length of matchingNotes
          if resultCount > ${limit} then set resultCount to ${limit}
          
          set jsonResult to "["
          repeat with i from 1 to resultCount
            set n to item i of matchingNotes
            set noteTitle to name of n
            set noteCreationDate to creation date of n
            set noteModDate to modification date of n
            ${includeBody ? 'set noteBody to body of n' : ''}
            
            set noteJson to "{\\"title\\": \\""
            set noteJson to noteJson & noteTitle & "\\""
            ${includeBody ? 'set noteJson to noteJson & ", \\"body\\": \\"" & noteBody & "\\""' : ''}
            set noteJson to noteJson & ", \\"creationDate\\": \\"" & noteCreationDate & "\\""
            set noteJson to noteJson & ", \\"modificationDate\\": \\"" & noteModDate & "\\"}"
            
            set jsonResult to jsonResult & noteJson
            if i < resultCount then set jsonResult to jsonResult & ", "
          end repeat
          set jsonResult to jsonResult & "]"
          
          return jsonResult
        else
          return "Folder not found: ${folder}"
        end if
      end tell
    `;
  } else {
    return `
      tell application "Notes"
        set matchingNotes to {}
        set allNotes to notes
        repeat with n in allNotes
          if name of n contains "${query}" or body of n contains "${query}" then
            set end of matchingNotes to n
          end if
        end repeat
        
        set resultCount to length of matchingNotes
        if resultCount > ${limit} then set resultCount to ${limit}
        
        set jsonResult to "["
        repeat with i from 1 to resultCount
          set n to item i of matchingNotes
          set noteTitle to name of n
          set noteCreationDate to creation date of n
          set noteModDate to modification date of n
          ${includeBody ? 'set noteBody to body of n' : ''}
          
          set noteJson to "{\\"title\\": \\""
          set noteJson to noteJson & noteTitle & "\\""
          ${includeBody ? 'set noteJson to noteJson & ", \\"body\\": \\"" & noteBody & "\\""' : ''}
          set noteJson to noteJson & ", \\"creationDate\\": \\"" & noteCreationDate & "\\""
          set noteJson to noteJson & ", \\"modificationDate\\": \\"" & noteModDate & "\\"}"
          
          set jsonResult to jsonResult & noteJson
          if i < resultCount then set jsonResult to jsonResult & ", "
        end repeat
        set jsonResult to jsonResult & "]"
        
        return jsonResult
      end tell
    `;
  }

• src/categories/notes.ts:394-415 (schema)

  Input schema defining parameters for the notes_search tool.

  schema: {
    type: "object",
    properties: {
      query: {
        type: "string",
        description: "Text to search for in notes (title and body)"
      },
      folder: {
        type: "string",
        description: "Optional folder name to search in"
      },
      limit: {
        type: "number",
        description: "Maximum number of results to return (default: 5)"
      },
      includeBody: {
        type: "boolean",
        description: "Whether to include note body in results (default: true)"
      }
    },
    required: ["query"]
  }

• src/framework.ts:222-232 (registration)

  Tool registration in listTools handler where 'notes_search' name is constructed as `${'notes'}_${'search'}`.

    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:244-247 (registration)

  Dispatch logic in callTool handler that parses 'notes_search' by splitting on '_' to get category 'notes' and script 'search'.

  const [categoryName, ...scriptNameParts] =
    toolName.split("_");
  const scriptName = scriptNameParts.join("_"); // Rejoin in case script name has underscores

• src/index.ts:35-35 (registration)

  Registration of the notes category containing the search script, which becomes notes_search tool.

  server.addCategory(notesCategory);