pinchflat-mcp: redact credentials, gate admin tools, expose retention

Reviewed-on: #15

packages/default.nix

@@ -32,5 +32,6 @@
   yarr = pkgs.callPackage ./yarr/package.nix { };
   pdf-mcp = pkgs.callPackage ./pdf-mcp/package.nix { };
   mcp-searxng = pkgs.callPackage ./mcp-searxng/package.nix { };
+  python-ssh-mcp = pkgs.callPackage ./python-ssh-mcp/package.nix { };
   # example-mcp-server = pkgs.callPackage ./example-mcp-server/package.nix { };
 }

packages/jellyfin-mcp/package.nix

@@ -6,16 +6,16 @@
 
 buildGoModule rec {
   pname = "jellyfin-mcp";
-  version = "2026.604.2";
+  version = "2026.1015.1";
 
   src = fetchFromGitHub {
     owner = "jaredtrent";
     repo = "jellyfin-mcp";
     tag = "v${version}";
-    hash = "sha256-Ks54txfOAkNEWfhl5ZXEIaFzAbmCnwhHtN1+FIa7dgo=";
+    hash = "sha256-5wSYB/peTbvNYDlDBd2M0nA7JreP93nQe1G9rW3hv2I=";
   };
 
-  vendorHash = "sha256-cDy+PpZM6xL7ur/xq81y4vlyaDnSOpGkyVV2hh8qI7o=";
+  vendorHash = "sha256-L39HdshrVfVXD+rV3prsKQRosvidynwIlA9J6dtfqmU=";
 
   meta = with lib; {
     description = "MCP server for Jellyfin media server — search, playback, metadata, admin";

packages/pinchflat-mcp/server.py

@@ -1,5 +1,28 @@
 #!/usr/bin/env python3
-"""Pinchflat MCP server — exposes the Pinchflat REST API as MCP tools."""
+"""Pinchflat MCP server — exposes the Pinchflat REST API as MCP tools.
+
+Tool tiers
+----------
+Two tiers of tools exist and only one is exposed by default:
+
+* ``subscriptions`` (default) — sources, media items, media profiles, tasks.
+  This is what an assistant needs to manage subscriptions and their files.
+* ``admin`` — global application state: ``get_settings``, ``get_app_info``.
+  These describe the installation rather than a subscription and are NOT
+  exposed unless explicitly enabled.
+
+Select the tier with ``PINCHFLAT_MCP_TOOLSET``:
+
+    PINCHFLAT_MCP_TOOLSET=subscriptions   # default
+    PINCHFLAT_MCP_TOOLSET=admin
+    PINCHFLAT_MCP_TOOLSET=all
+
+Responses are scrubbed of secrets on the way out (see ``_scrub``), because the
+Pinchflat settings record embeds the application's own ``api_token``. Exposing
+it to a tool caller hands out a credential that outlives the tool session, so
+secret-bearing keys are redacted at the transport boundary rather than left to
+individual tools to remember.
+"""
 
 import os
 import sys
@@ -20,13 +43,76 @@ HEADERS = {"Authorization": f"Bearer {PINCHFLAT_TOKEN}", "Content-Type": "applic
 
 mcp = FastMCP("pinchflat")
 
+# --- Tool tiers -------------------------------------------------------------
+
+_TIERS = {
+    "subscriptions": {"subscriptions"},
+    "admin": {"subscriptions", "admin"},
+    "all": {"subscriptions", "admin"},
+}
+_TOOLSET = os.environ.get("PINCHFLAT_MCP_TOOLSET", "subscriptions").strip().lower()
+ENABLED_TIERS = _TIERS.get(_TOOLSET, _TIERS["subscriptions"])
+
+
+def tool(tier: str = "subscriptions"):
+    """Register a tool only when its tier is enabled."""
+
+    def decorator(fn):
+        if tier in ENABLED_TIERS:
+            return mcp.tool()(fn)
+        return fn
+
+    return decorator
+
+
+# --- Response scrubbing -----------------------------------------------------
+
+# Keys whose values are credentials and must never cross the tool boundary.
+SECRET_KEYS = frozenset(
+    {
+        "api_token",
+        "api_key",
+        "token",
+        "secret",
+        "password",
+        "password_hash",
+        "youtube_api_key",
+        "apprise_server",
+    }
+)
+REDACTED = "[redacted]"
+
+
+def _scrub(obj: Any) -> Any:
+    """Recursively redact credential-bearing values from an API response."""
+    if isinstance(obj, dict):
+        out = {}
+        for k, v in obj.items():
+            if isinstance(k, str) and k.strip().lower() in SECRET_KEYS and v:
+                out[k] = REDACTED
+            else:
+                out[k] = _scrub(v)
+        return out
+    if isinstance(obj, list):
+        return [_scrub(v) for v in obj]
+    return obj
+
+
+# --- HTTP helpers -----------------------------------------------------------
+
+
+def _unwrap(r: httpx.Response) -> Any:
+    """Decode a response and scrub secrets before it reaches the caller."""
+    body = r.json()
+    return _scrub(body)
+
 
 def _get(path: str, params: Optional[dict] = None) -> Any:
     """Make a GET request to the Pinchflat API."""
     with httpx.Client(timeout=30) as client:
         r = client.get(f"{BASE}{path}", headers=HEADERS, params=params)
         r.raise_for_status()
-        return r.json()
+        return _unwrap(r)
 
 
 def _post(path: str, json: Optional[dict] = None) -> Any:
@@ -34,7 +120,7 @@ def _post(path: str, json: Optional[dict] = None) -> Any:
     with httpx.Client(timeout=30) as client:
         r = client.post(f"{BASE}{path}", headers=HEADERS, json=json)
         r.raise_for_status()
-        return r.json()
+        return _unwrap(r)
 
 
 def _put(path: str, json: dict) -> Any:
@@ -42,38 +128,40 @@ def _put(path: str, json: dict) -> Any:
     with httpx.Client(timeout=30) as client:
         r = client.put(f"{BASE}{path}", headers=HEADERS, json=json)
         r.raise_for_status()
-        return r.json()
+        return _unwrap(r)
 
 
-def _delete(path: str) -> Any:
+def _delete(path: str, params: Optional[dict] = None, timeout: int = 30) -> Any:
     """Make a DELETE request to the Pinchflat API."""
-    with httpx.Client(timeout=30) as client:
-        r = client.delete(f"{BASE}{path}", headers=HEADERS)
+    with httpx.Client(timeout=timeout) as client:
+        r = client.delete(f"{BASE}{path}", headers=HEADERS, params=params)
         r.raise_for_status()
-        return r.json()
+        return _unwrap(r)
 
 
 # --- Sources ---
 
-@mcp.tool()
+
+@tool()
 def list_sources() -> dict:
     """List all configured media sources (YouTube channels, playlists, etc.)."""
     return _get("/sources")
 
 
-@mcp.tool()
+@tool()
 def get_source(source_id: int) -> dict:
     """Get details of a specific source by ID, including its pending tasks."""
     return _get(f"/sources/{source_id}")
 
 
-@mcp.tool()
+@tool()
 def create_source(
     original_url: str,
     media_profile_id: int,
     collection_type: str = "channel",
     custom_name: Optional[str] = None,
     download_cutoff_date: Optional[str] = None,
+    retention_period_days: Optional[int] = None,
 ) -> dict:
     """Create a new media source (e.g. add a YouTube channel to monitor).
 
@@ -83,6 +171,8 @@ def create_source(
         collection_type: 'channel', 'playlist', or 'video'
         custom_name: Optional custom name for the source
         download_cutoff_date: Only download media after this date (YYYY-MM-DD)
+        retention_period_days: Delete downloaded media this many days after
+            publication; omit to keep everything
     """
     source = {
         "media_profile_id": media_profile_id,
@@ -93,18 +183,30 @@ def create_source(
         source["custom_name"] = custom_name
     if download_cutoff_date:
         source["download_cutoff_date"] = download_cutoff_date
+    if retention_period_days is not None:
+        source["retention_period_days"] = retention_period_days
     return _post("/sources", json={"source": source})
 
 
-@mcp.tool()
+@tool()
 def update_source(
     source_id: int,
     custom_name: Optional[str] = None,
     download_cutoff_date: Optional[str] = None,
     enabled: Optional[bool] = None,
     index_frequency_minutes: Optional[int] = None,
+    retention_period_days: Optional[int] = None,
+    prevent_culling: Optional[bool] = None,
+    download_media: Optional[bool] = None,
 ) -> dict:
-    """Update an existing source. Only provided fields will be changed."""
+    """Update an existing source. Only provided fields will be changed.
+
+    Args:
+        retention_period_days: Delete downloaded media this many days after
+            publication (0 keeps everything)
+        prevent_culling: If True, never delete this source's downloads
+        download_media: If False, index the source but download nothing
+    """
     updates = {}
     if custom_name is not None:
         updates["custom_name"] = custom_name
@@ -114,34 +216,46 @@ def update_source(
         updates["enabled"] = enabled
     if index_frequency_minutes is not None:
         updates["index_frequency_minutes"] = index_frequency_minutes
+    if retention_period_days is not None:
+        updates["retention_period_days"] = retention_period_days
+    if prevent_culling is not None:
+        updates["prevent_culling"] = prevent_culling
+    if download_media is not None:
+        updates["download_media"] = download_media
+    if not updates:
+        return {"data": {"message": "No fields to update."}}
     return _put(f"/sources/{source_id}", json={"source": updates})
 
 
-@mcp.tool()
+@tool()
 def delete_source(source_id: int) -> dict:
-    """Delete a source (marks it for deletion)."""
+    """Delete a source (marks it for deletion).
+
+    Note: this removes the source and its media records, but does NOT delete
+    the files from disk. Delete the media items first if space is the goal.
+    """
     return _delete(f"/sources/{source_id}")
 
 
-@mcp.tool()
+@tool()
 def force_download_pending(source_id: int) -> dict:
     """Force download of all pending media items for a source."""
     return _post(f"/sources/{source_id}/force_download_pending")
 
 
-@mcp.tool()
+@tool()
 def force_redownload(source_id: int) -> dict:
     """Force re-download of all existing media for a source."""
     return _post(f"/sources/{source_id}/force_redownload")
 
 
-@mcp.tool()
+@tool()
 def force_index(source_id: int) -> dict:
     """Force re-index of a source."""
     return _post(f"/sources/{source_id}/force_index")
 
 
-@mcp.tool()
+@tool()
 def force_metadata_refresh(source_id: int) -> dict:
     """Force metadata refresh for a source."""
     return _post(f"/sources/{source_id}/force_metadata_refresh")
@@ -149,7 +263,8 @@ def force_metadata_refresh(source_id: int) -> dict:
 
 # --- Media Items ---
 
-@mcp.tool()
+
+@tool()
 def list_media(
     source_id: Optional[int] = None,
     limit: int = 50,
@@ -172,25 +287,25 @@ def list_media(
     return _get("/media", params=params)
 
 
-@mcp.tool()
+@tool()
 def search_media(query: str) -> dict:
     """Search media items by title or description."""
     return _get("/media/search", params={"q": query})
 
 
-@mcp.tool()
+@tool()
 def get_media(media_id: int) -> dict:
     """Get details of a specific media item."""
     return _get(f"/media/{media_id}")
 
 
-@mcp.tool()
+@tool()
 def force_download_media(media_id: int) -> dict:
     """Force download of a specific media item."""
     return _post(f"/media/{media_id}/force_download")
 
 
-@mcp.tool()
+@tool()
 def delete_media(media_id: int, prevent_download: bool = False) -> dict:
     """Delete a media item's downloaded files from disk.
 
@@ -201,21 +316,19 @@ def delete_media(media_id: int, prevent_download: bool = False) -> dict:
     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()
+    return _delete(f"/media/{media_id}", params=params, timeout=120)
 
 
 # --- Media Profiles ---
 
-@mcp.tool()
+
+@tool()
 def list_media_profiles() -> dict:
     """List all media profiles (download quality/container settings)."""
     return _get("/media_profiles")
 
 
-@mcp.tool()
+@tool()
 def get_media_profile(profile_id: int) -> dict:
     """Get details of a specific media profile."""
     return _get(f"/media_profiles/{profile_id}")
@@ -223,7 +336,8 @@ def get_media_profile(profile_id: int) -> dict:
 
 # --- Tasks ---
 
-@mcp.tool()
+
+@tool()
 def list_tasks(source_id: Optional[int] = None) -> dict:
     """List all tasks. Optionally filter by source_id."""
     params = {}
@@ -232,21 +346,22 @@ def list_tasks(source_id: Optional[int] = None) -> dict:
     return _get("/tasks", params=params)
 
 
-@mcp.tool()
+@tool()
 def get_task(task_id: int) -> dict:
     """Get details of a specific task."""
     return _get(f"/tasks/{task_id}")
 
 
-# --- Settings & Info ---
+# --- Settings & Info (admin tier — not exposed by default) ---
 
-@mcp.tool()
+
+@tool("admin")
 def get_settings() -> dict:
-    """Get current Pinchflat settings."""
+    """Get current Pinchflat settings (credential values are redacted)."""
     return _get("/settings")
 
 
-@mcp.tool()
+@tool("admin")
 def get_app_info() -> dict:
     """Get Pinchflat app info (version, environment, etc.)."""
     return _get("/app_info")
@@ -254,4 +369,4 @@ def get_app_info() -> dict:
 
 if __name__ == "__main__":
     transport = os.environ.get("PINCHFLAT_MCP_TRANSPORT", "stdio")
-    mcp.run(transport=transport if transport in ("stdio", "http") else "stdio")
+    mcp.run(transport=transport if transport in ("stdio", "http") else "stdio")

packages/python-ssh-mcp/package.nix

@@ -0,0 +1,86 @@
+{
+  lib,
+  python313Packages,
+  fetchFromGitHub,
+  fetchPypi,
+}:
+
+# Upstream pins `requires-python = ">=3.11,<3.14"`, so this must NOT be built
+# with the default `python3Packages` (which is 3.14.x on nixos-unstable and
+# would be rejected by the build backend's requires-python check). Pin the
+# 3.13 package set explicitly.
+#
+# `fastmcp[tasks]` is a HARD runtime dependency: `src/ssh_mcp/tools/exec_tools.py`
+# does `from fastmcp.server.tasks import TaskConfig` at import time, and the
+# decorator validates at import. nixpkgs' `fastmcp` installs only the
+# client+server extras (optional-dependencies are passthru-only in nix and
+# install nothing), so the `tasks` extra's backend -- pydocket -- has to be
+# listed explicitly or the server crashes at startup.
+let
+  # Internal dependency: upstream pins `unidiff>=0.7.5,<0.8.0`, but nixpkgs only
+  # carries 1.0.0. The 0.7.x API surface used by the ssh_edit tool
+  # (`PatchSet.from_string` and hunk iteration) is unchanged in 1.0.0, but
+  # buildPythonApplication's runtime-dep check enforces the specifier, so the
+  # pinned version still has to be provided. 0.7.5 is sdist-only on PyPI
+  # (no wheel), so this is a source build.
+  unidiff = python313Packages.buildPythonPackage rec {
+    pname = "unidiff";
+    version = "0.7.5";
+
+    pyproject = true;
+    build-system = [ python313Packages.setuptools ];
+
+    src = fetchPypi {
+      inherit pname version;
+      hash = "sha256-Ll8BYgUiSJRrnwlwpA6eEkI2v4bIK3CCEUOm/B3qJXQ=";
+    };
+
+    doCheck = false;
+    pythonImportsCheck = [ "unidiff" ];
+
+    meta = with lib; {
+      description = "Unified diff parsing and application";
+      homepage = "https://github.com/matiasb/python-unidiff";
+      license = licenses.mit;
+    };
+  };
+in
+python313Packages.buildPythonApplication rec {
+  pname = "python-ssh-mcp";
+  version = "1.5.2";
+
+  pyproject = true;
+
+  src = fetchFromGitHub {
+    owner = "Nightreaver";
+    repo = "python-ssh-mcp";
+    rev = "73c00c9b0d26add59798bc7b39dff88ac547b15a"; # v1.5.2
+    hash = "sha256-OfwOiBan5sqGEs/zzHHC4vJdcALOLWaIr8uENCbQ4FU=";
+  };
+
+  build-system = [ python313Packages.hatchling ];
+
+  dependencies = with python313Packages; [
+    fastmcp
+    pydocket # the fastmcp[tasks] extra
+    asyncssh
+    pydantic
+    pydantic-settings
+    unidiff
+  ];
+
+  # Upstream ships no importable test suite in the sdist workflow used here
+  # (its 1649 tests need the dockerized sshd fixtures); skip and rely on the
+  # import check + the smoke test below.
+  doCheck = false;
+  pythonImportsCheck = [ "ssh_mcp" ];
+
+  meta = with lib; {
+    description = "SSH MCP server for multi-host systemd/docker/apt administration (read-only by default, tiered)";
+    homepage = "https://github.com/Nightreaver/python-ssh-mcp";
+    license = licenses.gpl3Only;
+    mainProgram = "ssh-mcp";
+    platforms = platforms.all;
+    maintainers = [ ];
+  };
+}

packages/zotero-mcp/package.nix

@@ -93,27 +93,31 @@ python3Packages.buildPythonApplication rec {
     # anything needed at runtime must live in this list.
     pymupdf
     ebooklib
+    # Runtime deps for the semantic-search tools (upstream "semantic" extra).
+    # zotero_mcp.semantic_search imports chromadb unconditionally at module
+    # scope (embeddings/providers/__init__.py, chroma_client.py), so these are
+    # hard requirements, not truly optional at runtime.
+    chromadb
+    sentence-transformers
+    openai
+    google-genai
+    tiktoken
   ];
 
-  # Optional extras (semantic search, PDF, scite).
-  # NOTE: buildPythonApplication stores these in passthru only and does NOT
-  # install them; adding an extra here has no runtime effect.
-  optional-dependencies = with python3Packages; {
-    semantic = [
-      chromadb
-      sentence-transformers
-      openai
-      google-genai
-      tiktoken
-    ];
-    pdf = [
-      pymupdf
-      ebooklib
-    ];
-    scite = [
-      requests
-    ];
-  };
+  # `zotero_get_pdf_outline` reads a PDF's table of contents in a throwaway
+  # `sys.executable -c ...` child (tools/write.py, _extract_pdf_toc). Under the
+  # Nix wrapper this package's dependencies are injected into the *parent*
+  # interpreter via site.addsitedir, never exported as PYTHONPATH, so the child
+  # gets a bare sys.path and its `import pymupdf` fails. The tool then reports
+  # "PyMuPDF (fitz) is required..." even though PyMuPDF is a build input.
+  # Forward the parent's sys.path so the child resolves the same modules.
+  # Mirrors nixpkgs' python-modules/vllm/0003-propagate-pythonpath.patch.
+  postPatch = ''
+    substituteInPlace src/zotero_mcp/tools/write.py \
+      --replace-fail \
+        'child_env.setdefault("PYTHONUTF8", "1")' \
+        'child_env.setdefault("PYTHONUTF8", "1"); child_env["PYTHONPATH"] = os.pathsep.join(p for p in sys.path if p)'
+  '';
 
   pythonImportsCheck = [ "zotero_mcp" ];