list_chats
Retrieve and organize WhatsApp chat lists by sorting, filtering, and pagination. Include last message details and customize display with parameters like limit, page, and query for efficient chat management.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| include_last_message | No | Include last message details (default true) | |
| limit | No | Max chats per page (default 20) | |
| page | No | Page number (0-indexed, default 0) | |
| query | No | Optional filter by chat name or JID | |
| sort_by | No | Sort order: 'last_active' (default) or 'name' | last_active |
Implementation Reference
- src/mcp.ts:216-267 (handler)The handler function that executes the list_chats tool logic: fetches chats from database with pagination, sorting, filtering; formats and returns as JSON; handles empty results and errors.async ({ limit, page, sort_by, query, include_last_message }) => { mcpLogger.info( `[MCP Tool] Executing list_chats: limit=${limit}, page=${page}, sort=${sort_by}, query=${query}, lastMsg=${include_last_message}`, ); try { const chats = getChats( limit, page, sort_by, query ?? null, include_last_message, ); if (!chats.length && page === 0) { return { content: [ { type: "text", text: `No chats found${query ? ` matching "${query}"` : ""}.`, }, ], }; } else if (!chats.length) { return { content: [ { type: "text", text: `No more chats found on page ${page}${ query ? ` matching "${query}"` : "" }.`, }, ], }; } const formattedChats = chats.map(formatDbChatForJson); return { content: [ { type: "text", text: JSON.stringify(formattedChats, null, 2), }, ], }; } catch (error: any) { mcpLogger.error(`[MCP Tool Error] list_chats failed: ${error.message}`); return { isError: true, content: [ { type: "text", text: `Error listing chats: ${error.message}` }, ], }; } },
- src/mcp.ts:186-215 (schema)Zod input schema defining parameters for the list_chats tool: limit, page, sort_by, query, include_last_message.{ limit: z .number() .int() .positive() .optional() .default(20) .describe("Max chats per page (default 20)"), page: z .number() .int() .nonnegative() .optional() .default(0) .describe("Page number (0-indexed, default 0)"), sort_by: z .enum(["last_active", "name"]) .optional() .default("last_active") .describe("Sort order: 'last_active' (default) or 'name'"), query: z .string() .optional() .describe("Optional filter by chat name or JID"), include_last_message: z .boolean() .optional() .default(true) .describe("Include last message details (default true)"), },
- src/mcp.ts:184-268 (registration)Registration of the list_chats tool using McpServer.tool() method, including schema and handler.server.tool( "list_chats", { limit: z .number() .int() .positive() .optional() .default(20) .describe("Max chats per page (default 20)"), page: z .number() .int() .nonnegative() .optional() .default(0) .describe("Page number (0-indexed, default 0)"), sort_by: z .enum(["last_active", "name"]) .optional() .default("last_active") .describe("Sort order: 'last_active' (default) or 'name'"), query: z .string() .optional() .describe("Optional filter by chat name or JID"), include_last_message: z .boolean() .optional() .default(true) .describe("Include last message details (default true)"), }, async ({ limit, page, sort_by, query, include_last_message }) => { mcpLogger.info( `[MCP Tool] Executing list_chats: limit=${limit}, page=${page}, sort=${sort_by}, query=${query}, lastMsg=${include_last_message}`, ); try { const chats = getChats( limit, page, sort_by, query ?? null, include_last_message, ); if (!chats.length && page === 0) { return { content: [ { type: "text", text: `No chats found${query ? ` matching "${query}"` : ""}.`, }, ], }; } else if (!chats.length) { return { content: [ { type: "text", text: `No more chats found on page ${page}${ query ? ` matching "${query}"` : "" }.`, }, ], }; } const formattedChats = chats.map(formatDbChatForJson); return { content: [ { type: "text", text: JSON.stringify(formattedChats, null, 2), }, ], }; } catch (error: any) { mcpLogger.error(`[MCP Tool Error] list_chats failed: ${error.message}`); return { isError: true, content: [ { type: "text", text: `Error listing chats: ${error.message}` }, ], }; } }, );
- src/mcp.ts:37-52 (helper)Helper function to format DbChat objects into JSON-friendly structure, used by list_chats handler to prepare output.function formatDbChatForJson(chat: DbChat) { return { jid: chat.jid, name: chat.name ?? chat.jid.split("@")[0] ?? "Unknown Chat", is_group: chat.jid.endsWith("@g.us"), last_message_time: chat.last_message_time?.toISOString() ?? null, last_message_preview: chat.last_message ?? null, last_sender_jid: chat.last_sender ?? null, last_sender_display: chat.last_sender ? chat.last_sender.split("@")[0] : chat.last_is_from_me ? "Me" : null, last_is_from_me: chat.last_is_from_me ?? null, }; }