iMessage MCP Server

Instructions

Implementation Reference

• src/index.ts:199-262 (handler)

  Handler for the search_contacts tool: extracts query, runs AppleScript to search Contacts app for matching names, formats results as JSON, and returns them.

  case "search_contacts": {
    const query = String(request.params.arguments?.query).toLowerCase();
  
    const script = `
      tell application "Contacts"
        set output to "["
        set isFirst to true
        repeat with p in every person
          if ((name of p as text) contains "${query}") then
            if not isFirst then
              set output to output & ","
            end if
            set output to output & "{"
            set output to output & "\\"name\\":\\"" & (name of p as text) & "\\","
            set output to output & "\\"phones\\":["
            set firstPhone to true
            repeat with ph in phones of p
              if not firstPhone then
                set output to output & ","
              end if
              set output to output & "\\"" & (value of ph) & "\\""
              set firstPhone to false
            end repeat
            set output to output & "],"
            set output to output & "\\"emails\\":["
            set firstEmail to true
            repeat with em in emails of p
              if not firstEmail then
                set output to output & ","
              end if
              set output to output & "\\"" & (value of em) & "\\""
              set firstEmail to false
            end repeat
            set output to output & "]"
            set output to output & "}"
            set isFirst to false
          end if
        end repeat
        return output & "]"
      end tell
    `;
  
    try {
      const results = await runAppleScript(script);
      return {
        content: [
          {
            type: "text",
            text: results,
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Search failed: ${getErrorMessage(error)}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:144-153 (schema)

  Input schema defining the 'query' parameter as a required string for searching contacts.

  inputSchema: {
    type: "object",
    properties: {
      query: {
        type: "string",
        description: "Search query",
      },
    },
    required: ["query"],
  },

• src/index.ts:141-154 (registration)

  Registration of the search_contacts tool in the ListTools response, providing name, description, and input schema.

  {
    name: "search_contacts",
    description: "Search contacts by name, phone, or email",
    inputSchema: {
      type: "object",
      properties: {
        query: {
          type: "string",
          description: "Search query",
        },
      },
      required: ["query"],
    },
  },