paperless-ngx-mcp/README.md

Hermes/paperless-ngx-mcp

Container image for the Paperless-ngx MCP server (freeformz/paperless-ngx-mcp) exposed over streamable-HTTP, consumed by Hermes in cluster0 (namespace ai-0-7).

• Upstream ships stdio only; this image wraps it with mcp-proxy==0.9.0 (stdio → streamable-HTTP) — a combination verified end-to-end: MCP initialize + tools/list over POST /mcp/ returned all 116 tools.
• Endpoint served on :3000: MCP at /mcp/ (trailing slash required for this proxy version), health at /status (JSON 200).
• Newer mcp-proxy releases (0.11/0.12) resolve incompatible mcp SDK versions and fail at import — the pin is deliberate. Version bumps happen via the weekly workflow, which resolves the newest upstream release itself.

Build

• Triggered on push to main, weekly (Mon 06:00 UTC, ahead of the cluster0 Monday image-update cron), or workflow_dispatch with an explicit version.
• Pushes gitea.williammiceli.systems/hermes/paperless-ngx-mcp:v<ver> + :latest.
• Push auth uses the REGISTRY_TOKEN repo Actions secret (scoped PAT with write:package) — Gitea's job token cannot push packages (issue #23642).

Consumed by

• Cluster0 manifests: William/Kubernetes_Cluster0 → ai-0-7 (Paperless MCP)/PaperlessMCP-Application.yaml
• Paperless instance: paperlessngx-service.personal-2.svc.cluster.local (v3.1.3)