mcp-event-subscriptions 0.1.0a1__tar.gz

mcp_event_subscriptions-0.1.0a1/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.11.22"
+      - run: uv python install 3.12
+      - run: uv sync --frozen --group dev --python 3.12
+      - run: uv run --group dev ruff check .
+      - run: uv run --group dev black --check .
+      - run: uv run python -m unittest discover -s tests -v
+      - run: uv build

mcp_event_subscriptions-0.1.0a1/.github/workflows/publish.yml

@@ -0,0 +1,76 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing version tag to publish (for example v0.1.0a1)
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pypi-${{ github.event.release.tag_name || inputs.tag }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          ref: ${{ github.event.release.tag_name || inputs.tag }}
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        with:
+          version: "0.11.22"
+      - run: uv python install 3.12
+      - run: uv sync --frozen --group dev --python 3.12
+      - name: Check release tag matches package version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name || inputs.tag }}
+        run: |
+          uv run python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          if os.environ["RELEASE_TAG"] != f"v{version}":
+              raise SystemExit("Release tag does not match package version")
+          PY
+      - run: uv run --group dev ruff check .
+      - run: uv run --group dev black --check .
+      - run: uv run python -m unittest discover -s tests -v
+      - run: uv build
+      - run: uv run --group dev twine check --strict dist/*
+      - name: Test installed wheel in an isolated environment
+        run: |
+          wheel="$(find "$GITHUB_WORKSPACE/dist" -name '*.whl' -print -quit)"
+          cd "$RUNNER_TEMP"
+          uv run --isolated --no-project --python 3.12 --with "$wheel" \
+            python -m unittest discover -s "$GITHUB_WORKSPACE/tests" -v
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: distributions
+          path: dist/*
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/mcp-event-subscriptions/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: distributions
+          path: dist/
+      - name: Publish distributions with Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1

mcp_event_subscriptions-0.1.0a1/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/

mcp_event_subscriptions-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Appwrite
+
+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.

mcp_event_subscriptions-0.1.0a1/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.5
+Name: mcp-event-subscriptions
+Version: 0.1.0a1
+Summary: Experimental portable MCP webhook subscription records and JWE envelopes
+Project-URL: Repository, https://github.com/ChiragAgg5k/mcp-event-subscriptions
+Project-URL: Documentation, https://github.com/ChiragAgg5k/mcp-event-subscriptions#readme
+Project-URL: Issues, https://github.com/ChiragAgg5k/mcp-event-subscriptions/issues
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: jsonschema<5,>=4.23
+Requires-Dist: jwcrypto<2,>=1.5.6
+Description-Content-Type: text/markdown
+
+# MCP Event Subscriptions
+
+An experimental, portable subscription record for MCP Events, with an optional
+[JWE](https://www.rfc-editor.org/rfc/rfc7516) encrypted envelope.
+
+Store the same record in a database, a key-value store, or an upstream webhook
+configuration. This repository defines its fields, encrypted encoding, and
+validation rules, with a Python reference implementation and conformance vectors.
+
+**Independent proposal. This is not an adopted MCP specification or an IETF RFC.**
+The format may change before a stable release. It does not change MCP event
+requests or notification payloads.
+
+## What is here
+
+- [Record specification](SPEC.md) and [JSON Schema](schemas/subscription-v1.schema.json).
+- [Encrypted envelope profile](profiles/encrypted-envelope.md): JWE Compact,
+  `dir` + `A256GCM`, with explicit server/tenant/resource binding.
+- [Appwrite webhook profile](profiles/appwrite-webhook.md): proposed storage
+  mapping and the limits of write-only upstream state.
+- [Examples](examples/) and [conformance vectors](test-vectors/README.md).
+- [Python reference implementation](packages/python/README.md).
+- [Upstream discussion draft](proposals/upstream-mcp.md).
+
+## Install the alpha release
+
+Once the first release is published to PyPI:
+
+```sh
+pip install mcp-event-subscriptions==0.1.0a1
+```
+
+See [RELEASING.md](RELEASING.md) for the Trusted Publishing setup and release process.
+
+## Quick start
+
+Python 3.12 or newer and [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv sync --group dev
+uv run python examples/roundtrip.py
+uv run python -m unittest discover -s tests -v
+```
+
+```python
+import json
+import secrets
+from mcp_event_subscriptions import seal, open_envelope
+
+record = json.load(open("examples/subscription.json"))
+context = {
+    "server": "https://mcp.example.com",
+    "tenant": "project_demo",
+    "resource": record["id"],
+}
+keys = {"k1": secrets.token_bytes(32)}
+token = seal(record, keys, active_key="k1", context=context)
+restored = open_envelope(token, keys, expected_context=context)
+assert restored == record
+```
+
+The sample subscription expires in 2030. Examples and vectors use synthetic
+principals and secrets. Fixed test-vector keys are public fixtures, never
+production keys.
+
+## Scope
+
+Version 1 describes webhook subscription state and optional encrypted storage.
+It does not specify a SQL layout, implement a delivery queue, establish current
+caller authorization, or make refresh/delete operations atomic. Adapters must
+provide their own coordination and revocation checks. Encryption cannot detect
+replay of an older, still-valid envelope without current state.
+
+The Appwrite profile is documentation, not a working Appwrite adapter. It is not
+wire-compatible with the existing `v1.<kid>.<ciphertext>` envelope in
+[appwrite/mcp PR #132](https://github.com/appwrite/mcp/pull/132).
+
+## Discussing the proposal
+
+Start with the [open questions](proposals/upstream-mcp.md#open-questions): which
+fields should be common, whether an encrypted profile belongs alongside the
+schema, and what lifecycle guarantees adapters must expose. No proposal has
+been submitted upstream by this repository.
+
+## Development
+
+```sh
+uv run --group dev ruff check .
+uv run --group dev black --check .
+uv run python -m unittest discover -s tests -v
+uv build
+```
+
+Licensed under the MIT License. See [SECURITY.md](SECURITY.md) before using the
+reference implementation with real secrets.

mcp_event_subscriptions-0.1.0a1/README.md

@@ -0,0 +1,95 @@
+# MCP Event Subscriptions
+
+An experimental, portable subscription record for MCP Events, with an optional
+[JWE](https://www.rfc-editor.org/rfc/rfc7516) encrypted envelope.
+
+Store the same record in a database, a key-value store, or an upstream webhook
+configuration. This repository defines its fields, encrypted encoding, and
+validation rules, with a Python reference implementation and conformance vectors.
+
+**Independent proposal. This is not an adopted MCP specification or an IETF RFC.**
+The format may change before a stable release. It does not change MCP event
+requests or notification payloads.
+
+## What is here
+
+- [Record specification](SPEC.md) and [JSON Schema](schemas/subscription-v1.schema.json).
+- [Encrypted envelope profile](profiles/encrypted-envelope.md): JWE Compact,
+  `dir` + `A256GCM`, with explicit server/tenant/resource binding.
+- [Appwrite webhook profile](profiles/appwrite-webhook.md): proposed storage
+  mapping and the limits of write-only upstream state.
+- [Examples](examples/) and [conformance vectors](test-vectors/README.md).
+- [Python reference implementation](packages/python/README.md).
+- [Upstream discussion draft](proposals/upstream-mcp.md).
+
+## Install the alpha release
+
+Once the first release is published to PyPI:
+
+```sh
+pip install mcp-event-subscriptions==0.1.0a1
+```
+
+See [RELEASING.md](RELEASING.md) for the Trusted Publishing setup and release process.
+
+## Quick start
+
+Python 3.12 or newer and [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv sync --group dev
+uv run python examples/roundtrip.py
+uv run python -m unittest discover -s tests -v
+```
+
+```python
+import json
+import secrets
+from mcp_event_subscriptions import seal, open_envelope
+
+record = json.load(open("examples/subscription.json"))
+context = {
+    "server": "https://mcp.example.com",
+    "tenant": "project_demo",
+    "resource": record["id"],
+}
+keys = {"k1": secrets.token_bytes(32)}
+token = seal(record, keys, active_key="k1", context=context)
+restored = open_envelope(token, keys, expected_context=context)
+assert restored == record
+```
+
+The sample subscription expires in 2030. Examples and vectors use synthetic
+principals and secrets. Fixed test-vector keys are public fixtures, never
+production keys.
+
+## Scope
+
+Version 1 describes webhook subscription state and optional encrypted storage.
+It does not specify a SQL layout, implement a delivery queue, establish current
+caller authorization, or make refresh/delete operations atomic. Adapters must
+provide their own coordination and revocation checks. Encryption cannot detect
+replay of an older, still-valid envelope without current state.
+
+The Appwrite profile is documentation, not a working Appwrite adapter. It is not
+wire-compatible with the existing `v1.<kid>.<ciphertext>` envelope in
+[appwrite/mcp PR #132](https://github.com/appwrite/mcp/pull/132).
+
+## Discussing the proposal
+
+Start with the [open questions](proposals/upstream-mcp.md#open-questions): which
+fields should be common, whether an encrypted profile belongs alongside the
+schema, and what lifecycle guarantees adapters must expose. No proposal has
+been submitted upstream by this repository.
+
+## Development
+
+```sh
+uv run --group dev ruff check .
+uv run --group dev black --check .
+uv run python -m unittest discover -s tests -v
+uv build
+```
+
+Licensed under the MIT License. See [SECURITY.md](SECURITY.md) before using the
+reference implementation with real secrets.

mcp_event_subscriptions-0.1.0a1/RELEASING.md

@@ -0,0 +1,49 @@
+# Publishing to PyPI
+
+The first release is `0.1.0a1`, an alpha. The package and specification remain
+experimental. Publishing a version is permanent: PyPI does not allow replacing
+its uploaded distribution files. Use a new version for subsequent fixes.
+
+## One-time account setup
+
+Sign in to PyPI, then open [account publishing](https://pypi.org/manage/account/publishing/).
+Under **Add a new pending publisher**, select GitHub and enter:
+
+| Field | Value |
+| --- | --- |
+| PyPI project name | `mcp-event-subscriptions` |
+| Repository owner | `ChiragAgg5k` |
+| Repository name | `mcp-event-subscriptions` |
+| Workflow name | `publish.yml` |
+| Environment name | `pypi` |
+
+Click **Add**. This authorizes only the configured GitHub workflow/environment.
+No API token or GitHub secret is required. A pending publisher creates the PyPI
+project on its first successful upload; it does not reserve the name beforehand.
+The repository has a `pypi` GitHub environment matching the workflow.
+
+References: [PyPI pending publishers](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)
+and [publishing with a trusted publisher](https://docs.pypi.org/trusted-publishers/using-a-publisher/).
+
+## Release
+
+1. Update `project.version` in `pyproject.toml` for later releases, run `uv lock`,
+   and commit the result. For this first alpha the version is already correct.
+2. Wait for CI to pass for the intended release commit.
+3. Create a GitHub release with a tag matching the version, e.g. `v0.1.0a1`,
+   targeting that commit. Mark alpha releases as prereleases.
+4. Publish the GitHub release. `.github/workflows/publish.yml` validates the
+   tag/version match, runs checks, builds distributions, checks metadata and
+   tests the installed wheel before publishing through GitHub OIDC.
+5. Verify the project/version on PyPI and install from PyPI in a clean environment.
+
+The publishing job downloads only the built artifacts; it does not check out or
+execute repository code. OIDC permissions are limited to that job. Actions are
+pinned to commit hashes. Default PyPA upload attestations are enabled.
+
+## Retry a failed publishing run
+
+If the initial upload fails because the pending publisher was not configured,
+add it on PyPI, then rerun the failed job. Alternatively manually dispatch
+**Publish to PyPI** with the existing version tag. Do not rerun an already
+successful upload; published files cannot be overwritten.

mcp_event_subscriptions-0.1.0a1/SECURITY.md

@@ -0,0 +1,26 @@
+# Security
+
+This repository is experimental and has not received an independent security
+audit. Report security issues privately through GitHub's private vulnerability
+reporting when available; otherwise use Appwrite's published security reporting
+channel. Do not include production keys or subscription secrets in public issues.
+
+## Trust boundaries
+
+- Records contain sensitive callback signing secrets. Do not log plaintext,
+  envelopes, Authorization headers, or decrypted errors with payloads.
+- Use dedicated, random 256-bit encryption keys from a secret manager. Public
+  fixture keys are intentionally insecure and must never be deployed.
+- Expected envelope context must come from trusted server configuration and
+  authenticated adapter routing. A token cannot establish its own tenant scope.
+- A decrypted subscription does not prove present authorization or revocation
+  status. Adapters must implement those checks and callback verification.
+- Validate callback addresses at connection time, block internal destinations,
+  preserve TLS hostname verification, and do not follow redirects. This library
+  validates URL syntax only; it does not resolve DNS or perform outbound HTTP.
+- Expiry limits validity; it does not prevent replay before expiry. Concurrent
+  writes and stale cleanup require storage-level coordination.
+- No-expiry subscriptions need durable revocation and key migration mechanisms.
+
+The decoder limits token size, rejects duplicate keys/non-finite numbers, uses
+an algorithm allowlist, and never fetches keys referenced by an envelope.

mcp_event_subscriptions-0.1.0a1/SPEC.md

@@ -0,0 +1,89 @@
+# Subscription Record v1 — experimental draft
+
+This document defines an optional persistence representation for webhook
+subscriptions. It is independent of the MCP wire protocol. MUST, SHOULD, and
+MAY express requirements for implementations claiming this draft profile; they
+are not additional requirements imposed on all MCP servers.
+
+## Record
+
+A record MUST be a JSON object conforming to
+[`subscription-v1.schema.json`](schemas/subscription-v1.schema.json) and the
+semantic rules below. Unknown fields MUST be rejected outside `extensions`.
+JSON parsers MUST reject duplicate object keys and non-finite numbers.
+
+| Field | Meaning |
+| --- | --- |
+| `version` | Integer `1`; unsupported versions MUST be rejected. |
+| `id` | Nonempty, opaque subscription identifier scoped to its issuing server. |
+| `principal` | Nonempty, opaque canonical owner identifier. It MUST NOT contain bearer or refresh tokens. |
+| `event.name` | Event type advertised by the issuing server. |
+| `event.arguments` | JSON object; the adapter MUST validate it against that event's published input schema. |
+| `delivery.mode` | `webhook` in v1. |
+| `delivery.url` | Absolute HTTPS callback URL without user information or fragment. |
+| `delivery.secret` | `whsec_` followed by canonical padded standard base64 for 24–64 decoded bytes. |
+| `lease.expiresAt` | Actual expiry, or `null` for an explicitly granted no-expiry subscription. |
+| `lease.refreshBefore` | Suggested refresh deadline, or `null` together with `expiresAt`. |
+| `extensions` | Optional object with namespaced keys such as `io.appwrite.source`. |
+
+Timestamps MUST be UTC RFC 3339 strings using `Z`, with seconds and optionally
+1–6 fractional digits. A finite `refreshBefore` MUST be at or before `expiresAt`.
+At the expiry instant the subscription is expired. No-expiry records MUST have
+both lease fields set to `null`; granting them requires durable storage and an
+explicit no-expiry request at the protocol layer. The schema permits this
+representation; it does not grant such a lease by itself.
+
+Record validation is separate from activation. A stored record may be expired;
+a consumer MUST check expiry before using it for delivery. The reference
+`open_envelope` checks expiry by default.
+
+The record MUST contain JSON values only. The reference implementation limits
+encoded records and envelopes to 64 KiB each; adapters MAY impose lower limits.
+This draft has no compression profile.
+
+## Identity and authorization
+
+The adapter MUST preserve MCP's logical identity based on principal, callback,
+event name, and arguments. This draft does not prescribe a hash algorithm or
+identifier syntax. Importing a record MUST NOT grant access: the receiving
+server MUST establish tenant/resource ownership and current authorization.
+Principal identifiers are server-scoped; cross-server migration requires an
+explicit identity mapping and reauthorization, not merely copying JSON.
+
+## Extensions
+
+An extension key MUST have a reverse-domain namespace followed by a name,
+for example `io.appwrite.source`. Core consumers MAY preserve extensions they
+do not understand, but MUST NOT depend on them to establish security. A future
+required extension needs a new profile or version with explicit negotiation.
+
+## Storage and lifecycle
+
+This record is a snapshot. It is not proof that a subscription remains live.
+The storage adapter MUST define:
+
+1. An atomic upsert or coordination mechanism for concurrent refreshes.
+2. Conditional expiry cleanup, so a stale snapshot cannot delete a renewed lease.
+3. Revocation semantics and the treatment of deliveries already in flight.
+4. How callback secret changes coexist with retries signed using an old secret.
+5. Lease durability and recovery guarantees.
+
+A generation number alone provides no protection without compare-and-swap or
+equivalent enforcement. Version 1 deliberately has no unenforced revision field.
+The encrypted profile authenticates a snapshot but cannot prove its freshness.
+
+## Versioning
+
+Adding required fields, changing field meaning, or changing validation rules
+requires a new record version. Readers MUST reject unsupported versions rather
+than guessing. This experimental draft may change before a stable release.
+
+## Related work
+
+- [MCP Events design sketch](https://github.com/modelcontextprotocol/experimental-ext-triggers-events/blob/main/docs/design-sketch-proposal.md)
+- [SEP-3415 discussion](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/3415)
+- [JSON Schema](https://json-schema.org/draft/2020-12)
+
+The proposal's value is a reusable persistence representation and test suite;
+it does not claim that internal database schemas must be standardized for MCP
+clients and servers to interoperate.

mcp_event_subscriptions-0.1.0a1/examples/appwrite-webhook.json

@@ -0,0 +1,14 @@
+{
+  "webhookId": "sub_example",
+  "name": "MCP events | functions.execution.failed | until 2030-01-01T01:00:00Z | owner demo",
+  "url": "https://mcp.example.com/appwrite/webhooks/sub_example",
+  "events": [
+    "functions.fn_demo.executions.*.create",
+    "functions.fn_demo.executions.*.update"
+  ],
+  "enabled": true,
+  "tls": true,
+  "authUsername": "mcp-events",
+  "authPassword": "eyJhbGciOiJkaXIiLCJjdHkiOiJhcHBsaWNhdGlvbi9qc29uIiwiZW5jIjoiQTI1NkdDTSIsImtpZCI6ImZpeHR1cmUtazEiLCJ0eXAiOiJtY3Atc3Vic2NyaXB0aW9uK2p3ZSJ9..AAECAwQFBgcICQoL.PCC1dKuRp2P5Y63wk5sdHuyj9VeVWWVeSxKH2ngRYd9xfMveg-Nh_QbSGp-qvQpQmi0Q_mD5jLdc5wR8YIKYnpxZ6Bm8vARNPiDPAI7hesoCqLkQGQk2C4mi-qkVn5vw59oplMsnoXb7PgSQJRZRUskSANiAt0zqOZY4o6-DAHjePm-20fq9YirNatJIuD-hRJ2TQVx-_Wi2JMoTn76AmPbl5zfThO4TyAe42OWi8d7_pqVN4Ilfnha6o7UUsZXJMTviiWi-iYh2E5CnzRCfxoYdsTVsb_a1MKHVgzkJ3b8rboHptHlbYhAs2U_NZhgZwKuEV7ES_Nd7SV1R4-g28Wfr3b_vvytbHqkXdZlIQmu3xKaorujuwl5KGzRkgMlpfC_8LcygoGOwBkF4a-fHpvWvNSo6tvVsuldoePRJLIanyhZOqVpaj82_H0UwvD9OsWql6_Zx5nwWyhxEt5M4jTZFnLrxCxauTcCGXruXDEnpmD1DzJd1r_yRXbOyJHdX3eajrPNuvLKPFp8WUiV2pZ8nTt7nVDe6TnmxKD7EgS1kVnUCp_NrUNPNvg2agNHILQchMDChTICGyobPvNA9HQIKx6_LJP4JySDCZcGn5XxZu0Zi8s4uDXn1ioohz9yWNc1bZPHhur056GHrh96IoqqO46oOnswQhi-hbJPYYyaUWNDIj2v-Km2ZkQ9TfALR99NXGFRZosbmCyNexzVy7whqW-jOa5J9VaYkz6UBedd30uo.11BkPstaF5zWAYhg92Q1gA",
+  "secret": "PUBLIC-EXAMPLE-INDEPENDENT-APPWRITE-SIGNING-SECRET"
+}

mcp_event_subscriptions-0.1.0a1/examples/encrypted-subscription.txt

@@ -0,0 +1 @@
+eyJhbGciOiJkaXIiLCJjdHkiOiJhcHBsaWNhdGlvbi9qc29uIiwiZW5jIjoiQTI1NkdDTSIsImtpZCI6ImZpeHR1cmUtazEiLCJ0eXAiOiJtY3Atc3Vic2NyaXB0aW9uK2p3ZSJ9..AAECAwQFBgcICQoL.PCC1dKuRp2P5Y63wk5sdHuyj9VeVWWVeSxKH2ngRYd9xfMveg-Nh_QbSGp-qvQpQmi0Q_mD5jLdc5wR8YIKYnpxZ6Bm8vARNPiDPAI7hesoCqLkQGQk2C4mi-qkVn5vw59oplMsnoXb7PgSQJRZRUskSANiAt0zqOZY4o6-DAHjePm-20fq9YirNatJIuD-hRJ2TQVx-_Wi2JMoTn76AmPbl5zfThO4TyAe42OWi8d7_pqVN4Ilfnha6o7UUsZXJMTviiWi-iYh2E5CnzRCfxoYdsTVsb_a1MKHVgzkJ3b8rboHptHlbYhAs2U_NZhgZwKuEV7ES_Nd7SV1R4-g28Wfr3b_vvytbHqkXdZlIQmu3xKaorujuwl5KGzRkgMlpfC_8LcygoGOwBkF4a-fHpvWvNSo6tvVsuldoePRJLIanyhZOqVpaj82_H0UwvD9OsWql6_Zx5nwWyhxEt5M4jTZFnLrxCxauTcCGXruXDEnpmD1DzJd1r_yRXbOyJHdX3eajrPNuvLKPFp8WUiV2pZ8nTt7nVDe6TnmxKD7EgS1kVnUCp_NrUNPNvg2agNHILQchMDChTICGyobPvNA9HQIKx6_LJP4JySDCZcGn5XxZu0Zi8s4uDXn1ioohz9yWNc1bZPHhur056GHrh96IoqqO46oOnswQhi-hbJPYYyaUWNDIj2v-Km2ZkQ9TfALR99NXGFRZosbmCyNexzVy7whqW-jOa5J9VaYkz6UBedd30uo.11BkPstaF5zWAYhg92Q1gA

mcp_event_subscriptions-0.1.0a1/examples/roundtrip.py

@@ -0,0 +1,16 @@
+import json
+import secrets
+from pathlib import Path
+
+from mcp_event_subscriptions import open_envelope, seal
+
+record = json.loads(Path(__file__).with_name("subscription.json").read_text())
+keys = {"k1": secrets.token_bytes(32)}
+context = {
+    "server": "https://mcp.example.com",
+    "tenant": "project_demo",
+    "resource": record["id"],
+}
+token = seal(record, keys, active_key="k1", context=context)
+assert open_envelope(token, keys, expected_context=context) == record
+print("Subscription sealed and recovered successfully (secrets omitted).")

mcp_event_subscriptions-0.1.0a1/examples/subscription.json

@@ -0,0 +1,22 @@
+{
+  "version": 1,
+  "id": "sub_example",
+  "principal": "principal_demo",
+  "event": {
+    "name": "functions.execution.failed",
+    "arguments": {
+      "project_id": "project_demo",
+      "function_id": "fn_demo"
+    }
+  },
+  "delivery": {
+    "mode": "webhook",
+    "url": "https://receiver.example.com/events",
+    "secret": "whsec_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8="
+  },
+  "lease": {
+    "expiresAt": "2030-01-01T01:00:00Z",
+    "refreshBefore": "2030-01-01T00:54:00Z"
+  },
+  "extensions": {}
+}

mcp_event_subscriptions-0.1.0a1/packages/python/README.md

@@ -0,0 +1,20 @@
+# Python reference implementation
+
+The root `pyproject.toml` packages `packages/python/src/mcp_event_subscriptions`.
+Install locally with `uv sync` or `pip install .` from the repository root.
+
+```python
+validate_subscription(record)  # structural and semantic checks; returns a copy
+seal(record, keys, active_key="k1", context=context)
+open_envelope(token, keys, expected_context=context)  # also rejects expiry
+```
+
+`keys` maps key IDs to dedicated 32-byte keys. `context` contains exactly
+`server`, `tenant`, and `resource`. Opening uses the `kid` named in the protected
+header. Missing keys, tampering, invalid records and context mismatches raise
+`EnvelopeError`; expired records raise `ExpiredSubscription`. Invalid direct
+record input raises `RecordError`. Keys must be generated randomly by the caller.
+
+`open_envelope(..., now=datetime(..., tzinfo=UTC))` permits a supplied clock for
+fixtures; normal consumers should use the default current clock. The function
+does not contact the callback or check current upstream revocation state.