Reader MCP Server

Instructions

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

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()