parcelapp-mcp 0.2.0__tar.gz

parcelapp_mcp-0.2.0/.dockerignore

@@ -0,0 +1,20 @@
+# Allowlist: exclude everything, then admit only what the build needs.
+#
+# Chosen over a blocklist because the set is five entries and stable, while
+# the working tree accumulates things that must never reach a build context:
+# .venv/, .omc/ state, .agent.lock, editor droppings. A blocklist protects
+# only against what someone remembered to list.
+#
+# Adding a source directory means adding its `!` line below.
+
+*
+
+!pyproject.toml
+!uv.lock
+!README.md
+!LICENSE
+!src/
+
+# Re-exclude what would otherwise ride along inside src/.
+**/__pycache__/
+**/*.py[co]

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

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# The test suite mocks the upstream API and needs no credentials: PARCEL_TOKEN
+# is set per-test by a fixture. Nothing here ever reaches api.parcel.app, which
+# matters because add_delivery is capped at 20 requests per day upstream.
+
+jobs:
+  lint:
+    name: Lint and type-check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # hatch-vcs reads the version from the nearest tag, and uv sync
+          # builds the project. A shallow clone has no tags and yields a
+          # meaningless 0.1.devN.
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+      - run: uv run mypy
+
+  test:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # hatch-vcs reads the version from the nearest tag, and uv sync
+          # builds the project. A shallow clone has no tags and yields a
+          # meaningless 0.1.devN.
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --locked
+      - run: uv run pytest

parcelapp_mcp-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,156 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+# One tag drives the whole release: PyPI, then the GitHub release, then the
+# changelog commit. It is deliberately not split across two workflows, because
+# a release created with the GITHUB_TOKEN does not trigger anything else --
+# GitHub suppresses that cascade on purpose -- so a `release: published` hook
+# would simply never fire.
+#
+# Publishing is irreversible: PyPI never lets a version number be reused, even
+# after a yank. So the build job runs the full check suite first, and only a
+# later job gets an OIDC token.
+
+permissions: {}
+
+jobs:
+  build:
+    name: Build and verify
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read # the workflow-level default is nothing, and checkout needs this
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # hatch-vcs reads the version from the nearest tag and git-cliff walks
+          # the history for the notes. A shallow checkout has neither, and would
+          # quietly produce a dev version instead of failing.
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+
+      - run: uv sync --locked
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+      - run: uv run mypy
+      - run: uv run pytest
+
+      - name: Build the sdist and the wheel
+        run: uv build
+
+      # With hatch-vcs the version is derived from the tag, so this normally
+      # agrees by construction. It stays because the ways it can disagree are
+      # exactly the ways hatch-vcs fails quietly: a shallow fetch, or a tag that
+      # is not on the commit being built, both of which yield a .devN version.
+      - name: Check the release tag against the built version
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          version="${TAG#v}"
+          if [ ! -f "dist/parcelapp_mcp-${version}.tar.gz" ]; then
+            echo "Tag ${TAG} implies version ${version}, but uv build produced:" >&2
+            ls -1 dist >&2
+            exit 1
+          fi
+
+      - name: Check the metadata renders on PyPI
+        run: uvx twine check --strict dist/*
+
+      # The same cliff.toml that generates CHANGELOG.md, so the release page and
+      # the file cannot drift. The leading "## <version> - <date>" heading is
+      # dropped: the release is already titled with its tag.
+      - name: Generate the release notes
+        run: |
+          # sed, in order: drop the leading "## <version> - <date>" heading,
+          # then drop the blank lines it leaves behind at the top.
+          uvx git-cliff --latest --strip all \
+            | sed -e '1{/^## /d;}' -e '/./,$!d' > release-notes.md
+          cat release-notes.md
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: release
+          path: |
+            dist/
+            release-notes.md
+          if-no-files-found: error
+
+  pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # Configured at https://pypi.org/manage/project/parcelapp-mcp/settings/publishing/
+    # as a GitHub publisher: obeone/parcelapp-mcp, workflow publish.yml,
+    # environment pypi. No API token lives in this repository.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/parcelapp-mcp
+    permissions:
+      id-token: write # mints the short-lived OIDC token Trusted Publishing exchanges
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: release
+      - uses: pypa/gh-action-pypi-publish@v1.14.2
+
+  release:
+    name: GitHub release and changelog
+    # Last on purpose: a release must not announce a package that failed to
+    # upload. The reverse order leaves a dangling release; this order at worst
+    # leaves a published package with no release notes, which is fixable.
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # creates the release and pushes the changelog commit
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # main, not the tag: the changelog commit belongs on the branch. The
+          # full history still gives git-cliff the tag it needs.
+          ref: main
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v10.0.1
+
+      - uses: actions/download-artifact@v8
+        with:
+          name: release
+          # Outside the checkout: the release notes are a build artifact, not
+          # something that should show up as an untracked file in the commit
+          # this job is about to make.
+          path: artifacts
+
+      - name: Create the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          gh release create "$TAG" \
+            --title "$TAG" \
+            --notes-file artifacts/release-notes.md \
+            artifacts/dist/*
+
+      # Regenerated rather than appended, so a reworded history stays reflected.
+      # The commit is a chore(release), which cliff.toml skips, so it never shows
+      # up in the next changelog.
+      - name: Update CHANGELOG.md on main
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          uvx git-cliff -o CHANGELOG.md
+          if git diff --quiet -- CHANGELOG.md; then
+            echo "CHANGELOG.md already up to date."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add CHANGELOG.md
+          git commit -m "chore(release): update the changelog for ${TAG}"
+          # main may have moved while the package was uploading.
+          git pull --rebase --autostash
+          git push

parcelapp_mcp-0.2.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+.agent.lock
+PROMPT.md
+.worktrees/

parcelapp_mcp-0.2.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+Generated from the Conventional Commits in the git history. Do not edit by
+hand: run `uvx git-cliff -o CHANGELOG.md` instead.
+
+## Unreleased
+
+### Features
+
+- Per-request API key, rate-limit budget, filtering and a resource
+- Containerise the HTTP transport
+
+### Bug fixes
+
+- Pin setup-uv to an existing ref
+
+### Refactoring
+
+- Adopt src layout, rename to parcelapp-mcp, move live scripts
+- Split the HTTP client out of the server module
+
+### Documentation
+
+- Add CLAUDE.md with architecture and rate-limit invariants
+- Add the MIT licence and rewrite the README for publication
+- Rewrite the README for the two transports
+- Record the HTTP-transport invariants in CLAUDE.md
+
+### Tests
+
+- Add a pytest suite mocking the upstream API with respx
+
+### Build and CI
+
+- Publish to PyPI on a released tag
+
+### Chores
+
+- Add ruff, strict mypy and a CI workflow
+- Untrack the design brief
+- Fill in the package, image and repository metadata
+

parcelapp_mcp-0.2.0/CLAUDE.md

@@ -0,0 +1,180 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+An MCP server wrapping the [Parcel](https://parcelapp.net) delivery-tracking API,
+which premium users of the macOS/iOS app get access to. Two upstream endpoints plus a
+public carrier-code list, exposed as three MCP tools and one resource template.
+
+It serves two transports. stdio reads the key from the environment. HTTP takes it
+per request, which turns process-global state into a leak and drives most of the
+design below.
+
+The upstream API is documented only by two help pages:
+
+- <https://parcelapp.net/help/api-view-deliveries.html>
+- <https://parcelapp.net/help/api-add-delivery.html>
+
+Anything beyond those pages is undocumented. When behaviour is unclear, handle it
+defensively and note the uncertainty in a comment rather than inventing a contract.
+
+`PROMPT.md` holds the original project brief (restructuring roadmap and feature
+backlog). Read it before starting work that touches project layout or scope.
+
+## Commands
+
+The project uses `uv`. The API key comes from `envchain parcel` locally.
+
+```bash
+uv sync                                       # install deps and the dev group
+uv run pytest                                 # 80 tests, no network
+uv run pytest tests/test_tools.py::test_add_delivery_demands_a_postcode_without_spending_a_request
+uv run ruff check && uv run ruff format       # lint, then format
+uv run mypy                                   # strict, and currently clean
+uvx git-cliff --unreleased                    # preview the next changelog section
+envchain parcel uv run parcelapp-mcp          # run the server over stdio
+envchain parcel uv run scripts/smoke_test.py  # live, read-only check (in-process)
+envchain parcel uv run scripts/stdio_test.py  # live, end-to-end MCP client over stdio
+envchain parcel uv run scripts/http_test.py   # live, against a running HTTP server
+docker build --build-arg VERSION=$(git describe --tags --abbrev=0 | sed s/^v//) \
+  -t parcelapp-mcp . && docker run -p 8000:8000 parcelapp-mcp
+```
+
+`uv run pytest` is the loop to work in: it never touches the network, so it costs
+nothing from either rate-limit budget. The two `scripts/` entries do hit the real API
+and are manual checks, not part of the suite.
+
+The suite mocks the upstream with `respx`. Every test runs under `@respx.mock`, so an
+unmocked request fails the test rather than escaping to the real API.
+
+CI (`.github/workflows/ci.yml`) runs those same three commands: lint and types once,
+tests across 3.10 to 3.13. It uses `uv sync --locked`, so a dependency change means
+committing the refreshed `uv.lock` alongside it.
+
+## Releasing
+
+A tag is the whole trigger. `git tag v0.3.0 && git push --tags` runs
+`.github/workflows/publish.yml`, which checks, builds, uploads to PyPI through
+Trusted Publishing (no API token in the repository), creates the GitHub release with
+generated notes, and commits the refreshed `CHANGELOG.md` back to `main`.
+
+Nothing is versioned by hand. `hatch-vcs` derives the version from the nearest git
+tag, which has three consequences worth knowing before debugging a wrong number:
+
+- **Every checkout that builds this package needs `fetch-depth: 0`.** A shallow clone
+  has no tags, so the build quietly produces a `0.1.devN` version instead of failing.
+  The build job's tag check exists to catch exactly that.
+- **A build with no `.git` at all fails outright.** `.dockerignore` keeps `.git` out of
+  the build context on purpose, so the Dockerfile passes the version in through
+  `--build-arg VERSION=…`, which it forwards as `SETUPTOOLS_SCM_PRETEND_VERSION`. A
+  `docker build` without that argument reports `0.0.0` rather than lying. Beware
+  the warm uv cache mount: it can hand back a wheel built under a previous
+  `VERSION`, so pass `--no-cache` when the number in the image actually matters.
+- **A dirty working tree taints the version** with a `.dYYYYMMDD` suffix. Harmless
+  locally, but it means a release must be built from a clean checkout.
+
+The changelog is generated from the Conventional Commits by `git-cliff`, configured in
+`cliff.toml`. The same config produces `CHANGELOG.md` and the body of each GitHub
+release, so the two cannot drift. Preview it locally with `uvx git-cliff --unreleased`.
+
+The workflow is deliberately one file rather than a `release.yml` feeding a
+`publish.yml`: GitHub suppresses the event cascade from anything the `GITHUB_TOKEN`
+creates, so a release made by CI would never fire a `release: published` trigger.
+
+## Rate limits drive everything
+
+| Endpoint | Limit |
+| --- | --- |
+| `deliveries/` | 20 per hour |
+| `add-delivery/` | 20 per **day**, failed attempts included |
+| `supported_carriers.json` | none |
+
+Two consequences the code depends on:
+
+- **`add_delivery` validates locally before touching the network.** It checks the
+  carrier code against the cached carrier list and enforces the carrier's
+  `extra_required` field (postcode or email) *before* issuing the POST. A
+  preventable error must never consume one of the 20 daily requests.
+- **`add_delivery` must not be called live during development.** Test it against a
+  mock. `smoke_test.py` deliberately never touches it; `stdio_test.py` only exercises
+  the local guard rails, which fail before any request is sent.
+
+## Architecture
+
+Two modules, split along one line: `client.py` knows nothing about MCP, `server.py`
+knows nothing about HTTP. Resist adding a third for three tools.
+
+`src/parcel_mcp/client.py` — the network:
+
+- `request()` is the single HTTP chokepoint. It injects the `api-key` header,
+  maps 401 and 429 to explicit messages, and unwraps the upstream
+  `{"success": bool, "error_message": str}` envelope. Every upstream failure mode is
+  normalised here, so tools never inspect status codes themselves.
+- `_cache` is a module-level `dict[str, tuple[float, Any]]`, with per-call TTLs via
+  `cached()` / `store()` and eviction via `clear_cache()`. Deliveries: 180 s (upstream
+  serves a cached view anyway, so this costs no freshness and protects the hourly
+  budget). Carriers: 24 h. It is process-global state, so tests must call
+  `clear_cache()` between cases.
+- `_requests` holds the rate-limit counters, per bucket and per caller, pruned on
+  read. `clear_rate_limits()` resets them for tests.
+- `ParcelError` lives here, next to what raises it, though it reaches into the SDK.
+  See the invariant below.
+
+`src/parcel_mcp/server.py` — the MCP surface:
+
+- The `MCPServer` instance, the three tools, the resource template, the argparse
+  transport selection, `main()`.
+- `resolve_api_key(ctx)` decides where the key comes from: an `X-Parcel-Token` or
+  `Authorization: Bearer` header first, the environment as fallback. That fallback
+  is what lets one code path serve both transports.
+- The two translation tables, `STATUS_CODES` and `EXTRA_REQUIRED`, exist because the
+  upstream API speaks in integers. Resolving them, along with carrier codes to names,
+  is the entire value this server adds. Do not strip it in favour of raw passthrough.
+- `add_delivery`'s local validation stays here, beside the error messages it produces.
+
+### Non-obvious invariants
+
+- **`ParcelError` subclasses the SDK's `ToolError`.** If it does not, mcp 2.x
+  replaces the message with a generic "Error executing tool" and the model learns
+  nothing. Do not reparent it to `Exception`.
+- **mcp 2.x API: `MCPServer`, not `FastMCP`.** The v1 spelling is gone. Do not
+  reintroduce it from memory; check the installed version (`mcp` 2.1.x) when unsure.
+- **Docstrings are the tool contracts.** They are the text the model actually reads.
+  Keep them describing behaviour, arguments and rate limits, not implementation.
+- **Errors name the fix.** "Bpost requires a postcode; pass `postcode`" beats
+  "invalid request". Any new error path follows that shape.
+- `carrier_name()` swallows `ParcelError` and falls back to the raw code, so a
+  carrier-list fetch failure degrades `list_deliveries` instead of breaking it.
+- **`@mcp.tool()` returns the function unchanged.** It registers and hands back `fn`,
+  so tests and scripts can call `list_deliveries(...)` directly without going through
+  `mcp.call_tool`.
+- **`ToolAnnotations` fields are snake_case in Python.** `read_only_hint`, not
+  `readOnlyHint`. The camelCase spelling is the wire alias; pydantic accepts it, but
+  mypy cannot check it. The serialised JSON is identical either way.
+- **Everything cached or counted is keyed by `key_fingerprint(key)`.** Over HTTP one
+  process serves several people; an unpartitioned cache would hand one caller's
+  parcels to another. The carrier catalogue is the deliberate exception, being
+  public. Never introduce a cache key without the fingerprint in it.
+- **`ctx: Context | None = None`, never a bare `Context`.** The SDK unwraps the union
+  and still injects it, while the default keeps the tools directly callable from the
+  tests and scripts. Verified, not assumed.
+- **A static resource cannot receive a `Context`.** The SDK refuses it outright, which
+  is why `parcel://deliveries/{filter_mode}` is a URI template: only templated
+  resources get a context, and without one a resource cannot read a per-request key.
+- **The client factory is `streamable_http_client`, and headers go through an
+  `httpx2.AsyncClient` passed as `http_client`.** Not `streamablehttp_client`, and not
+  a `headers=` argument; both are v1 spellings that no longer exist.
+
+## Auth
+
+`PARCEL_TOKEN`, falling back to `PARCEL_API_KEY`, sent as the `api-key` header. Keys
+are generated at <https://web.parcelapp.net>. Never put a realistic-looking key in a
+test fixture.
+
+## Dependencies
+
+Standard library plus `httpx` and `mcp`. Justify any third dependency before adding
+it; `respx` or `httpx.MockTransport` for the future test suite is the expected
+exception.

parcelapp_mcp-0.2.0/Dockerfile

@@ -0,0 +1,72 @@
+# syntax=docker/dockerfile:1
+
+# Serves the streamable-http transport. No credential is baked in or expected
+# at runtime: each request carries its own Parcel key in an X-Parcel-Token or
+# Authorization: Bearer header, so one container can serve several people.
+
+FROM python:3.13-slim
+
+# uv is pinned like any other dependency.
+COPY --from=ghcr.io/astral-sh/uv:0.12.9 /uv /uvx /bin/
+
+WORKDIR /app
+
+# Created first: a --chown naming a user this stage does not know yet is
+# silently dropped, and the files land as root.
+RUN groupadd -r -g 10001 app && useradd -r -u 10001 -g app app
+
+# Dependencies as root, in their own cached layer. /app/.venv stays root-owned
+# on purpose: the app runs it but cannot rewrite it.
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --locked --no-install-project --no-dev
+
+# The package version comes from the nearest git tag, but .dockerignore keeps
+# .git out of the build context on purpose, so hatchling cannot read it here.
+# This ARG is the only way in, and a build without it honestly reports 0.0.0
+# rather than a stale hardcoded number:
+#   docker build --build-arg VERSION=$(git describe --tags --abbrev=0 | sed s/^v//) .
+# It feeds both the install below and the OCI label at the end of this stage.
+ARG VERSION=0.0.0
+
+COPY --chown=app:app . .
+RUN --mount=type=cache,target=/root/.cache/uv \
+    SETUPTOOLS_SCM_PRETEND_VERSION=${VERSION} uv sync --locked --no-dev
+
+# Hand over the workdir, not the dependency tree, then drop privileges last.
+RUN chown app:app /app
+USER app
+
+ENV PATH="/app/.venv/bin:$PATH" \
+    PARCEL_TRANSPORT=streamable-http \
+    PARCEL_HOST=0.0.0.0 \
+    PARCEL_PORT=8000 \
+    PARCEL_PATH=/mcp
+
+EXPOSE 8000
+
+LABEL org.opencontainers.image.title="parcelapp-mcp" \
+      org.opencontainers.image.description="MCP server for the Parcel delivery tracking app: read and add deliveries over stdio or HTTP" \
+      org.opencontainers.image.source="https://github.com/obeone/parcelapp-mcp" \
+      org.opencontainers.image.documentation="https://github.com/obeone/parcelapp-mcp#readme" \
+      org.opencontainers.image.url="https://github.com/obeone/parcelapp-mcp" \
+      org.opencontainers.image.authors="Grégoire Compagnon <obeone@obeone.org>" \
+      org.opencontainers.image.licenses="MIT" \
+      org.opencontainers.image.version="${VERSION}"
+
+# There is no /health endpoint, and a GET on /mcp opens an SSE stream that
+# never returns, so neither would work. This performs a real MCP initialize
+# handshake instead: it proves the session manager and the tool registry are
+# alive, not merely that a socket is open. urlopen raises on a non-2xx, and the
+# assert catches a 200 that is not a protocol response.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD python -c "import json,urllib.request as u; \
+r=u.Request('http://127.0.0.1:8000/mcp', \
+data=json.dumps({'jsonrpc':'2.0','id':1,'method':'initialize','params':{'protocolVersion':'2025-06-18','capabilities':{},'clientInfo':{'name':'healthcheck','version':'0'}}}).encode(), \
+headers={'Content-Type':'application/json','Accept':'application/json, text/event-stream'}); \
+assert b'\"result\"' in u.urlopen(r, timeout=4).read()" || exit 1
+
+# Exec form, so the server is PID 1 and receives SIGTERM directly. uvicorn
+# installs its own handler and drains, so no init shim is needed.
+CMD ["parcelapp-mcp"]

parcelapp_mcp-0.2.0/LICENSE

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