From 617bb9cab59a8ad7e33881af914067bc57e1845c Mon Sep 17 00:00:00 2001
From: Hermes Agent <hermes-agent@bueso.me>
Date: Sun, 12 Jul 2026 11:09:19 +0000
Subject: [PATCH] pinchflat-mcp: add pagination, downloaded filter, and
 delete_media tool

- list_media: add offset and downloaded params for API pagination
- delete_media: new tool to delete downloaded files (with prevent_download option)
- Bump timeout on delete to 120s
---
 packages/pinchflat-mcp/server.py | 37 +++++++++++++++++++++++++++++---
 1 file changed, 34 insertions(+), 3 deletions(-)

diff --git a/packages/pinchflat-mcp/server.py b/packages/pinchflat-mcp/server.py
index 439a55b..4d5f669 100644
--- a/packages/pinchflat-mcp/server.py
+++ b/packages/pinchflat-mcp/server.py
@@ -150,11 +150,25 @@ def force_metadata_refresh(source_id: int) -> dict:
 # --- Media Items ---
 
 @mcp.tool()
-def list_media(source_id: Optional[int] = None, limit: int = 50) -> dict:
-    """List media items. Optionally filter by source_id."""
-    params = {}
+def list_media(
+    source_id: Optional[int] = None,
+    limit: int = 50,
+    offset: int = 0,
+    downloaded: Optional[bool] = None,
+) -> dict:
+    """List media items with pagination. Optionally filter by source_id or download status.
+
+    Args:
+        source_id: Filter to a specific source
+        limit: Max items to return (default 50)
+        offset: Skip first N items for pagination (default 0)
+        downloaded: If True, only return downloaded media; if False, only undownloaded
+    """
+    params = {"limit": limit, "offset": offset}
     if source_id:
         params["source_id"] = source_id
+    if downloaded is not None:
+        params["downloaded"] = "true" if downloaded else "false"
     return _get("/media", params=params)
 
 
@@ -176,6 +190,23 @@ def force_download_media(media_id: int) -> dict:
     return _post(f"/media/{media_id}/force_download")
 
 
+@mcp.tool()
+def delete_media(media_id: int, prevent_download: bool = False) -> dict:
+    """Delete a media item's downloaded files from disk.
+
+    Args:
+        media_id: The media item ID to delete
+        prevent_download: If True, prevent the item from being re-downloaded in the future
+    """
+    params = {}
+    if prevent_download:
+        params["prevent_download"] = "true"
+    with httpx.Client(timeout=120) as client:
+        r = client.delete(f"{BASE}/media/{media_id}", headers=HEADERS, params=params)
+        r.raise_for_status()
+        return r.json()
+
+
 # --- Media Profiles ---
 
 @mcp.tool()