Pinboard MCP Server

Instructions

Args:
    days: Number of days to look back (1-30, default 7)
    limit: Maximum number of results to return (1-100, default 20)

Implementation Reference

• src/pinboard_mcp_server/main.py:73-92 (handler)

  MCP tool handler for list_recent_bookmarks: validates inputs, calls PinboardClient.get_recent_bookmarks, formats response with bookmarks list, total count, and days parameter.

  @mcp.tool
  async def list_recent_bookmarks(days: int = 7, limit: int = 20) -> dict[str, Any]:
      """List bookmarks saved in the last N days.
  
      Args:
          days: Number of days to look back (1-30, default 7)
          limit: Maximum number of results to return (1-100, default 20)
      """
      if not 1 <= days <= 30:
          raise ValueError("Days must be between 1 and 30")
      if not 1 <= limit <= 100:
          raise ValueError("Limit must be between 1 and 100")
  
      bookmarks = await client.get_recent_bookmarks(days=days, limit=limit)
  
      return {
          "bookmarks": [bookmark.model_dump() for bookmark in bookmarks],
          "total": len(bookmarks),
          "days": days,
      }

• src/pinboard_mcp_server/client.py:346-367 (helper)

  Helper method in PinboardClient that retrieves recent bookmarks by filtering cached bookmarks by date cutoff, sorting by recency, limiting results, and using query cache.

  async def get_recent_bookmarks(
      self, days: int = 7, limit: int = 20
  ) -> list[Bookmark]:
      """Get bookmarks from the last N days."""
      cache_key = f"recent:{days}:{limit}"
      if cache_key in self._query_cache:
          return self._query_cache[cache_key]
  
      bookmarks = await self.get_all_bookmarks()
      cutoff_date = datetime.now() - timedelta(days=days)
  
      # Filter by date and sort by most recent first
      recent = [
          bookmark
          for bookmark in bookmarks
          if bookmark.saved_at.replace(tzinfo=None) >= cutoff_date
      ]
      recent.sort(key=lambda b: b.saved_at, reverse=True)
  
      result = recent[:limit]
      self._query_cache[cache_key] = result
      return result