gotify-mcp 0.3.0__tar.gz

gotify_mcp-0.3.0/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "gotify-mcp",
+  "interface": {
+    "displayName": "Gotify MCP"
+  },
+  "plugins": [
+    {
+      "name": "gotify-mcp",
+      "source": {
+        "source": "local",
+        "path": "./"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Utilities"
+    }
+  ]
+}

gotify_mcp-0.3.0/.app.json

@@ -0,0 +1,9 @@
+{
+  "apps": [
+    {
+      "name": "gotify-mcp",
+      "type": "mcp",
+      "config": "./.mcp.json"
+    }
+  ]
+}

gotify_mcp-0.3.0/.claude-plugin/plugin.json

@@ -0,0 +1,50 @@
+{
+  "name": "gotify-mcp",
+  "version": "0.3.0",
+  "description": "Gotify push notifications and management via MCP tools with HTTP fallback. Sends alerts for long-running tasks, plan completions, and blocked states.",
+  "author": {
+    "name": "Jacob Magar"
+  },
+  "repository": "https://github.com/jmagar/gotify-mcp",
+  "license": "MIT",
+  "keywords": [
+    "gotify",
+    "notifications",
+    "push",
+    "homelab",
+    "mcp"
+  ],
+  "userConfig": {
+    "gotify_mcp_url": {
+      "type": "string",
+      "title": "Gotify MCP Server URL",
+      "description": "Full MCP endpoint URL (e.g. http://localhost:9158/mcp). Default works if running via docker compose in this repo.",
+      "default": "https://gotify.tootie.tv/mcp",
+      "sensitive": false
+    },
+    "gotify_mcp_token": {
+      "type": "string",
+      "title": "MCP Server Bearer Token",
+      "description": "Bearer token for authenticating with the gotify-mcp server. Must match GOTIFY_MCP_TOKEN in .env. Generate with: openssl rand -hex 32",
+      "sensitive": true
+    },
+    "gotify_url": {
+      "type": "string",
+      "title": "Gotify Server URL",
+      "description": "Base URL of your Gotify server, e.g. http://gotify or https://gotify.example.com. No trailing slash.",
+      "sensitive": true
+    },
+    "gotify_app_token": {
+      "type": "string",
+      "title": "Gotify App Token",
+      "description": "Gotify application token for sending messages. Found in Gotify UI under Settings -> Apps -> Create Application.",
+      "sensitive": true
+    },
+    "gotify_client_token": {
+      "type": "string",
+      "title": "Gotify Client Token",
+      "description": "Gotify client token for management operations (list messages, manage apps/clients). Found in Gotify UI under Settings -> Clients.",
+      "sensitive": true
+    }
+  }
+}

gotify_mcp-0.3.0/.codex-plugin/plugin.json

@@ -0,0 +1,43 @@
+{
+  "name": "gotify-mcp",
+  "version": "0.3.0",
+  "description": "Gotify push notification management via MCP.",
+  "homepage": "https://github.com/jmagar/gotify-mcp",
+  "repository": "https://github.com/jmagar/gotify-mcp",
+  "license": "MIT",
+  "keywords": [
+    "gotify",
+    "notifications",
+    "push",
+    "homelab",
+    "mcp"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "apps": "./.app.json",
+  "interface": {
+    "displayName": "Gotify MCP",
+    "shortDescription": "Send and manage Gotify push notifications",
+    "longDescription": "Send push notifications and manage Gotify applications, clients, and messages through MCP tools and bundled skills.",
+    "developerName": "Jacob Magar",
+    "category": "Utilities",
+    "capabilities": [
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/jmagar/gotify-mcp",
+    "defaultPrompt": [
+      "Send a Gotify alert when this task finishes.",
+      "List my Gotify applications and clients.",
+      "Review recent Gotify messages."
+    ],
+    "brandColor": "#7B44F2",
+    "composerIcon": "./assets/icon.png",
+    "logo": "./assets/logo.svg"
+  },
+  "author": {
+    "name": "Jacob Magar",
+    "email": "jmagar@users.noreply.github.com",
+    "url": "https://github.com/jmagar"
+  }
+}

gotify_mcp-0.3.0/.dockerignore

@@ -0,0 +1,49 @@
+.git
+.github
+.claude-plugin
+.codex-plugin
+.agents
+.beads
+.dolt
+.omc
+.lavra
+.serena
+.cache
+.worktrees
+.full-review
+.full-review-archive-*
+.vscode
+.cursor
+.windsurf
+.1code
+.idea
+.env
+.env.*
+!.env.example
+*.log
+logs/
+backups/
+docs/
+specs/
+*.md
+!README.md
+__pycache__
+*.pyc
+.pytest_cache
+.ruff_cache
+.mypy_cache
+.coverage
+htmlcov
+.hypothesis
+node_modules
+dist
+coverage
+*.tsbuildinfo
+target
+Justfile
+biome.json
+.pre-commit-config.yaml
+.prettierrc
+.prettierignore
+tests/
+

gotify_mcp-0.3.0/.env.example

@@ -0,0 +1,43 @@
+# =============================================================================
+# GOTIFY SERVER CONFIGURATION
+# =============================================================================
+GOTIFY_URL=https://your-gotify-instance.example.com
+GOTIFY_CLIENT_TOKEN=your_gotify_client_token
+GOTIFY_APP_TOKEN=your_gotify_app_token
+
+# =============================================================================
+# MCP SERVER CONFIGURATION
+# =============================================================================
+GOTIFY_MCP_HOST=0.0.0.0
+GOTIFY_MCP_PORT=9158
+GOTIFY_MCP_TRANSPORT=http
+
+# Bearer token for MCP server authentication.
+# Generate with: openssl rand -hex 32
+GOTIFY_MCP_TOKEN=
+
+# Set to true to disable bearer auth (e.g. behind a trusted reverse proxy)
+GOTIFY_MCP_NO_AUTH=false
+
+# =============================================================================
+# LOGGING
+# =============================================================================
+GOTIFY_LOG_LEVEL=INFO
+
+# =============================================================================
+# DOCKER / CONTAINER SETTINGS
+# =============================================================================
+PUID=1000
+PGID=1000
+
+# External Docker network name (leave empty to use default bridge)
+DOCKER_NETWORK=
+
+# =============================================================================
+# USAGE
+# =============================================================================
+# 1. Copy this file to .env: cp .env.example .env
+# 2. Set GOTIFY_URL, GOTIFY_CLIENT_TOKEN, GOTIFY_APP_TOKEN
+# 3. Generate and set GOTIFY_MCP_TOKEN: openssl rand -hex 32
+# 4. Run: docker compose up -d
+# 5. Test: curl http://localhost:9158/health

gotify_mcp-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group dev
+      - run: uv run ty check
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group dev
+      - run: uv run pytest
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group dev
+      - run: uv export --no-hashes | uv pip compile - -q | uv pip audit --stdin || true
+  contract-drift:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: bash scripts/lint-plugin.sh

gotify_mcp-0.3.0/.github/workflows/docker-publish.yml

@@ -0,0 +1,75 @@
+name: Build and Push Docker Image
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
+
+      - name: Log in to GitHub Container Registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=sha
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@ca052bb54ab0790a636c9b5f226502c73d547a25 # v5
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          sbom: true
+          provenance: mode=max
+
+      - name: Scan image for vulnerabilities
+        if: github.event_name != 'pull_request'
+        uses: aquasecurity/trivy-action@915b19bbe73b92a6cf82a1bc12b087c9a19a5fe2 # v0.28.0
+        with:
+          image-ref: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}
+          format: 'sarif'
+          output: 'trivy-results.sarif'
+          severity: 'CRITICAL,HIGH'
+

gotify_mcp-0.3.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,63 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+  id-token: write  # required for pypa/gh-action-pypi-publish trusted publishing
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: release
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Verify tag matches pyproject.toml version
+        run: |
+          PKG_VERSION=$(grep -m1 '^version' pyproject.toml | sed 's/.*"\(.*\)".*/\1/')
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "Version mismatch: pyproject.toml=$PKG_VERSION tag=$TAG_VERSION"
+            exit 1
+          fi
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true
+
+      - name: Create GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" \
+            --title "Release $GITHUB_REF_NAME" \
+            --generate-notes \
+            dist/*
+
+      - name: Install mcp-publisher
+        run: |
+          curl -fsSL "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+
+      - name: Set version in server.json
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          jq --arg v "$VERSION" '
+            .version = $v |
+            .packages = [.packages[] | if .registryType == "pypi" then .version = $v else . end]
+          ' server.json > server.tmp && mv server.tmp server.json
+
+      - name: Authenticate to MCP Registry
+        run: ./mcp-publisher login dns --domain tootie.tv --private-key ${{ secrets.MCP_PRIVATE_KEY }}
+
+      - name: Publish to MCP Registry
+        run: ./mcp-publisher publish

gotify_mcp-0.3.0/.gitignore

@@ -0,0 +1,86 @@
+# ── Secrets ──────────────────────────────────────────────────────────────────
+.env
+.env.*
+!.env.example
+
+# ── Runtime artifacts ────────────────────────────────────────────────────────
+logs/
+backups/
+*.log
+*.pid
+*.bak
+*.bak-*
+
+# ── Claude Code / AI tooling ────────────────────────────────────────────────
+.claude/settings.local.json
+.claude/worktrees/
+.omc/
+.lavra/
+.beads/
+.dolt/
+*.db
+*.db-shm
+*.db-wal
+.beads-credential-key
+.serena/
+.worktrees/
+.full-review/
+.full-review-archive-*
+.bivvy
+
+# ── IDE / editor ─────────────────────────────────────────────────────────────
+.vscode/
+.cursor/
+.windsurf/
+.1code/
+.idea/
+.zed/
+*.iml
+*.swp
+*.swo
+*~
+.emdash.json
+
+# ── OS generated ─────────────────────────────────────────────────────────────
+.DS_Store
+Thumbs.db
+
+# ── Caches (ALL tool caches go here) ─────────────────────────────────────────
+.cache/
+
+# ── Documentation artifacts (session/plan docs, not reference) ───────────────
+.docs/
+docs/plans/
+docs/sessions/
+docs/reports/
+docs/research/
+docs/superpowers/
+specs/
+
+# ── Python ───────────────────────────────────────────────────────────────────
+.venv/
+__pycache__/
+*.py[oc]
+*.egg-info/
+*.egg
+build/
+dist/
+sdist/
+wheels/
+pip-wheel-metadata/
+*.whl
+.hypothesis/
+.pytest_cache/
+.ruff_cache/
+.ty_cache/
+.mypy_cache/
+.pytype/
+.pyre/
+.pyright/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+.tox/
+.nox/
+pip-log.txt

gotify_mcp-0.3.0/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "gotify-mcp": {
+      "type": "http",
+      "url": "${GOTIFY_MCP_URL}"
+    }
+  }
+}

gotify_mcp-0.3.0/.pre-commit-config.yaml

@@ -0,0 +1,36 @@
+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-merge-conflict
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: skills-validate
+        name: Validate skills
+        entry: just validate-skills
+        language: system
+        pass_filenames: false
+      - id: docker-security
+        name: Docker security check
+        entry: bash scripts/check-docker-security.sh
+        language: system
+        pass_filenames: false
+      - id: no-baked-env
+        name: No baked env vars
+        entry: bash scripts/check-no-baked-env.sh
+        language: system
+        pass_filenames: false
+      - id: ensure-ignore-files
+        name: Ensure ignore files
+        entry: bash scripts/ensure-ignore-files.sh --check
+        language: system
+        pass_filenames: false

gotify_mcp-0.3.0/AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

gotify_mcp-0.3.0/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [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.3.0] - 2026-04-04
+
+### Added
+- **MCP Registry publishing**: `server.json` conforming to the official MCP Registry schema; published as `tv.tootie/gotify-mcp`
+- **Automated registry CI**: `publish-pypi.yml` extended to authenticate via DNS (tootie.tv Ed25519 key) and publish to `registry.modelcontextprotocol.io` after each PyPI release
+- **PyPI ownership verification**: `<!-- mcp-name: tv.tootie/gotify-mcp -->` comment in README for registry validation
+- **OCI discoverability label**: `io.modelcontextprotocol.server.name` LABEL added to Dockerfile
+
+## [0.2.2] - 2026-04-03
+
+### Fixed
+- **OAuth discovery 401 cascade**: BearerAuthMiddleware was blocking GET /.well-known/oauth-protected-resource, causing MCP clients to surface generic "unknown error". Added WellKnownMiddleware (RFC 9728) to return resource metadata.
+
+### Added
+- **docs/AUTHENTICATION.md**: New setup guide covering token generation and client config.
+- **README Authentication section**: Added quick-start examples and link to full guide.
+
+
+
+### Added
+- FastMCP server with `gotify` and `gotify_help` tools
+- BearerAuthMiddleware with startup token validation
+- Dual transport (http/stdio via GOTIFY_MCP_TRANSPORT)
+- Action+subaction pattern for all Gotify operations
+- CLAUDE.md, AGENTS.md, GEMINI.md AI memory files
+- Multi-stage Dockerfile with non-root user (1000:1000)
+- ensure-ignore-files.sh hook for .gitignore and .dockerignore
+- .codex-plugin/plugin.json and .app.json for Codex CLI support
+- assets/ directory with icon and logo placeholders
+- gotify_mcp_token userConfig entry in plugin.json
+- .dockerignore with all required patterns
+- flock-based concurrency in sync-env.sh
+- awk-based env replacement in sync-env.sh
+
+## [0.1.0] - 2026-03-29
+
+### Added
+- Initial release
+- Gotify message sending, listing, deleting
+- Gotify application and client management
+- Docker Compose deployment

gotify_mcp-0.3.0/CLAUDE.md

@@ -0,0 +1,67 @@
+# gotify-mcp
+
+MCP server for Gotify push notification management.
+
+## Development
+
+- Language: Python (FastMCP + uv)
+- Port: 9158 (GOTIFY_MCP_PORT)
+- Auth: Bearer token (GOTIFY_MCP_TOKEN)
+
+## Commands
+
+```bash
+just dev       # run locally
+just test      # run tests
+just lint      # ruff check
+just build     # docker build
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `GOTIFY_URL` | Yes | Base URL of your Gotify server |
+| `GOTIFY_CLIENT_TOKEN` | Yes | Gotify client token for management |
+| `GOTIFY_APP_TOKEN` | Yes | Gotify app token for sending messages |
+| `GOTIFY_MCP_TOKEN` | Yes (HTTP) | Bearer token for MCP server auth |
+| `GOTIFY_MCP_URL` | No | MCP server URL (for .mcp.json) |
+| `GOTIFY_MCP_PORT` | No | MCP server port (default 9158) |
+| `GOTIFY_MCP_HOST` | No | MCP server host (default 0.0.0.0) |
+| `GOTIFY_MCP_TRANSPORT` | No | Transport mode: http or stdio (default http) |
+| `GOTIFY_MCP_NO_AUTH` | No | Set true to disable bearer auth |
+| `GOTIFY_LOG_LEVEL` | No | Log level (default INFO) |
+| `PUID` | No | User ID for container (default 1000) |
+| `PGID` | No | Group ID for container (default 1000) |
+
+## Architecture
+
+- `gotify_mcp/server.py` — FastMCP server entry point, action+subaction pattern
+- `gotify_mcp/client.py` — Gotify HTTP API client
+- `entrypoint.sh` — Container entrypoint with env validation
+- `hooks/scripts/sync-env.sh` — Syncs userConfig to .env at session start
+- `hooks/scripts/ensure-ignore-files.sh` — Ensures .gitignore and .dockerignore have required patterns
+- `hooks/scripts/fix-env-perms.sh` — Enforces chmod 600 on .env
+
+
+## Version Bumping
+
+**Every feature branch push MUST bump the version in ALL version-bearing files.**
+
+Bump type is determined by the commit message prefix:
+- `feat!:` or `BREAKING CHANGE` → **major** (X+1.0.0)
+- `feat` or `feat(...)` → **minor** (X.Y+1.0)
+- Everything else (`fix`, `chore`, `refactor`, `test`, `docs`, etc.) → **patch** (X.Y.Z+1)
+
+**Files to update (if they exist in this repo):**
+- `Cargo.toml` — `version = "X.Y.Z"` in `[package]`
+- `package.json` — `"version": "X.Y.Z"`
+- `pyproject.toml` — `version = "X.Y.Z"` in `[project]`
+- `.claude-plugin/plugin.json` — `"version": "X.Y.Z"`
+- `.codex-plugin/plugin.json` — `"version": "X.Y.Z"`
+- `gemini-extension.json` — `"version": "X.Y.Z"`
+- `README.md` — version badge or header
+- `CHANGELOG.md` — new entry under the bumped version
+
+All files MUST have the same version. Never bump only one file.
+CHANGELOG.md must have an entry for every version bump.