pse-edge-mcp 0.16.0__tar.gz

pse_edge_mcp-0.16.0/.dockerignore

@@ -0,0 +1,18 @@
+# Keep the build context minimal and secret-free.
+.git
+.github
+.env*
+!.env.example
+tests
+docs
+**/__pycache__
+**/*.pyc
+.venv
+.pytest_cache
+.mypy_cache
+.ruff_cache
+compose*.yaml
+Dockerfile
+CHANGELOG.md
+*.md
+!README.md

pse_edge_mcp-0.16.0/.env.example

@@ -0,0 +1,106 @@
+# Copy to .env for docker compose. NEVER commit .env.
+POSTGRES_PASSWORD=change-me
+# DATABASE_URL is set automatically inside compose; for bare-metal runs:
+# DATABASE_URL=postgresql+asyncpg://pse:change-me@localhost:5432/pse_edge
+
+# Market session overrides (defaults shown)
+# PSE_MARKET_OPEN=09:30
+# PSE_MARKET_CLOSE=15:00
+# PSE_THROTTLE_RPS=1.0
+
+# Auth — opt-in, requires DATABASE_URL. Users self-serve via OAuth 2.1 + passkeys; the CLI
+# is for clients that do not speak OAuth, and is the only route on a plain-http deployment.
+# Provision accounts with: pse-edge-admin create-user EMAIL && pse-edge-admin issue-token EMAIL
+# PSE_AUTH_REQUIRED=1
+# PSE_TOKEN_CACHE_TTL=60      # seconds; this is the revocation-latency budget, nothing else
+# PSE_QUOTA_PER_MIN=60
+# PSE_QUOTA_PER_DAY=2000
+
+# DB connection pool (auth adds a potential lookup per request; tune under load)
+# PSE_DB_POOL_SIZE=5
+# PSE_DB_MAX_OVERFLOW=10
+
+# Email (signup verification). The ZeptoMail key arrives at runtime only, never committed.
+# ZEPTOMAIL_API_KEY=
+#
+# PSE_EMAIL_FROM must be an address on a domain ZeptoMail has VERIFIED, and it is the most
+# common thing to get wrong. ZeptoMail verifies EXACT domains: a verified example.com does
+# NOT cover mcp.example.com. Both compose files default this to no-reply@$PSE_DOMAIN, which
+# is therefore wrong whenever your hostname is a subdomain. An unverified sender is refused
+# with a bare HTTP 500 and an empty body, so signup fails in a way that looks like the
+# server is broken rather than misconfigured. Test it before trusting it:
+#   curl -sS -X POST https://api.zeptomail.com/v1.1/email \
+#     -H "Authorization: Zoho-enczapikey $ZEPTOMAIL_API_KEY" \
+#     -H 'Content-Type: application/json' \
+#     -d '{"from":{"address":"noreply@example.com"},
+#          "to":[{"email_address":{"address":"you@example.com"}}],
+#          "subject":"test","htmlbody":"<p>test</p>"}'
+# PSE_EMAIL_FROM=noreply@example.com
+#
+# Where the nightly schema canary reports failures. It emails ONLY on failure — a nightly
+# "all fine" message is filtered within a week, and a filtered alert feels like coverage
+# while providing none. Unset, the canary still runs and still logs, but nobody is told.
+# PSE_OPERATOR_EMAIL=ops@example.com
+#
+# Accounts allowed to provision machine clients (headless/agent credentials) from the
+# /account web page — the way to grant agent access on a NAS with no shell. Comma-separated,
+# matched against the signed-in account's email. This is the SAME authority as the
+# pse-edge-admin CLI: keep it to yourself. Empty = web provisioning off, CLI only.
+# PSE_ADMIN_EMAILS=you@example.com
+#
+# PSE_PUBLIC_URL=https://mcp.example.com   # drives WebAuthn rp_id, email links, OAuth issuer
+# PSE_USAGE_RETENTION_DAYS=90              # the privacy page states 90 — changing this
+#                                          # changes what users were told
+
+# --- VPS or host reachable on 80/443 (compose.yaml + compose.prod.yaml) — docs/deploy.md ---
+# Caddy publishes high by default (8280/8243) to stay clear of a NAS's own web UI. Only the
+# published side moves — Caddy still listens on 80/443 inside the container. YOUR ROUTER MUST
+# FORWARD 80 -> 8280 AND 443 -> 8243, because certificate authorities always validate on 80
+# (HTTP-01) or 443 (TLS-ALPN-01) and no setting changes that. If you cannot forward, use the
+# NAS + tunnel path below, which needs no inbound ports at all.
+# PSE_HTTP_PORT=8280
+# PSE_HTTPS_PORT=8243
+# PSE_DOMAIN must be the real public hostname: it becomes PSE_PUBLIC_URL, which drives the
+# WebAuthn rp_id, the email links and the OAuth issuer. Wrong value = passkeys silently
+# break, because credentials are bound to the origin they were enrolled under.
+# PSE_DOMAIN=mcp.example.com
+# PSE_ACME_EMAIL=ops@example.com
+# PSE_IMAGE_TAG=0.11.0                 # PIN THIS — production pulls, it does not build.
+# BACKUP_RETENTION_DAYS=14
+# PSE_LOG_JSON=1
+# PSE_LOG_LEVEL=INFO
+
+# --- NAS stage 1: LAN only (compose.nas.yaml) — see docs/deploy.md ---
+# Needs nothing from Cloudflare. Reachable at http://<nas-ip>:8200; auth is on, and passkeys
+# cannot work over plain http, so mint a token with `pse-edge-admin issue-token`.
+# PSE_IMAGE_TAG=0.11.0                 # PIN THIS. :latest may predate a flag this file uses.
+# PSE_LAN_PORT=8200                   # host side only; the app always listens on 8000 inside
+# PSE_WORKERS=1                       # each worker multiplies the in-memory quota ceiling
+# APP_MEMORY_LIMIT=768m
+# DB_MEMORY_LIMIT=1g
+#
+# Put the database and its dumps on NAS directories you can see and snapshot. Create both
+# first — Docker will not, and the mount error does not name the missing path. Keep backups
+# OUTSIDE the database directory: a backup stored inside the thing it protects is not one.
+#
+# No chown needed. Postgres runs as uid 999 and a bind mount would otherwise arrive
+# root-owned, crash-looping on "mkdir: cannot create directory '/var/lib/postgresql':
+# Permission denied" — so a `pgdata-owner` container fixes the ownership before the
+# database starts. That matters on a NAS UI, which may give you no shell at all.
+#
+# PGDATA must be the NAS's OWN internal volume, never SMB/NFS/USB: Postgres needs POSIX
+# locking and honest fsync. Dumps are just files, so a network share is fine for backups.
+# SETTING PSE_PGDATA_PATH ON AN EXISTING DEPLOYMENT STARTS AN EMPTY DATABASE — dump first,
+# see docs/deploy.md "Moving the database onto a NAS share".
+# PSE_PGDATA_PATH=/volume1/docker/pse-mcp/pgdata
+# PSE_BACKUP_PATH=/volume1/docker/pse-mcp/backups
+
+# --- NAS stage 2: public hostname (+ compose.tunnel.yaml) — see docs/deploy.md ---
+# cloudflared dials out; Cloudflare terminates TLS, so no ACME here. Set PSE_LAN_BIND to
+# close the stage 1 LAN port — an overlay cannot remove a port, because Compose merges
+# `ports` additively, so binding it to loopback is how it stops being reachable.
+# PSE_LAN_BIND=127.0.0.1
+# PSE_DOMAIN=mcp.example.com
+# Set PSE_EMAIL_FROM in the Email section above — signup goes live at this stage, and the
+# default derived from PSE_DOMAIN is wrong if this hostname is a subdomain.
+# CLOUDFLARE_TUNNEL_TOKEN=            # Zero Trust -> Networks -> Tunnels

pse_edge_mcp-0.16.0/.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: CI
+
+on:
+  # develop is the integration branch; main is covered by release.yml, which reruns
+  # these same gates before it publishes anything.
+  push:
+    branches: [develop]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          python-version: "3.14"
+      - run: uv sync --all-extras
+      - run: uv run ruff check .
+      - run: uv run pytest -q
+
+  # Both published architectures are gated here, on native runners (free for public
+  # repos), so arm64 breakage is caught at review time rather than at publish time —
+  # otherwise a green PR could merge and then leave main with no image at all.
+  # `name:` is pinned so the required-check contexts stay exactly "image (amd64)" and
+  # "image (arm64)"; without it GitHub would name them after every matrix value.
+  image:
+    name: image (${{ matrix.arch }})
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: amd64
+            runner: ubuntu-latest
+          - arch: arm64
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          python-version: "3.14"
+      # Each runner is native for its own arch, so a plain build needs no buildx or QEMU.
+      - name: Build image
+        run: docker build -t pse-edge-mcp:ci .
+      # Enforces necessity, not a megabyte number: installed distributions must equal
+      # the resolved runtime closure, with no toolchain, package manager, dev deps,
+      # caches, or stray source tree. Size is reported for information only.
+      - name: Check image contains only what the app needs
+        run: |
+          # pipefail matters: without it the pipeline returns tee's status and a failed
+          # check would pass silently.
+          set -eo pipefail
+          uv sync --all-extras --quiet
+          uv run python scripts/check_image.py pse-edge-mcp:ci --extra postgres --extra auth | tee -a "$GITHUB_STEP_SUMMARY"
+      - name: Scan image for secrets & vulns
+        uses: aquasecurity/trivy-action@v0.36.0
+        with:
+          image-ref: pse-edge-mcp:ci
+          scanners: secret
+          exit-code: "1"
+      - name: Smoke-test the image
+        run: |
+          ARCH=$(docker image inspect pse-edge-mcp:ci --format '{{.Architecture}}')
+          test "$ARCH" = "${{ matrix.arch }}"
+          TOOLS=$(docker run --rm --entrypoint python pse-edge-mcp:ci -c '
+          import asyncio
+          from pse_edge_mcp.server import build_server
+          print(len(asyncio.run(build_server().list_tools())))')
+          echo "Tools registered on $ARCH: $TOOLS"
+          test "$TOOLS" -ge 6

pse_edge_mcp-0.16.0/.github/workflows/release.yml

@@ -0,0 +1,308 @@
+name: Release
+
+# Merges to main publish a multi-arch container image to GHCR:
+#   docker pull ghcr.io/phdwight/pse-edge-mcp:latest        # linux/amd64 + linux/arm64
+#
+# A merge that bumps `version` in pyproject.toml also cuts a GitHub Release and a
+# matching immutable image tag; merges that don't bump only move :latest and :sha-*.
+#
+# Each architecture is built on its OWN NATIVE RUNNER (free for public repos) rather
+# than emulated under QEMU, which keeps builds fast and — more importantly — lets the
+# gates run natively per arch. Invariant #5 (thin, secret-free images) is enforced on
+# every architecture BEFORE anything reaches the registry, so a bloated or broken
+# arm64 image can't ride along behind a passing amd64 one.
+#
+# Publishing is two-phase: each arch pushes an untagged blob addressed by digest, then
+# the merge job stitches those digests into one manifest list under the real tags. That
+# way a tag never exists in a half-published state.
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch: # lets you re-publish the current main on demand
+
+permissions:
+  contents: write # create the release + tag
+  packages: write # push to GHCR
+
+# Never let two main merges publish concurrently, and never cancel a half-done
+# publish: an interrupted push can leave :latest pointing at nothing useful.
+concurrency:
+  group: release-main
+  cancel-in-progress: false
+
+env:
+  IMAGE: ghcr.io/${{ github.repository }}
+
+jobs:
+  version:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      bumped: ${{ steps.version.outputs.bumped }}
+      tags: ${{ steps.version.outputs.tags }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 2 # need HEAD~1 to tell whether the version changed
+
+      - name: Resolve version and detect a bump
+        id: version
+        run: |
+          read_version() { grep -m1 '^version = ' "$1" | cut -d'"' -f2; }
+          VERSION=$(read_version pyproject.toml)
+          if [ -z "$VERSION" ]; then
+            echo "::error::could not read version from pyproject.toml"
+            exit 1
+          fi
+          git show HEAD~1:pyproject.toml > /tmp/prev-pyproject.toml 2>/dev/null || : > /tmp/prev-pyproject.toml
+          PREVIOUS=$(read_version /tmp/prev-pyproject.toml || true)
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          if [ "$VERSION" != "$PREVIOUS" ]; then
+            BUMPED=true
+            echo "Version bump: ${PREVIOUS:-none} -> $VERSION (will cut a release)"
+          else
+            BUMPED=false
+            echo "Version unchanged at $VERSION (no release; :latest still moves)"
+          fi
+          echo "bumped=$BUMPED" >> "$GITHUB_OUTPUT"
+          # Assembled here, not with an inline conditional at the point of use, so a
+          # no-bump build can never emit an empty tag.
+          TAGS="${IMAGE}:latest ${IMAGE}:sha-${GITHUB_SHA}"
+          if [ "$BUMPED" = "true" ]; then TAGS="$TAGS ${IMAGE}:${VERSION}"; fi
+          echo "tags=$TAGS" >> "$GITHUB_OUTPUT"
+          echo "Tags: $TAGS"
+
+      - name: Fail if this release tag already exists
+        if: steps.version.outputs.bumped == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          TAG="v${{ steps.version.outputs.version }}"
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            echo "::error::release $TAG already exists — bump the version in pyproject.toml"
+            exit 1
+          fi
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          python-version: "3.14"
+      - run: uv sync --all-extras
+      - run: uv run ruff check .
+      - run: uv run pytest -q
+
+  build:
+    needs: [test, version]
+    strategy:
+      fail-fast: false # report both arches' problems in one run, not just the first
+      matrix:
+        include:
+          - arch: amd64
+            platform: linux/amd64
+            runner: ubuntu-latest
+          - arch: arm64
+            platform: linux/arm64
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          python-version: "3.14"
+      - uses: docker/setup-buildx-action@v4
+
+      # Load into the local daemon first so the gates below run on the exact bits that
+      # get pushed. Native runner => no QEMU, and `docker run` works for the smoke test.
+      - name: Build ${{ matrix.platform }}
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: ${{ matrix.platform }}
+          load: true
+          tags: pse-edge-mcp:candidate
+          cache-from: type=gha,scope=${{ matrix.arch }}
+          cache-to: type=gha,mode=max,scope=${{ matrix.arch }}
+
+      # Enforces necessity, not a megabyte number — see scripts/check_image.py.
+      - name: Check image contains only what the app needs
+        run: |
+          # pipefail matters: without it the pipeline returns tee's status and a failed
+          # check would pass silently.
+          set -eo pipefail
+          uv sync --all-extras --quiet
+          {
+            echo "### \`${{ matrix.arch }}\` image"
+            echo '```'
+            uv run python scripts/check_image.py pse-edge-mcp:candidate --extra postgres --extra auth
+            echo '```'
+          } | tee -a "$GITHUB_STEP_SUMMARY"
+
+      - name: Scan image for secrets
+        uses: aquasecurity/trivy-action@v0.36.0
+        with:
+          image-ref: pse-edge-mcp:candidate
+          scanners: secret
+          exit-code: "1"
+
+      - name: Smoke-test the image
+        run: |
+          # A published image that cannot build the server is worse than no publish.
+          ARCH=$(docker image inspect pse-edge-mcp:candidate --format '{{.Architecture}}')
+          echo "Image architecture: $ARCH (expected ${{ matrix.arch }})"
+          test "$ARCH" = "${{ matrix.arch }}"
+          TOOLS=$(docker run --rm --entrypoint python pse-edge-mcp:candidate -c '
+          import asyncio
+          from pse_edge_mcp.server import build_server
+          print(len(asyncio.run(build_server().list_tools())))')
+          echo "Tools registered: $TOOLS"
+          test "$TOOLS" -ge 6
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ github.token }}
+
+      # Push untagged, addressed only by digest. The merge job gives these real tags.
+      # provenance/sbom off so the manifest list holds exactly one entry per arch.
+      - name: Push ${{ matrix.platform }} by digest
+        id: push
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: ${{ matrix.platform }}
+          provenance: false
+          sbom: false
+          outputs: type=image,name=${{ env.IMAGE }},push-by-digest=true,name-canonical=true,push=true
+          cache-from: type=gha,scope=${{ matrix.arch }}
+
+      - name: Export digest
+        run: |
+          DIGEST="${{ steps.push.outputs.digest }}"
+          if [ -z "$DIGEST" ]; then
+            echo "::error::push produced no digest"
+            exit 1
+          fi
+          echo "Pushed ${{ matrix.arch }} as $DIGEST"
+          mkdir -p /tmp/digests
+          touch "/tmp/digests/${DIGEST#sha256:}"
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: digest-${{ matrix.arch }}
+          path: /tmp/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  pypi:
+    # Publishes the sdist+wheel on every version bump via PyPI Trusted Publishing
+    # (OIDC — no long-lived secret in this repo). One-time setup on pypi.org: add a
+    # GitHub publisher for project pse-edge-mcp (owner phdwight, repo pse-edge-mcp,
+    # workflow release.yml, environment pypi). Until that exists this job fails at
+    # the upload step — visibly, without blocking the image release (nothing needs it).
+    needs: [test, version]
+    if: needs.version.outputs.bumped == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write # OIDC token for Trusted Publishing
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v9.0.0
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  merge:
+    needs: [build, version]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          path: /tmp/digests
+          pattern: digest-*
+          merge-multiple: true
+
+      - uses: docker/setup-buildx-action@v4
+      - name: Log in to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ github.token }}
+
+      - name: Create the multi-arch manifest list
+        env:
+          TAGS: ${{ needs.version.outputs.tags }}
+        run: |
+          cd /tmp/digests
+          COUNT=$(ls -1 | wc -l)
+          echo "Digests to combine: $COUNT"
+          test "$COUNT" -eq 2 # one per architecture; fewer means an arch silently dropped
+          TAG_ARGS=""
+          for t in $TAGS; do TAG_ARGS="$TAG_ARGS -t $t"; done
+          # shellcheck disable=SC2086
+          docker buildx imagetools create $TAG_ARGS \
+            $(printf "${IMAGE}@sha256:%s " *)
+
+      - name: Verify both architectures are published
+        run: |
+          PLATFORMS=$(docker buildx imagetools inspect "${IMAGE}:latest" --format '{{json .Manifest}}' \
+            | jq -r '.manifests[]? | select(.platform.architecture != "unknown")
+                     | .platform.os + "/" + .platform.architecture' | sort -u)
+          echo "Published platforms:"; echo "$PLATFORMS"
+          echo "$PLATFORMS" | grep -qx "linux/amd64" || { echo "::error::linux/amd64 missing"; exit 1; }
+          echo "$PLATFORMS" | grep -qx "linux/arm64" || { echo "::error::linux/arm64 missing"; exit 1; }
+
+      - name: Create release
+        if: needs.version.outputs.bumped == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ needs.version.outputs.version }}
+        run: |
+          gh release create "v${VERSION}" \
+            --repo "${{ github.repository }}" \
+            --target "${{ github.sha }}" \
+            --title "v${VERSION}" \
+            --notes "$(cat <<EOF
+          Multi-arch container image (\`linux/amd64\`, \`linux/arm64\`) for v${VERSION}:
+
+          \`\`\`bash
+          docker pull ${IMAGE}:${VERSION}
+          \`\`\`
+
+          Also published as \`${IMAGE}:latest\`.
+
+          Serve streamable HTTP on :8000 (the image default):
+
+          \`\`\`bash
+          docker run --rm -p 8000:8000 ${IMAGE}:${VERSION}
+          \`\`\`
+
+          Or stdio, for Claude Desktop/Code (\`--entrypoint\` clears the default HTTP args):
+
+          \`\`\`bash
+          docker run --rm -i --entrypoint pse-edge-mcp ${IMAGE}:${VERSION}
+          \`\`\`
+
+          See [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/v${VERSION}/CHANGELOG.md) for what changed.
+          EOF
+          )"
+
+      - name: Summarise the download
+        run: |
+          {
+            echo "## Published (linux/amd64 + linux/arm64)"
+            echo
+            echo '```bash'
+            echo "docker pull ${IMAGE}:latest"
+            if [ "${{ needs.version.outputs.bumped }}" = "true" ]; then
+              echo "docker pull ${IMAGE}:${{ needs.version.outputs.version }}"
+            fi
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"

pse_edge_mcp-0.16.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.pyc
+.venv/
+.env
+.env.*
+!.env.example
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+
+# Operator-local files that must never enter public history. ugreen.yaml is the
+# operator's personal compose fork and carries a tunnel token inline; a blanket
+# `git add -A` once swept it into pushed commits, forcing a token rotation and a
+# history rewrite of develop. Never commit these.
+ugreen.yaml
+.DS_Store