Reader MCP Server

Instructions

Implementation Reference

• main.py:104-134 (handler)

  The primary handler function for the 'list_documents' tool. Decorated with @mcp.tool() for registration. Validates parameters using helper, calls Reader API /list/ endpoint, logs activity, handles errors, and returns ListDocumentResponse.
  @mcp.tool() async def list_documents( location: Optional[Literal['new', 'later', 'shortlist', 'archive', 'feed']] = Field( default=None, description="The folder where the document is located, supports 'new', 'later', 'shortlist', 'archive', 'feed'"), updatedAfter: Optional[str] = Field(default=None, description="Filter by update time (ISO8601)"), withContent: Optional[bool] = Field(default=False, description="Whether to include HTML content"), pageCursor: Optional[str] = Field(default=None, description="Pagination cursor"), ) -> ListDocumentResponse: """ Get the document list via the Reader API. Args: location: The folder where the document is located, supports 'new', 'later', 'shortlist', 'archive', 'feed' (optional) updatedAfter: Filter by update time (optional, ISO8601) withContent: Whether to include HTML content (optional, default false) pageCursor: Pagination cursor (optional) Returns: Document list JSON """ ctx = get_reader_context() logger.info(f"tool list_documents: location={location}, updatedAfter={updatedAfter}, withContent={withContent}, pageCursor={pageCursor}") try: params = validate_list_params(location, updatedAfter, withContent, pageCursor) response = await ctx.client.get("/list/", params=params) response.raise_for_status() data = response.json() return data except Exception as e: logger.error(f"Error in tool list_documents: {str(e)}") raise
• models.py:75-80 (schema)

  Output schema model ListDocumentResponse defining the structure of the tool's response: count, results (list of ReaderDocument), nextPageCursor.
  class ListDocumentResponse: """Response of the document list API""" count: int results: List[ReaderDocument] nextPageCursor: Optional[str] = None
• models.py:6-72 (schema)

  Supporting schema model ReaderDocument used within ListDocumentResponse.results, representing individual document details from Reader API.
  @dataclass class ReaderDocument: """ Document object in Reader. """ # Required document identifiers id: str url: str # Document details title: str source_url: Optional[str] = None author: Optional[str] = None source: Optional[str] = None category: Optional[str] = None location: Optional[str] = None tags: Dict[str, Any] = field(default_factory=dict) site_name: Optional[str] = None word_count: Optional[int] = None notes: Optional[str] = None published_date: Optional[str] = None summary: Optional[str] = None html_content: Optional[str] = None image_url: Optional[str] = None parent_id: Optional[str] = None # Reading state reading_progress: float = 0.0 first_opened_at: Optional[datetime] = None last_opened_at: Optional[datetime] = None # Timestamps created_at: Optional[datetime] = None updated_at: Optional[datetime] = None saved_at: Optional[datetime] = None last_moved_at: Optional[datetime] = None @classmethod def from_dict(cls, doc: Dict[str, Any]) -> "ReaderDocument": """Create a ReaderDocument from a dictionary representation""" return cls( id=doc.get('id', ''), url=doc.get('url', ''), title=doc.get('title', 'Untitled'), source_url=doc.get('source_url'), author=doc.get('author'), source=doc.get('source'), category=doc.get('category'), location=doc.get('location'), tags=doc.get('tags', {}), site_name=doc.get('site_name'), word_count=doc.get('word_count'), notes=doc.get('notes'), published_date=doc.get('published_date'), summary=doc.get('summary'), html_content=doc.get('html_content'), image_url=doc.get('image_url'), parent_id=doc.get('parent_id'), reading_progress=doc.get('reading_progress', 0.0), first_opened_at=doc.get('first_opened_at'), last_opened_at=doc.get('last_opened_at'), created_at=doc.get('created_at'), updated_at=doc.get('updated_at'), saved_at=doc.get('saved_at'), last_moved_at=doc.get('last_moved_at') )
• main.py:70-102 (helper)

  Helper function validate_list_params that processes and sanitizes input parameters (location, after/updatedAfter, with_content, page_cursor) ensuring valid values before API call.
  def validate_list_params(location: Optional[Literal['new', 'later', 'shortlist', 'archive', 'feed']] = None, after: Optional[str] = None, with_content: Optional[bool] = False, page_cursor: Optional[str] = None) -> Dict[str, Any]: """ Validate and filter document list parameters. Args: location: The location parameter to validate (only supports 'new', 'later', 'shortlist', 'archive', 'feed') after: The timestamp parameter to validate with_content: Whether to include html_content page_cursor: Pagination cursor Returns: Dict containing valid parameters """ params = {} if location in VALID_LOCATIONS: params['location'] = location else: logger.warning(f"Invalid `location`: '{location}', parameter will be ignored") try: if after and 'T' in after and (after.endswith('Z') or '+' in after): params['updatedAfter'] = after elif after: logger.warning(f"Invalid ISO 8601 datetime: {after}, parameter will be ignored") except (TypeError, ValueError): logger.warning(f"Invalid datetime format: {after}, parameter will be ignored") if with_content: params['withHtmlContent'] = with_content if page_cursor: params['pageCursor'] = page_cursor return params
• main.py:104-104 (registration)

  Tool registration via the @mcp.tool() decorator on the list_documents function.
  @mcp.tool()