messages_list_chats

Retrieve a list of available iMessage and SMS chats from macOS, optionally including participant details for each conversation.

Instructions

[iMessage operations] List available iMessage and SMS chats

Input Schema

TableJSON Schema

Name	Required	Description	Default
`includeParticipantDetails`	No	Include detailed participant information

Implementation Reference

src/categories/messages.ts:10-60 (handler)

Handler implementation for the 'messages_list_chats' tool. Defines the AppleScript logic to list iMessage/SMS chats, including optional participant details.

{
  name: "list_chats",
  description: "List available iMessage and SMS chats",
  schema: {
    type: "object",
    properties: {
      includeParticipantDetails: {
        type: "boolean",
        description: "Include detailed participant information",
        default: false
      }
    }
  },
  script: (args) => `
    tell application "Messages"
      set chatList to {}
      repeat with aChat in chats
        set chatName to name of aChat
        if chatName is missing value then
          set chatName to ""
          -- Try to get the contact name for individual chats
          try
            set theParticipants to participants of aChat
            if (count of theParticipants) is 1 then
              set theParticipant to item 1 of theParticipants
              set chatName to name of theParticipant
            end if
          end try
        end if
        
        set chatInfo to {id:id of aChat, name:chatName, isGroupChat:(id of aChat contains "+")}
        
        ${args.includeParticipantDetails ? `
        -- Add participant details if requested
        set participantList to {}
        repeat with aParticipant in participants of aChat
          set participantInfo to {id:id of aParticipant, handle:handle of aParticipant}
          try
            set participantInfo to participantInfo & {name:name of aParticipant}
          end try
          copy participantInfo to end of participantList
        end repeat
        set chatInfo to chatInfo & {participant:participantList}
        ` : ''}
        
        copy chatInfo to end of chatList
      end repeat
      return chatList
    end tell
  `
},

src/categories/messages.ts:13-22 (schema)

Input schema for 'messages_list_chats' tool, defining optional 'includeParticipantDetails' parameter.

schema: {
  type: "object",
  properties: {
    includeParticipantDetails: {
      type: "boolean",
      description: "Include detailed participant information",
      default: false
    }
  }
},

src/index.ts:34-35 (registration)
Registers the 'messages' category (containing list_chats script) with the MCP server framework.
```
server.addCategory(messagesCategory);
server.addCategory(notesCategory);
```

src/framework.ts:222-231 (registration)

Dynamically registers all category scripts as MCP tools in ListToolsRequestHandler, constructing names like 'messages_list_chats'.

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: {},
    },
  })),
),

applescript-mcp