get_readwise_highlights_by_document_ids
Retrieve highlights from Readwise by specifying document IDs to access saved annotations and notes from specific documents.
Instructions
Get highlights from Readwise by document ids.
Args:
document_ids (List[int]): The IDs of the documents to retrieve highlights for.
Returns:
List[Highlight]: A list of Highlight objects containing the highlights from the specified document.
Raises:
ValueError: If no document IDs are provided.Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| document_ids | Yes |
Implementation Reference
- server.py:98-130 (handler)The primary handler function for the tool 'get_readwise_highlights_by_document_ids'. Decorated with @mcp.tool() for registration, it validates the document_ids input, concurrently calls the helper get_highlight_by_document_id for each ID, gathers results, flattens the list of highlights, and returns it.
@mcp.tool() async def get_readwise_highlights_by_document_ids( document_ids: List[int], ) -> List[Highlight]: """ Get highlights from Readwise by document ids. Args: document_ids (List[int]): The IDs of the documents to retrieve highlights for. Returns: List[Highlight]: A list of Highlight objects containing the highlights from the specified document. Raises: ValueError: If no document IDs are provided. """ if not document_ids: raise ValueError("No document IDs provided") # Create a list of tasks (co-routines), one for each document ID tasks = [get_highlight_by_document_id(READWISE_API_KEY, doc_id) for doc_id in document_ids] # Execute all tasks concurrently and gather the results results = await asyncio.gather(*tasks) highlights: List[Highlight] = [] # Flatten the list of lists into a single list of highlights for doc_highlights in results: highlights.extend(doc_highlights) return highlights - Pydantic BaseModel defining the Highlight type, which is used in the tool's return type List[Highlight]. This serves as the output schema.
class Highlight(BaseModel): """Represents a highlight from Readwise API.""" id: int text: str note: str location: int location_type: str highlighted_at: Optional[datetime] = None url: Optional[HttpUrl] = None color: str updated: datetime book_id: int tags: List[Tag] = [] - Core helper function that retrieves all highlights for a single document ID from the Readwise API, including pagination logic using get_data.
async def get_highlight_by_document_id(api_key: str, document_id: int) -> List[Highlight]: """Get highlights by document id.""" url = f"{READWISE_API_URL}/highlights/" params = {"book_id": document_id, "page_size": 100} highlights: List[Highlight] = [] first_request = True while True: # Pass params only on the first request. current_params = params if first_request else None hs = await get_data(api_key, url, current_params) first_request = False hs_results = hs["results"] highlights.extend([Highlight(**h) for h in hs_results]) total_highlights = hs["count"] logging.info(f"Total highlights: {total_highlights}") url = hs.get("next", None) if not url: break await asyncio.sleep(DEFAULT_SLEEP_BETWEEN_REQUESTS_IN_SECONDS) return highlights - server.py:98-98 (registration)The @mcp.tool() decorator registers the get_readwise_highlights_by_document_ids function as an MCP tool.
@mcp.tool()