pwpush-mcp 0.2.0__tar.gz

pwpush_mcp-0.2.0/.env.example

@@ -0,0 +1,45 @@
+# Password Pusher API token (generate at <base-url>/api_tokens).
+# Whether it is required depends on the instance: some allow anonymous
+# create/preview/expire. Listing and audit always require a token.
+PWPUSH_API_TOKEN=
+
+# Email tied to the API token. Required for authenticated calls on legacy
+# (v1) instances, which use X-User-Email + X-User-Token headers.
+PWPUSH_API_EMAIL=
+
+# Base URL of the Password Pusher instance.
+# Default: https://pwpush.com
+# EU users:  https://eu.pwpush.com
+# Self-hosted: https://pwpush.example.com
+PWPUSH_BASE_URL=https://pwpush.com
+
+# API generation: auto (default), v1, or v2. 'auto' probes /api/v2/version
+# and falls back to the legacy v1 endpoints when absent.
+PWPUSH_API_VERSION=auto
+
+# TLS verification. Set to false ONLY for internal instances with an untrusted
+# certificate chain. Prefer PWPUSH_CA_BUNDLE with the instance's CA instead.
+PWPUSH_VERIFY_SSL=true
+# PWPUSH_CA_BUNDLE=/path/to/ca-bundle.pem
+
+# --- Security / multi-tenant knobs ------------------------------------------
+# Read-only mode: removes write tools (create_push, expire_push). Preview,
+# list, audit and version remain available.
+PWPUSH_READ_ONLY=false
+
+# Tool allowlist (comma-separated fnmatch globs). Empty = all tools enabled.
+# Example: list_*,get_version,preview_push
+PWPUSH_ENABLED_TOOLS=
+
+# Emit one JSON audit line per write-tool invocation on stderr.
+PWPUSH_AUDIT_LOG=true
+
+# --- Reliability knobs ------------------------------------------------------
+# Cap concurrent in-flight HTTP requests. 0 = unlimited.
+PWPUSH_MAX_CONCURRENT=0
+
+# Retries for transient failures (connection errors, 429, 5xx) with backoff.
+PWPUSH_MAX_RETRIES=2
+
+# Per-request HTTP timeout, in seconds.
+PWPUSH_TIMEOUT=30

pwpush_mcp-0.2.0/.github/dependabot.yml

@@ -0,0 +1,26 @@
+version: 2
+updates:
+  # Keep GitHub Actions SHA pins up to date automatically. Dependabot updates
+  # both the SHA and the inline version comment.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    commit-message:
+      prefix: "chore(deps)"
+    labels:
+      - "ci/cd"
+      - "security"
+
+  # Keep Python dependencies up to date within the declared bounds. Upper bounds
+  # on mcp and httpx prevent silent breaking upgrades (see tests/test_packaging.py).
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    commit-message:
+      prefix: "chore(deps)"
+    labels:
+      - "ci/cd"

pwpush_mcp-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: ruff check src tests
+      - run: ruff format --check src tests
+      - run: mypy src
+      - name: pytest with coverage
+        run: pytest -q --cov=pwpush_mcp --cov-report=term --cov-report=xml --cov-fail-under=80
+      - name: catalog metadata is up to date
+        run: |
+          python scripts/gen_metadata.py >/dev/null
+          git diff --exit-code catalog/metadata.json \
+            || { echo "catalog/metadata.json is stale — run scripts/gen_metadata.py and commit"; exit 1; }
+
+  docker:
+    needs: lint-test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5  # v4.1.0
+      - run: docker build -t pwpush-mcp:ci .

pwpush_mcp-0.2.0/.github/workflows/pypi.yml

@@ -0,0 +1,50 @@
+name: Publish to PyPI (manual fallback)
+
+# Automatic PyPI publishing on vX.Y.Z tags is handled by release.yml
+# (publish-pypi job). This workflow exists only as a manual fallback via
+# workflow_dispatch in case that job needs to be re-run independently.
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write   # required for PyPI trusted publishing
+
+jobs:
+  build:
+    name: Build wheel + sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
+        with:
+          python-version: "3.12"
+      - run: pip install --upgrade build
+      - run: python -m build
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI (trusted publisher)
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pwpush-mcp
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4.3.0
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14.0
+        with:
+          # OIDC trusted publishing — no token needed once the pending publisher
+          # is configured on pypi.org (Account Settings -> Publishing):
+          #   PyPI project name: pwpush-mcp
+          #   Repository owner:  k9fr4n
+          #   Repository name:   pwpush-mcp
+          #   Workflow name:     pypi.yml
+          #   Environment:       pypi
+          attestations: true

pwpush_mcp-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,91 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: write   # create GitHub Releases
+  packages: write   # push to GHCR
+  id-token: write   # PyPI OIDC trusted publishing
+
+jobs:
+  image:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+
+      - uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130  # v3.7.0
+      - uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5  # v4.1.0
+
+      - uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9  # v3.7.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - id: meta
+        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051  # v5.10.0
+        with:
+          images: ghcr.io/${{ github.repository_owner }}/pwpush-mcp
+          tags: |
+            type=ref,event=branch
+            type=semver,pattern=v{{version}}
+            type=semver,pattern=v{{major}}.{{minor}}
+            type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/v') }}
+
+      - name: Generate Docker MCP Gateway metadata label
+        run: |
+          pip install -e . -q
+          SERVER_METADATA=$(python scripts/gen_metadata.py)
+          echo "SERVER_METADATA=${SERVER_METADATA}" >> "$GITHUB_ENV"
+
+      - uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf  # v7.2.0
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            SERVER_METADATA=${{ env.SERVER_METADATA }}
+          provenance: true
+          sbom: true
+
+      # Create a GitHub Release only when a vX.Y.Z tag is pushed.
+      # --generate-notes builds the changelog from commits since the previous tag.
+      # `gh release create` is idempotent: it exits 0 if the release already exists.
+      - name: Create GitHub Release
+        if: startsWith(github.ref, 'refs/tags/v')
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "${GITHUB_REF_NAME}" \
+            --title "${GITHUB_REF_NAME}" \
+            --generate-notes \
+            --latest \
+          || echo "Release already exists, skipping."
+
+  # Publish to PyPI on every vX.Y.Z tag. Runs in the same workflow so the
+  # GITHUB_TOKEN cross-workflow event limitation is irrelevant.
+  publish-pypi:
+    name: Publish to PyPI
+    needs: image
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pwpush-mcp
+    permissions:
+      id-token: write  # OIDC trusted publishing
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
+        with:
+          python-version: "3.12"
+      - run: pip install --upgrade build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14.0
+        with:
+          attestations: true

pwpush_mcp-0.2.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtualenvs
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Local planning notes
+.claude/plans/
+
+# Env / secrets
+.env
+.env.local
+.mcp.json
+
+# OS
+.DS_Store

pwpush_mcp-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,26 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-json
+      - id: check-added-large-files
+      - id: check-merge-conflict
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.13.0
+    hooks:
+      - id: mypy
+        files: ^src/
+        additional_dependencies:
+          - httpx>=0.27
+          - mcp[cli]>=1.2.0

pwpush_mcp-0.2.0/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-06-05
+
+First packaged, distributable release. The server moves to the low-level MCP
+SDK, gains an HTTP transport, security/multi-tenant knobs, and a full
+distribution + governance setup inspired by
+[thruk-mcp](https://github.com/k9fr4n/thruk-mcp).
+
+### Added
+
+- **HTTP transport**: `pwpush-mcp --listen PORT` exposes the server over
+  Streamable-HTTP/SSE (Starlette + uvicorn). `--host` / `--log-level` flags.
+  stdio remains the default.
+- **Docker image**: multi-stage `Dockerfile` (non-root user, wheel build) and
+  `compose.yml`. Published to `ghcr.io/k9fr4n/pwpush-mcp` on each `vX.Y.Z` tag.
+- **Docker MCP Gateway**: `catalog/server.yaml` + generated `catalog/metadata.json`
+  and the `io.docker.server.metadata` OCI label so the gateway forwards tool
+  arguments correctly. `scripts/gen_metadata.py` regenerates the catalog.
+- **Release automation**: `release.yml` builds multi-arch (amd64/arm64) images
+  with SBOM + provenance, creates the GitHub Release, and publishes to PyPI via
+  OIDC trusted publishing. `pypi.yml` is a manual fallback. `dependabot.yml`
+  keeps Actions (SHA-pinned) and Python deps current.
+- **Security / multi-tenant knobs**:
+  - `PWPUSH_READ_ONLY=true` removes write tools (`create_push`, `expire_push`).
+  - `PWPUSH_ENABLED_TOOLS=list_*,get_version` restricts the exposed tool surface
+    via fnmatch globs.
+  - `PWPUSH_AUDIT_LOG=true` (default) emits one JSON line per write-tool
+    invocation on the `pwpush_mcp.audit` logger; secrets are redacted.
+- **Reliability knobs**: `PWPUSH_MAX_CONCURRENT` (concurrency cap),
+  `PWPUSH_MAX_RETRIES` (transport retries + 429/5xx backoff honouring
+  `Retry-After`), `PWPUSH_TIMEOUT`.
+- **Governance**: `CONTRIBUTING.md`, `SUPPORT.md`, `UPGRADING.md`,
+  `.pre-commit-config.yaml`, this `CHANGELOG.md`.
+- New tests for config knobs, tool filtering, audit logging, retries/concurrency,
+  catalog drift, and dependency bounds.
+
+### Changed
+
+- **Server rewritten on the low-level MCP SDK** (`mcp.server.Server`) instead of
+  FastMCP, with explicit `inputSchema` per tool. Dependency `fastmcp` replaced by
+  `mcp[cli]` (+ `uvicorn`, `starlette`).
+- `Config.__repr__` / `__str__` now redact the API token unconditionally.
+- CI gained `ruff format --check`, `mypy src`, a 80% coverage gate, a catalog
+  drift check, and a Docker build job; Actions are pinned to commit SHAs.
+- Dependency upper bounds added for `mcp` (`<2.0`) and `httpx` (`<1.0`).
+
+[Unreleased]: https://github.com/k9fr4n/pwpush-mcp/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/k9fr4n/pwpush-mcp/releases/tag/v0.2.0

pwpush_mcp-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contributing to pwpush-mcp
+
+Thanks for your interest! This is a small, focused MCP server — contributions
+that keep it simple and secure are very welcome.
+
+## Development setup
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pre-commit install        # optional but recommended
+```
+
+## Before opening a PR
+
+Run the same checks CI runs:
+
+```bash
+ruff check src tests
+ruff format --check src tests
+mypy src
+pytest -q --cov=pwpush_mcp --cov-fail-under=80
+python scripts/gen_metadata.py >/dev/null   # if you touched the tool surface
+```
+
+`pre-commit run --all-files` runs the lint/format/type subset automatically.
+
+## Design invariants (please preserve)
+
+- **Never retrieve a push payload.** Retrieving consumes a view irreversibly; it
+  must stay a human action via the secret URL. There is intentionally no
+  `retrieve` tool.
+- **The API token is never a tool argument.** It comes only from
+  `PWPUSH_API_TOKEN` so the model can neither supply nor log it.
+- **Secrets never reach logs.** `payload` / `passphrase` / file contents are
+  stripped from returned objects (`client._public`) and from audit lines
+  (`audit._redact` / `audit.scrub`). `Config.__repr__` redacts the token.
+
+## Adding a tool
+
+1. Add an async handler and a `ToolSpec` to `TOOL_REGISTRY` in
+   `src/pwpush_mcp/server.py` (set `is_write` / `destructive` correctly).
+2. Regenerate the catalog: `python scripts/gen_metadata.py >/dev/null` and commit
+   `catalog/metadata.json` (CI fails on drift).
+3. Add tests under `tests/`.
+
+## Adding an env var
+
+1. Add the field + parsing in `src/pwpush_mcp/config.py`.
+2. Document it in `.env.example` and the README configuration table.
+3. If it is operator-facing, add it to `catalog/server.yaml`.
+
+## Commit / PR conventions
+
+- Conventional-commit style prefixes (`feat:`, `fix:`, `chore:`, `docs:`, `ci:`).
+- One logical change per PR; update `CHANGELOG.md` under `[Unreleased]`.
+
+## Releasing (maintainers)
+
+1. Move `[Unreleased]` notes to a new `[X.Y.Z]` section in `CHANGELOG.md`.
+2. Bump `version` in `pyproject.toml` and `__version__` in
+   `src/pwpush_mcp/__init__.py`.
+3. Tag and push: `git tag vX.Y.Z && git push origin vX.Y.Z`.
+4. `release.yml` builds/pushes the multi-arch image, creates the GitHub Release,
+   and publishes to PyPI (OIDC). No manual token handling.

pwpush_mcp-0.2.0/Dockerfile

@@ -0,0 +1,30 @@
+# syntax=docker/dockerfile:1.7
+FROM python:3.12-slim AS build
+WORKDIR /src
+RUN pip install --no-cache-dir build
+COPY pyproject.toml README.md ./
+COPY src ./src
+RUN python -m build --wheel --outdir /dist
+
+FROM python:3.12-slim
+RUN useradd -r -u 1001 -m pwpush
+WORKDIR /app
+COPY --from=build /dist/*.whl /tmp/
+RUN pip install --no-cache-dir /tmp/*.whl && rm -f /tmp/*.whl
+
+# Embed the Docker MCP Gateway catalog metadata so that self-configured
+# deployments (docker:// references) expose correct tool argument schemas.
+# Without this label the gateway uses empty schemas and strips all arguments
+# before forwarding tool calls, causing "Field required" errors at runtime.
+# The value is produced by scripts/gen_metadata.py and injected at build time:
+#   --build-arg SERVER_METADATA="$(python scripts/gen_metadata.py)"
+ARG SERVER_METADATA="{}"
+LABEL io.docker.server.metadata="$SERVER_METADATA"
+
+USER pwpush
+ENV PYTHONUNBUFFERED=1
+# Default = stdio transport (Docker MCP Gateway / Claude Desktop / Claude Code).
+# For HTTP/Streamable-HTTP, override CMD: ["--listen", "8000"]
+EXPOSE 8000
+ENTRYPOINT ["pwpush-mcp"]
+CMD []

pwpush_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pwpush-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.