list_messages
Retrieve chat history by listing messages from a specified WhatsApp chat. Supports pagination with adjustable limits and page numbers for efficient message retrieval.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| chat_jid | Yes | The JID of the chat (e.g., '123456@s.whatsapp.net' or 'group@g.us') | |
| limit | No | Max messages per page (default 20) | |
| page | No | Page number (0-indexed, default 0) |
Implementation Reference
- src/mcp.ts:136-181 (handler)Handler function that executes the list_messages MCP tool: logs execution, fetches messages via getMessages, handles empty results, formats with formatDbMessageForJson, returns JSON text content or error.async ({ chat_jid, limit, page }) => { mcpLogger.info( `[MCP Tool] Executing list_messages for chat ${chat_jid}, limit=${limit}, page=${page}`, ); try { const messages = getMessages(chat_jid, limit, page); if (!messages.length && page === 0) { return { content: [ { type: "text", text: `No messages found for chat ${chat_jid}.` }, ], }; } else if (!messages.length) { return { content: [ { type: "text", text: `No more messages found on page ${page} for chat ${chat_jid}.`, }, ], }; } const formattedMessages = messages.map(formatDbMessageForJson); return { content: [ { type: "text", text: JSON.stringify(formattedMessages, null, 2), }, ], }; } catch (error: any) { mcpLogger.error( `[MCP Tool Error] list_messages failed for ${chat_jid}: ${error.message}`, ); return { isError: true, content: [ { type: "text", text: `Error listing messages for ${chat_jid}: ${error.message}`, }, ], }; } },
- src/mcp.ts:116-135 (schema)Zod schema defining input parameters for list_messages tool: required chat_jid, optional limit (default 20), optional page (default 0).chat_jid: z .string() .describe( "The JID of the chat (e.g., '123456@s.whatsapp.net' or 'group@g.us')", ), limit: z .number() .int() .positive() .optional() .default(20) .describe("Max messages per page (default 20)"), page: z .number() .int() .nonnegative() .optional() .default(0) .describe("Page number (0-indexed, default 0)"), },
- src/mcp.ts:113-182 (registration)Registration of the list_messages tool on the MCP server using server.tool(name, inputSchema, handlerFn).server.tool( "list_messages", { chat_jid: z .string() .describe( "The JID of the chat (e.g., '123456@s.whatsapp.net' or 'group@g.us')", ), limit: z .number() .int() .positive() .optional() .default(20) .describe("Max messages per page (default 20)"), page: z .number() .int() .nonnegative() .optional() .default(0) .describe("Page number (0-indexed, default 0)"), }, async ({ chat_jid, limit, page }) => { mcpLogger.info( `[MCP Tool] Executing list_messages for chat ${chat_jid}, limit=${limit}, page=${page}`, ); try { const messages = getMessages(chat_jid, limit, page); if (!messages.length && page === 0) { return { content: [ { type: "text", text: `No messages found for chat ${chat_jid}.` }, ], }; } else if (!messages.length) { return { content: [ { type: "text", text: `No more messages found on page ${page} for chat ${chat_jid}.`, }, ], }; } const formattedMessages = messages.map(formatDbMessageForJson); return { content: [ { type: "text", text: JSON.stringify(formattedMessages, null, 2), }, ], }; } catch (error: any) { mcpLogger.error( `[MCP Tool Error] list_messages failed for ${chat_jid}: ${error.message}`, ); return { isError: true, content: [ { type: "text", text: `Error listing messages for ${chat_jid}: ${error.message}`, }, ], }; } }, );
- src/mcp.ts:20-35 (helper)Helper function to format a database Message object into the JSON structure returned by list_messages.function formatDbMessageForJson(msg: DbMessage) { return { id: msg.id, chat_jid: msg.chat_jid, chat_name: msg.chat_name ?? "Unknown Chat", sender_jid: msg.sender ?? null, sender_display: msg.sender ? msg.sender.split("@")[0] : msg.is_from_me ? "Me" : "Unknown", content: msg.content, timestamp: msg.timestamp.toISOString(), is_from_me: msg.is_from_me, }; }
- src/database.ts:173-196 (helper)Core database helper function getMessages that performs SQL query to fetch paginated messages for a specific chat_jid, ordered by timestamp DESC, used directly by the list_messages handler.export function getMessages( chatJid: string, limit: number = 20, page: number = 0, ): Message[] { const db = getDb(); try { const offset = page * limit; const stmt = db.prepare(` SELECT m.*, c.name as chat_name FROM messages m JOIN chats c ON m.chat_jid = c.jid WHERE m.chat_jid = ? -- Positional parameter 1 ORDER BY m.timestamp DESC LIMIT ? -- Positional parameter 2 OFFSET ? -- Positional parameter 3 `); const rows = stmt.all(chatJid, limit, offset) as any[]; return rows.map(rowToMessage); } catch (error) { console.error("Error getting messages:", error); return []; } }