readwise_list_highlights
Retrieve and filter highlights from Readwise by book, date, or other criteria for efficient organization and review of saved content.
Instructions
List highlights from Readwise with optional filtering by book, date, or other criteria
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| book_id | No | Filter highlights by specific book ID | |
| highlighted_at__gt | No | Filter highlights made after this date (ISO 8601) | |
| highlighted_at__lt | No | Filter highlights made before this date (ISO 8601) | |
| page | No | Page number for pagination | |
| page_size | No | Number of results per page (default: 100, max: 1000) | |
| updated__gt | No | Filter highlights updated after this date (ISO 8601) | |
| updated__lt | No | Filter highlights updated before this date (ISO 8601) |
Implementation Reference
- src/handlers/highlights-handlers.ts:3-37 (handler)The main handler function that implements the 'readwise_list_highlights' tool. It initializes the Readwise client, constructs query parameters from input args, fetches highlights, strips to essential fields (id, text, note, book_id), and returns formatted JSON response.export async function handleListHighlights(args: any) { const client = await initializeClient(); const params = { page_size: args.page_size, page: args.page, book_id: args.book_id, updated__lt: args.updated__lt, updated__gt: args.updated__gt, highlighted_at__lt: args.highlighted_at__lt, highlighted_at__gt: args.highlighted_at__gt, }; const response = await client.listHighlights(params); // Strip to essentials const minimal = { count: response.data.count, results: response.data.results.map(h => ({ id: h.id, text: h.text, note: h.note || undefined, book_id: h.book_id })) }; return { content: [ { type: 'text', text: JSON.stringify(minimal, null, 2), }, ], }; }
- src/handlers/index.ts:39-40 (registration)The switch case in the central tool dispatcher (handleToolCall) that routes 'readwise_list_highlights' calls to the specific handler function.case 'readwise_list_highlights': return handleListHighlights(args);
- The tool definition including name, description, and input schema validation for parameters like page_size, page, book_id, date filters.{ name: 'readwise_list_highlights', description: 'List highlights from Readwise with optional filtering by book, date, or other criteria', inputSchema: { type: 'object', properties: { page_size: { type: 'number', description: 'Number of results per page (default: 100, max: 1000)', }, page: { type: 'number', description: 'Page number for pagination', }, book_id: { type: 'number', description: 'Filter highlights by specific book ID', }, updated__lt: { type: 'string', description: 'Filter highlights updated before this date (ISO 8601)', }, updated__gt: { type: 'string', description: 'Filter highlights updated after this date (ISO 8601)', }, highlighted_at__lt: { type: 'string', description: 'Filter highlights made before this date (ISO 8601)', }, highlighted_at__gt: { type: 'string', description: 'Filter highlights made after this date (ISO 8601)', }, }, additionalProperties: false, }, },
- src/index.ts:24-26 (registration)Registers the list of all tools (including readwise_list_highlights from tool-definitions) for the MCP ListTools request.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools }; });
- src/index.ts:28-33 (registration)Registers the CallTool request handler which invokes handleToolCall for executing tools like readwise_list_highlights.server.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: args } = request.params; try { return await handleToolCall(name, args); } catch (error) {