handle-mcp 1.5.1__tar.gz

handle_mcp-1.5.1/.github/FUNDING.yml

@@ -0,0 +1,2 @@
+github: NJohansen
+buy_me_a_coffee: niclasjohansen

handle_mcp-1.5.1/.github/badges/make.py

@@ -0,0 +1,40 @@
+"""Write clones.json, the shields.io endpoint for the README clones badge.
+
+Reads traffic.json (GitHub API answer) and clones-history.json.
+GitHub keeps traffic for 14 days only. The history keeps the days the API still
+shows, plus one sum for all older days, so no daily numbers older than 14 days are public.
+"""
+
+import json
+import pathlib
+
+
+def update(saved: dict, traffic: dict) -> tuple[dict, dict]:
+    """Merge one traffic answer into the history. Returns (history, badge)."""
+    days = dict(saved["days"])
+    before = saved["before"]
+    fresh = {d["timestamp"][:10]: d["uniques"] for d in traffic["clones"]}
+    if fresh:
+        days.update(fresh)
+        first = min(fresh)
+        before += sum(n for day, n in days.items() if day < first)
+        days = {day: n for day, n in days.items() if day >= first}
+    days = dict(sorted(days.items()))
+    total = before + sum(days.values())
+    message = f"{total / 1000:.1f}k".replace(".0k", "k") if total >= 1000 else str(total)
+    badge = {"schemaVersion": 1, "label": "clones", "message": message, "color": "brightgreen"}
+    return {"before": before, "days": days}, badge
+
+
+def main() -> None:
+    history = pathlib.Path("clones-history.json")
+    saved = json.loads(history.read_text()) if history.exists() else {"before": 0, "days": {}}
+    traffic = json.loads(pathlib.Path("traffic.json").read_text())
+    new, badge = update(saved, traffic)
+    history.write_text(json.dumps(new, indent=1) + "\n")
+    pathlib.Path("clones.json").write_text(json.dumps(badge) + "\n")
+    print(f"{badge['message']} clones")
+
+
+if __name__ == "__main__":
+    main()

handle_mcp-1.5.1/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly

handle_mcp-1.5.1/.github/workflows/badges.yml

@@ -0,0 +1,72 @@
+name: badges
+# The README clones badge: shields.io reads clones.json on the `badges` branch.
+# GitHub keeps traffic for 14 days only, so each run saves the days it sees.
+#
+# Needs secret TRAFFIC_TOKEN in the environment `badges` (Settings > Environments,
+# deployment branches: main only). A fine-grained token for this repo only,
+# "Administration: read", with an expiry date. The traffic API needs it;
+# GITHUB_TOKEN cannot get it. Never runs on pull requests, so forks never see it.
+on:
+  schedule:
+    - cron: "17 3 * * *"
+  workflow_dispatch:
+permissions: {}
+concurrency:
+  group: badges
+jobs:
+  fetch:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    environment: badges
+    permissions: {}
+    steps:
+      - name: Fetch the clone counts
+        env:
+          GH_TOKEN: ${{ secrets.TRAFFIC_TOKEN }}
+          REPO: ${{ github.repository }}
+        run: |
+          if [ -z "$GH_TOKEN" ]; then
+            echo "::error::Secret TRAFFIC_TOKEN is not set in the environment 'badges'."
+            exit 1
+          fi
+          gh api "repos/$REPO/traffic/clones" > traffic.json
+      - uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        with:
+          name: traffic
+          path: traffic.json
+          retention-days: 1
+  write:
+    needs: fetch
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write  # push to the badges branch only; main is protected
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        with:
+          name: traffic
+          path: ${{ runner.temp }}
+      - name: Switch to the badges branch
+        run: |
+          cp .github/badges/make.py "$RUNNER_TEMP/make.py"
+          if git fetch -q --depth 1 origin badges; then
+            git checkout -q -B badges FETCH_HEAD
+          else  # first run
+            git checkout -q --orphan badges
+            git rm -rq --cached .
+            git clean -fdq
+          fi
+      - name: Write the badge
+        run: |
+          cp "$RUNNER_TEMP/traffic.json" .
+          python3 -I "$RUNNER_TEMP/make.py"
+          rm traffic.json
+      - name: Commit to the badges branch
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add clones.json clones-history.json
+          git diff --cached --quiet && exit 0
+          git commit -qm "Update clone count"
+          git push origin HEAD:badges

handle_mcp-1.5.1/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --python 3.12
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pytest -q

handle_mcp-1.5.1/.github/workflows/claude-review.yml

@@ -0,0 +1,67 @@
+name: claude-review
+# A fresh Claude reviews every PR. It has no memory of the session that wrote the code.
+on:
+  pull_request:
+    types: [opened, synchronize, ready_for_review, reopened]
+
+concurrency:
+  group: claude-review-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  review:
+    # Only PRs from this repo: forks and Dependabot get no secrets, so the job would fail.
+    # Skip drafts.
+    if: |
+      github.event.pull_request.draft == false &&
+      github.actor != 'dependabot[bot]' &&
+      github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+      id-token: write  # the action trades this for its GitHub App token
+      actions: read
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 1
+      - uses: anthropics/claude-code-action@c0949c50a78c1ec8ce2647db36629b870e715d0c # v1.0.268
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          track_progress: true
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            You review this pull request. You did not write it. Be skeptical.
+            Read CLAUDE.md and docs/adr/ first. Then read the full diff.
+
+            Block the PR (say "BLOCKER") if any of these break:
+            1. The human always pays. No code may place an order, pay, read cards,
+               choose a delivery time or change the address. No new store endpoint
+               outside search, product, cart quantity and read-only delivery slots.
+            2. Privacy. Every tool answer goes through privacy.scrub() in server._out().
+               No name, address, phone, email or raw store JSON leaves the server,
+               also not in logs, errors or test fixtures.
+            3. stdout is JSON-RPC. No print(). Logs go to stderr via logging.
+            4. No secrets in git: no tokens, passwords, cookies or real personal data.
+            5. One adapter per store in src/handle_mcp/stores/. A new store must not
+               need changes in server.py. One failing store must not stop the others.
+            6. Money is Decimal DKK. Bilka øre are converted in the adapter.
+            7. Tests use no network and no logins (except tests marked live).
+
+            Then look for real bugs: wrong logic, missing error handling, retries on
+            the wrong errors (only timeout, 429 and 5xx), missing tests for new code.
+            Skip style nits that ruff catches.
+
+            Output:
+            - Inline comments on the exact lines (mcp__github_inline_comment__create_inline_comment).
+            - One short top comment with `gh pr comment`: verdict (OK / changes needed /
+              BLOCKER), then max 5 bullets. Short sentences. No praise, no filler.
+            - Do not add any footer or attribution.
+
+          claude_args: |
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Read,Glob,Grep"

handle_mcp-1.5.1/.github/workflows/claude.yml

@@ -0,0 +1,38 @@
+name: claude
+# Write @claude in a PR or issue comment to ask a question or request a change.
+# Never on a PR from a fork: the workspace holds the PR's code, which may hold
+# instructions meant for the agent, and the agent can push.
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    # Only the repo owner can call @claude.
+    if: |
+      github.actor == 'NJohansen' && (
+        (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+        (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+        (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude'))
+      )
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      id-token: write  # the action trades this for its GitHub App token
+      actions: read
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 1
+      - uses: anthropics/claude-code-action@c0949c50a78c1ec8ce2647db36629b870e715d0c # v1.0.268
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          additional_permissions: |
+            actions: read

handle_mcp-1.5.1/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: release
+# Publishes to PyPI when a version tag (vX.Y.Z) is pushed.
+# Trusted Publishing: PyPI trusts this workflow in the `pypi` environment,
+# so no PyPI token is stored in GitHub.
+on:
+  push:
+    tags: ["v[0-9]+.[0-9]+.[0-9]+"]
+permissions: {}
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - name: Tag must be on main
+        run: git merge-base --is-ancestor "$GITHUB_SHA" origin/main
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          version: "0.11.32"
+      - name: Tag must match the version in pyproject.toml
+        run: |
+          version=$(uv version --short)
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match version $version" >&2
+            exit 1
+          fi
+      - run: uv sync --python 3.12
+      - run: uv run pytest -q
+      - run: uv build
+      - uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/handle-mcp
+    permissions:
+      id-token: write  # Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

handle_mcp-1.5.1/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+
+# Secrets and local state: never commit logins or sessions
+.env
+.env.*
+*.secret.json
+config/*.json
+captures/
+
+# OS / editors
+.DS_Store
+.idea/
+.vscode/

handle_mcp-1.5.1/CLAUDE.md

@@ -0,0 +1,117 @@
+# handle-mcp
+
+A local MCP server (stdio) for Danish grocery stores with home delivery. Goal and roadmap: the README. Findings about the stores: `docs/research.md`. How to contribute: `CONTRIBUTING.md`.
+
+## Rules (never break)
+
+1. **The human always pays.** No code may order, pay, read cards, choose a delivery time or change the address. See `docs/adr/0001-the-human-always-pays.md`. `tests/test_safety.py` greps for forbidden endpoints.
+2. **Privacy first.** Every tool answer goes through `privacy.scrub()` in `server._out()`. Never return raw store JSON without it.
+3. **stdout is JSON-RPC.** Never `print()`. Log to stderr with `logging`.
+4. **No secrets in git.** Logins only in env vars, the OS keychain (`handle-mcp login <store>`) or `~/.config/handle-mcp/<store>.json` (chmod 600).
+5. **Small and boring.** < ~550 lines per store file, < ~300 in every other file. No layer until two real users need it. A store that grows past the limit splits into mixins, `stores/<store>_<topic>.py`, never into a second layer.
+6. **No Claude attribution** in commits, PRs or comments.
+
+## Layout
+
+```
+src/handle_mcp/
+  server.py        all tools, store selection, error handling
+  cli.py           `handle-mcp` entry: stdio server or `login <store>` (logins into the OS keychain)
+  compare.py       compare_basket: best product per item, cheapest store
+  candidates.py    the products per item the caller picks from, with flags
+  match.py         words: does this product match the item?
+  pricing.py       kroner: packs for the amount, offers, delivery day
+  recipe_cart.py   add_recipe_to_cart: a recipe's products as absolute cart counts
+  links.py         with_utm(): UTM tags on every cart link the human clicks
+  telemetry.py     anonymous counts (server_started, first_tool_call, login_ok, cart_filled); off with HANDLE_TELEMETRY=0
+  models.py        dataclasses; money is Decimal DKK
+  privacy.py       scrub(): removes personal data
+  stores/__init__.py  Store protocol, StoreError, load_login(), STORES
+  stores/_http.py     one request with the retries every store needs
+  stores/<store>.py   one file per store: login, calls and parsing for that store
+  stores/<store>_<topic>.py  mixins when a store outgrows one file (nemlig_offers, nemlig_recipes, nemlig_delivery)
+tests/             no network, no logins
+tests/snapshots/tools.json  every tool as the model sees it (name, description, args)
+docs/adr/          one short file per hard decision
+docs/tools.md      the tool table users read: stores per tool, what writes
+```
+
+## Language
+
+- Code, comments, docs, commits and PRs: English.
+- Everything a human reads in a tool answer or error: Danish. `StoreError("nemlig.com har kø lige nu.")`.
+- Product names, offer texts and store messages pass through as the store wrote them (after `privacy.scrub()`).
+
+## Tools
+
+- Every tool has annotations: `READ`, `WRITE` (absolute cart quantities) or `ADD` (adds to the cart). Nothing else.
+- Every write tool says "Never orders or pays" in its description. A tool that adds to the cart says "ASK THE HUMAN FIRST". The tool never asks; the model does.
+- A tool that works in one store says so in its description and in `docs/tools.md`.
+- `tests/snapshots/tools.json` is the contract. A change to a tool's name, description or args is on purpose, in its own commit, with `HANDLE_UPDATE_SNAPSHOT=1`.
+- Tool answers are small, readable JSON: money as strings in kroner with two decimals (`"12.95"`, `"39.00"`, never `"39"` or `"0.0"`; `privacy.jsonable()` formats every Decimal, see `docs/adr/0002-money-has-two-decimals.md`), dates ISO, no raw store fields. A missing fact is `null` with a reason next to it, not a guess.
+- A new rule or a changed one gets a short ADR in `docs/adr/`.
+
+## Add a store
+
+1. Create `src/handle_mcp/stores/<name>.py` with a class that has every method in `stores.Store`.
+2. Raise `StoreError("clear Danish message")` for expected failures. Raise `NotImplementedError` if the store cannot do something.
+3. Add one line to `STORES` in `stores/__init__.py`.
+4. Tests: fixtures in `tests/fixtures/<name>/` are real answers with personal data replaced. Mock HTTP with `httpx.MockTransport`.
+
+No change to `server.py` or the tools is needed.
+
+## Store API lessons (see docs/research.md)
+
+- Money from stores may be in øre (Bilka). Convert to Decimal kroner in the adapter.
+- Quantities are absolute; 0 removes the line.
+- Bilka answers HTTP 200 on errors. A cart change failed if the applied count differs from the requested one.
+- Bilka: log in without a `cart` cookie, or the login replaces the cart.
+- Retry only on timeout, network errors (e.g. ReadError), 429 and 5xx. Safe because every write sets an absolute quantity.
+- nemlig: the front page and `?GetAsJson=1` land in queue-it. Use `/webapi/` and the productbff API. Never work around a queue or a bot check: raise a clear StoreError and let the human wait.
+- Fixtures are real captures with personal data replaced. `tests/fixtures/<store>/README.md` says what was captured and when, so a stale fixture is easy to spot.
+
+## Test
+
+```
+uv sync
+uv run pytest -q          # unit tests, no network
+HANDLE_UPDATE_SNAPSHOT=1 uv run pytest tests/test_protocol.py   # after changing a tool's name, description or args on purpose
+uv run ruff check . && uv run ruff format --check .
+HANDLE_LIVE=1 uv run pytest -m live   # read-only smoke tests against real stores (from step 3)
+HANDLE_LIVE=1 uv run pytest -m live -s tests/test_live_list.py   # 50 fixed items (tests/live_list.json): fails when no candidate fits
+```
+
+## Workflow
+
+One PR per change. Run the tests before you push, show the result, wait for OK.
+
+- A change that touches a store file: run the live tests for that store before merge. Stores change without notice.
+- A change to the matcher (`match.py`, `pricing.py`, `candidates.py`): run the live list before merge.
+- A new tool or a changed one: update `docs/tools.md` and the snapshot in the same PR.
+- Squash and merge. The squash message is the PR title.
+
+## Release
+
+1. Bump `version` in `pyproject.toml` (`uv lock` follows) and every pin: `grep -rn "handle-mcp@" README.md docs/` (README, `docs/setup.md`, `docs/security.md`). The website lives in [NJohansen/handlemcp.dk](https://github.com/NJohansen/handlemcp.dk): bump its pin in `index.html` there too.
+2. Merge, then tag the merge commit on `main`: `git fetch origin main && git tag vX.Y.Z origin/main && git push origin vX.Y.Z`. The tag runs `.github/workflows/release.yml`: tests, build, publish to PyPI (Trusted Publishing, environment `pypi`). It fails if the tag and `version` differ.
+3. Semver: a tool's args or answer shape changes in a way old skills notice → major. New tool or field → minor. Fix → patch.
+
+## Branches, commits and PRs (gitmoji)
+
+Branch name = type + short slug. The type says what the branch solves:
+
+| Type | Gitmoji | Use for |
+|---|---|---|
+| `feature/` | ✨ | new tool, store or behaviour |
+| `fix/` | 🐛 | bug fix |
+| `hotfix/` | 🚑️ | urgent fix on main |
+| `refactor/` | ♻️ | same behaviour, better code |
+| `docs/` | 📝 | docs only |
+| `test/` | ✅ | tests only |
+| `chore/` | 🔧 | config, CI, dependencies |
+
+Example: branch `feature/compare-basket`, PR title `✨ Compare a basket across stores`.
+
+- Start every commit message and PR title with the gitmoji ([gitmoji.dev](https://gitmoji.dev)).
+- No emoji in branch names: they break shells and URLs. The prefix is enough.
+- One type per branch. Split mixed work into two branches.

handle_mcp-1.5.1/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing
+
+Small and boring wins. Read `CLAUDE.md` first: the six rules, the layout and how to add a store.
+
+## Setup
+
+```sh
+uv sync
+uv run pytest -q                                   # no network, no logins
+uv run ruff check . && uv run ruff format --check .
+```
+
+Live tests (`HANDLE_LIVE=1 uv run pytest -m live -s`) call the real stores with **your own** accounts, saved with `handle-mcp login <store>`. They only read. CI never runs them.
+
+## Add a store
+
+1. Create `src/handle_mcp/stores/<name>.py` with a class that has every method in `stores.Store`.
+2. Raise `StoreError("clear Danish message")` for expected failures, `NotImplementedError` for what the store cannot do.
+3. Add one line to `STORES` in `src/handle_mcp/stores/__init__.py`.
+4. Tests: real, redacted answers in `tests/fixtures/<name>/`, HTTP mocked with `httpx.MockTransport`.
+
+No change to `server.py` or the tools. Store facts: [docs/research.md](docs/research.md).
+
+## Pull requests
+
+- Branch: `<type>/<slug>`, type is one of `feature`, `fix`, `hotfix`, `refactor`, `docs`, `test`, `chore`. One type per branch.
+- Commit messages and PR title start with the matching gitmoji (✨ 🐛 🚑️ ♻️ 📝 ✅ 🔧).
+- Tests for new code. HTTP is mocked with `httpx.MockTransport`.
+- Fixtures are real store answers with personal data replaced. Say so in `tests/fixtures/<store>/README.md`. Never commit a login, a cookie, a token or a real name, address, phone or email.
+- A Claude review runs on PRs from this repo. It is a second pair of eyes, not the decision.
+
+## Never
+
+- An endpoint that orders, pays, reads cards, chooses a delivery time or changes the address. `tests/test_safety.py` fails if one appears.
+- `print()`. stdout is the MCP stream. Log to stderr with `logging`.
+- Raw store JSON in a tool answer. Everything goes through `privacy.scrub()`.

handle_mcp-1.5.1/CREDITS.md

@@ -0,0 +1,8 @@
+# Credits
+
+Built on what these projects found out. Thank you.
+
+- [eisbaw/nemlig_cli](https://github.com/eisbaw/nemlig_cli): the nemlig.com API map (`nemlig_api.md`). MIT.
+- [kraenhansen/nemlig-mcp](https://github.com/kraenhansen/nemlig-mcp): nemlig MCP server and the privacy-marker idea. MIT.
+- [nickknissen/bilkatogo](https://github.com/nickknissen/bilkatogo): BilkaToGo login, cart and order flow, and the test fixtures in `tests/fixtures/bilkatogo/`. MIT, Copyright (c) 2026 Nick Nissen.
+- [stigvoss/bilkatogo-mcp](https://github.com/stigvoss/bilkatogo-mcp): read for facts about BilkaToGo. No code copied.

handle_mcp-1.5.1/LICENSE

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

handle_mcp-1.5.1/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.5
+Name: handle-mcp
+Version: 1.5.1
+Summary: MCP server for Danish grocery delivery: search, cart and price comparison. You always pay yourself.
+Project-URL: Homepage, https://handlemcp.dk
+Project-URL: Source, https://github.com/NJohansen/handle-mcp
+Project-URL: Issues, https://github.com/NJohansen/handle-mcp/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=25
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: tzdata>=2024.1
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="docs/hero.svg" alt="Give AI a budget, fill it cheaply, you pay and they deliver, unpack the week, enjoy dinner" width="800">
+
+# handle-mcp
+
+<a href="https://github.com/NJohansen/handle-mcp/stargazers"><picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/github/NJohansen/handle-mcp/stars.svg?mode=dark"><img src="https://shieldcn.dev/github/NJohansen/handle-mcp/stars.svg?mode=light" alt="GitHub stars"></picture></a>
+<a href="https://github.com/NJohansen/handle-mcp/graphs/traffic"><picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/badge/dynamic/json.svg?url=https%3A%2F%2Fraw.githubusercontent.com%2FNJohansen%2Fhandle-mcp%2Fbadges%2Fclones.json&query=%24.message&label=clones&mode=dark"><img src="https://shieldcn.dev/badge/dynamic/json.svg?url=https%3A%2F%2Fraw.githubusercontent.com%2FNJohansen%2Fhandle-mcp%2Fbadges%2Fclones.json&query=%24.message&label=clones&mode=light" alt="git clones"></picture></a>
+<a href="https://pypi.org/project/handle-mcp/"><picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/pypi/handle-mcp.svg?mode=dark"><img src="https://shieldcn.dev/pypi/handle-mcp.svg?mode=light" alt="PyPI version"></picture></a>
+<a href="LICENSE"><picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/badge/license-MIT-blue.svg?mode=dark"><img src="https://shieldcn.dev/badge/license-MIT-blue.svg?mode=light" alt="license MIT"></picture></a>
+<br>
+<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/badge/platforms-macOS_%7C_Windows_%7C_Linux-blue.svg?mode=dark"><img src="https://shieldcn.dev/badge/platforms-macOS_%7C_Windows_%7C_Linux-blue.svg?mode=light" alt="macOS, Windows, Linux"></picture>
+
+**Your AI agent fills the cheapest cart at [nemlig.com](https://www.nemlig.com) and [BilkaToGo](https://www.bilkatogo.dk). You pay.**<br>
+An MCP server: it reads the offers, plans the week on your budget and compares both stores.
+
+**[Install →](#install)** · [handlemcp.dk](https://handlemcp.dk)
+
+</div>
+
+**It can never order or pay. You do.** That code does not exist, and a test fails if it shows up ([why](docs/adr/0001-the-human-always-pays.md)).
+
+**It counts anonymous usage, and tells you so.** No id, no personal data. Off with `HANDLE_TELEMETRY=0`. [Exactly what is sent](#brugsstatistik).
+
+## How it works
+
+1. **Plan.** Give your agent a budget. It reads this week's offers on nemlig.com and BilkaToGo, and both stores' recipes, and plans the meals around them.
+2. **Compare.** It prices the whole list in both stores: pack sizes, offers, delivery fee and minimum order.
+3. **Fill.** It puts the list in the cheapest store's cart, with your login. Only the cart, nothing else.
+4. **Pay.** You open nemlig.com or BilkaToGo, check the cart, pick a delivery time and pay.
+
+Taste, budget and meal rules live in your own prompt or skill. The server finds and counts. [Build your own skill](docs/skills.md).
+
+## Requirements
+
+- macOS, Linux or Windows (x64). Windows on ARM is not supported yet: a dependency (`cryptography`) has no ready-made build for it.
+- [uv](https://docs.astral.sh/uv/). It fetches Python 3.12+ if you do not have it.
+- An MCP client, Grok, Claude Code, Claude Desktop or Codex etc.
+- An account at nemlig.com or BilkaToGo with home delivery to your address.
+
+## Install
+
+```sh
+uvx handle-mcp@1.5.1 login nemlig
+claude mcp add handle -- uvx handle-mcp@1.5.1
+```
+
+Then ask:
+
+- *"Plan 5 dinners for 4 within 900 kr, built on this week's offers. Fill the cheapest cart."*
+- *"What is on offer this week? Any free gifts?"*
+- *"Which delivery times are cheapest tomorrow?"*
+
+BilkaToGo, Claude Desktop, headless machines and AI agents (`handle-mcp login <store> --from-env`): [setup](docs/setup.md). nemlig's offers work with no login at all. No terminal? [Join the waitlist](https://handlemcp.dk).
+
+## Tools
+
+| Tool | Writes? | What |
+|---|---|---|
+| `search_products` | no | Price, price per kg/l, offers |
+| `search_recipes` | no | The store's recipes (nemlig) |
+| `list_recipes` | no | Featured recipes (BilkaToGo: the week's madplan), by tag (nemlig) or by category (BilkaToGo) |
+| `get_recipe` | no | The products to buy for a recipe, for any number of persons |
+| `list_offers` | no | This week's offers and free gifts |
+| `compare_basket` | no | Prices a list in every store, fees included, cheapest first |
+| `get_cart` | no | Cart lines, fees, total, in one store or every store |
+| `set_cart_quantities` | **yes** | Sets quantities in the cart. Nothing else |
+| `add_recipe_to_cart` | **yes** | Puts a recipe's products in the cart, after your yes. Nothing else |
+| `get_delivery_info` | no | Chosen time, fees |
+| `list_delivery_slots` | no | Free times, cheapest first |
+| `get_orders` / `get_order` | no | What you usually buy |
+
+Full arguments and fields: [docs/tools.md](docs/tools.md).
+
+## Brugsstatistik
+
+handle-mcp counts, anonymously, how far people get from install to a filled cart, so we can show nemlig.com and BilkaToGo how many carts and kroner it sends them each week. It is on by default and easy to turn off.
+
+What is sent, and nothing else. Every event also has `version` and `date` (day only):
+
+| Event | When | Fields |
+|---|---|---|
+| `server_started` | the server starts, at most once per machine per day | `os` (`darwin`, `linux` or `windows`) |
+| `first_tool_call` | the first tool call of the day (a client that only lists the tools sends nothing) | `tool` (e.g. `compare_basket`) |
+| `login_ok` | a store answers with your cart, at most once per store per day | `store` (`nemlig` or `bilka`) |
+| `cart_filled` | once per order: after 30 minutes without changes, only when every line went in. Later edits send nothing until the cart is empty again (after checkout) | `store`, `basket_total_dkk` (rounded to the nearest 50 kr), `item_count` |
+
+Never sent: names, addresses, phone, email, logins, product names, order ids or any id for you or your machine. The events go to [Umami Cloud](https://umami.is) over HTTPS. Umami sees your IP address to send the answer back and to guess the country; it does not save the address. Sends run with a 2 second timeout, in the background. A failed send never breaks a tool. The first tool answer on a machine has a `telemetry_notice`, so your AI tells you about it once. The only file is `~/.config/handle-mcp/telemetry.json`: whether the notice was shown, the day each daily event was last sent, and which stores have a counted cart that is not empty yet.
+
+Cart links (`url` in the cart) carry `utm_source=handlemcp&utm_medium=mcp&utm_campaign=cart`, so the store sees the visit in its own analytics.
+
+Turn it off with any of:
+
+```sh
+HANDLE_TELEMETRY=0          # env var
+DO_NOT_TRACK=1              # the common opt-out
+handle-mcp --no-telemetry   # flag
+```
+
+Send the events to your own Umami: `HANDLE_TELEMETRY_URL=https://umami.example.com/api/send` and `HANDLE_TELEMETRY_WEBSITE=<website id>`. Why and how: [docs/adr/0005](docs/adr/0005-anonymous-usage-counts.md).
+
+## More
+
+[Setup](docs/setup.md) · [Skills](docs/skills.md) · [Security](docs/security.md) · [Troubleshooting](docs/troubleshooting.md) · [Testing](docs/testing.md) · [Roadmap](docs/roadmap.md) · [Contributing](CONTRIBUTING.md) · [Credits](CREDITS.md)
+
+Unofficial. Uses the stores' private website APIs, so it can break any day. Not affiliated with nemlig.com or Salling Group.
+
+[MIT](LICENSE)
+
+Free, and it stays free. If it saves you time or money: <a href="https://buymeacoffee.com/niclasjohansen"><img src="docs/badges/coffee.svg" alt="buy me a coffee" height="26" align="absmiddle"></a>