albert-heijn-mcp 1.3.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,376 @@
+<p align="center"><img src="assets/logo.png" alt="" width="128" height="128"></p>
+
+# albert-heijn-mcp
+
+[![npm](https://img.shields.io/npm/v/albert-heijn-mcp?color=cb3837&logo=npm)](https://www.npmjs.com/package/albert-heijn-mcp)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Node.js 24](https://img.shields.io/badge/node-24%20LTS-339933?logo=node.js&logoColor=white)](.nvmrc)
+[![MCP](https://img.shields.io/badge/MCP-server-6E56CF)](https://modelcontextprotocol.io)
+
+**Your Albert Heijn account, in your AI assistant.**
+
+albert-heijn-mcp is a [Model Context Protocol](https://modelcontextprotocol.io) server for Albert Heijn 🇳🇱. Connect it to any MCP client and just ask: find products and bonus deals, plan meals from Allerhande recipes, keep your shopping list and delivery order up to date, and look back at what you've bought.
+
+> [!NOTE]
+> An unofficial project, not affiliated with or endorsed by Albert Heijn. It uses the same API as the AH mobile app, which may change without notice.
+
+---
+
+## Contents
+
+- [What you can ask](#what-you-can-ask)
+- [Quick start](#quick-start)
+- [Logging in](#logging-in)
+- [Connecting a client](#connecting-a-client)
+- [Configuration](#configuration)
+- [Deploying to a server](#deploying-to-a-server)
+- [Tools](#tools) and [limitations](#limitations)
+- [Development](#development)
+- [Troubleshooting](#troubleshooting)
+
+## What you can ask
+
+Ask in Dutch, English or any language your assistant speaks:
+
+> *"Wat is er deze week in de bonus van wat ik meestal koop?"*
+
+**Plan meals**
+
+> *"Find a vegetarian Allerhande recipe under 30 minutes for two, and put the ingredients on my shopping list. I already have olive oil and salt."*
+
+> *"Scale the panlasagne recipe to six people and tell me how much salmon I need."*
+
+> *"Plan three weeknight dinners around what's on bonus this week."*
+
+**Save money**
+
+> *"Which products I usually buy are on bonus this week?"*
+
+> *"Rebuild tonight's stir-fry with ingredients that are on bonus, without changing the recipe too much."*
+
+> *"Is next week's bonus out yet? If not, when does it appear?"*
+
+> *"What's in the 2+1 gratis kaas deal?"*
+
+**Shop**
+
+> *"Put the products I've had delivered at least three times back on my list."*
+
+> *"Find organic, gluten-free pasta, cheapest first."*
+
+> *"Compare the protein and sugar in these three yoghurts and add the best one to my list."*
+
+> *"When can AH deliver on Saturday?"*
+
+> *"The courgettes are sold out. What else would work in this recipe?"*
+
+> *"Add two more packs of milk to my upcoming delivery."*
+
+> *"Make a favourites list called Pasta night with everything from this recipe."*
+
+> *"Any vandaag-af bread or vegetables at my local AH worth picking up tonight?"*
+
+**Look back**
+
+> *"How much did my in-store receipts add up to in September, and what were the five priciest items?"*
+
+> *"Show the receipt from my last shop and list anything I bought more than once."*
+
+## Quick start
+
+**Requirements:** Node.js 24 (LTS) and an Albert Heijn account.
+
+There's nothing to install: [connect a client](#connecting-a-client) with `npx -y albert-heijn-mcp`, which downloads and runs the [latest version](https://www.npmjs.com/package/albert-heijn-mcp), then ask it to log you in to Albert Heijn.
+
+To install it permanently instead, run `npm install --global albert-heijn-mcp` and use the `albert-heijn-mcp` command. To [build from source](#development), clone the repository.
+
+## Logging in
+
+AH's login page has a captcha that only works on AH's own site, so logging in takes two steps:
+
+1. **Ask your assistant to log you in.** It calls `ah_login` and gives you a link to AH's login page; locally, it also opens in your browser. Log in as usual.
+2. **Paste the code back.** After you log in, AH redirects to a link meant for its iPhone app, which the browser can't open, so the page stays put. Open the developer console (Chrome: <kbd>⌘</kbd> <kbd>⌥</kbd> <kbd>J</kbd> on Mac, <kbd>Ctrl</kbd> <kbd>Shift</kbd> <kbd>J</kbd> on Windows/Linux) and find this line:
+
+   ```
+   Failed to launch 'appie://login-exit?code=…' because the scheme does not have a registered handler.
+   ```
+
+   Copy the `appie://login-exit?code=…` link into the chat. The code works once and expires quickly, so paste it right away.
+
+You only log in once. Tokens are stored on your machine and refreshed automatically:
+
+| OS | Location |
+|---|---|
+| macOS | `~/Library/Application Support/albert-heijn-mcp/tokens.json` |
+| Linux | `~/.config/albert-heijn-mcp/tokens.json` |
+| Windows | `%AppData%\albert-heijn-mcp\tokens.json` |
+
+The file is readable only by your user. Override the location with `AH_TOKENS_PATH`.
+
+## Connecting a client
+
+albert-heijn-mcp works with any MCP client. It runs locally over stdio, or on a server over Streamable HTTP.
+
+### Local clients (stdio)
+
+Clients that start MCP servers as a local command run `npx -y albert-heijn-mcp`. Most of them take this JSON in their MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "ah": {
+      "command": "npx",
+      "args": ["-y", "albert-heijn-mcp"]
+    }
+  }
+}
+```
+
+Where the settings live differs per client; see its documentation. Clients with a CLI usually have an add command instead, e.g. `<client> mcp add ah -- npx -y albert-heijn-mcp`. It is also listed in the [MCP Registry](https://registry.modelcontextprotocol.io), which some clients install from.
+
+> [!TIP]
+> Desktop apps don't load your shell profile, so they may not find `npx` (common with nvm). Then set `command` to the output of `which npx`. For a source checkout, use `node` with the argument `/path/to/albert-heijn-mcp/dist/index.js`.
+
+### Remote clients (Streamable HTTP)
+
+Web apps such as ChatGPT and Claude.ai only connect to servers on the internet. Set one up first ([Deploying to a server](#deploying-to-a-server)). The endpoint is `https://your-server/mcp`. Send the token as an `Authorization: Bearer YOUR_TOKEN` header if the client lets you set headers; otherwise put it in the URL: `https://your-server/mcp?token=YOUR_TOKEN`.
+
+**ChatGPT**: needs Developer mode (Plus, Pro, Business, Enterprise and Education). Open Settings → advanced settings, turn on Developer mode, and create a connector with the URL. Set authentication to **No authentication**: ChatGPT offers only OAuth or none, so the token goes in the URL.
+
+**Claude.ai**: Settings → Connectors → Add custom connector, then paste the URL with the token.
+
+> [!IMPORTANT]
+> A token in a URL can end up in proxy logs. Use a long random value (`openssl rand -hex 32`) and replace it if it leaks.
+
+## Configuration
+
+Settings are environment variables. They can also go in a `.env` file in the working directory (see [`.env.example`](.env.example)); variables already set in the environment take precedence.
+
+| Variable | Default | Description |
+|---|---|---|
+| `AH_REMOTE` | `false` | Don't open a browser on login. Use on servers (same as `--remote`). |
+| `AH_TOKENS_PATH` | [per OS](#logging-in) | Where to store login tokens. |
+| `AH_MCP_HOST` | `127.0.0.1` | Interface the HTTP server listens on. Keep the default behind a reverse proxy. |
+| `AH_MCP_PORT` | `3000` | HTTP server port. |
+| `AH_MCP_BASE_URL` | `http://localhost:3000` | Public URL of the HTTP server. Set it on a server: for a non-local URL, the localhost-only `Host` check is turned off so a reverse proxy can forward requests. |
+| `AH_MCP_TOKEN` | — | Secret required on every HTTP request, as `Authorization: Bearer …` or `?token=…`. Required for the HTTP transport, which doesn't start without it. |
+| `AH_LOG_FILE` | — | Also append logs to this file. Logs always go to stderr. |
+
+Command-line flags:
+
+```
+node dist/index.js [--transport stdio|streamable-http] [--remote] [--version] [--help]
+```
+
+`stdio` (the default) is for local clients; `streamable-http` serves MCP at `/mcp`.
+
+## Deploying to a server
+
+albert-heijn-mcp runs as a hardened systemd service behind a reverse proxy, installed from the latest release.
+
+1. **Prepare the server.** Install Node.js 24 and create a service user:
+
+   ```bash
+   sudo useradd -r -m -d /home/albert-heijn-mcp -s /sbin/nologin albert-heijn-mcp
+   ```
+
+2. **Configure it** in `/home/albert-heijn-mcp/.env`:
+
+   ```env
+   AH_MCP_BASE_URL=https://albert-heijn-mcp.example.com
+   AH_MCP_TOKEN=<output of: openssl rand -hex 32>
+   ```
+
+3. **Install it** with the [service unit](deploy/albert-heijn-mcp.service) that comes with the package (it runs in `--remote` mode):
+
+   ```bash
+   sudo npm install --global --prefix /usr/local albert-heijn-mcp
+   sudo install -m 644 /usr/local/lib/node_modules/albert-heijn-mcp/deploy/albert-heijn-mcp.service /etc/systemd/system/
+   sudo systemctl daemon-reload
+   sudo systemctl enable --now albert-heijn-mcp
+   ```
+
+   To update, run the same commands, then `sudo systemctl restart albert-heijn-mcp`.
+
+4. **Add TLS** with a reverse proxy that forwards to `127.0.0.1:3000`. With Caddy:
+
+   ```
+   albert-heijn-mcp.example.com {
+       reverse_proxy 127.0.0.1:3000
+   }
+   ```
+
+The service can write only to `/home/albert-heijn-mcp`, where it keeps its tokens. If you point `AH_LOG_FILE` elsewhere, add that path to `ReadWritePaths` in the unit file.
+
+## Tools
+
+Read-only tools are marked as such, so clients can run them without asking. Tools that remove data are marked destructive, so clients ask for confirmation first.
+
+Tools that return data also return it as [structured output](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content) with a declared schema, for clients that use it. Products and recipes in tool results include a `url` to their page on ah.nl, and the server asks the assistant to link their names to it.
+
+<details open>
+<summary><b>Account</b></summary>
+
+| Tool | Description |
+|---|---|
+| `ah_login` | Log in: returns AH's login link, then completes the login with the code you paste back. |
+| `ah_logout` | Delete the stored tokens, to switch accounts or reset a session. |
+| `ah_get_member_profile` | Name, masked email, and bonus card number (last 4 digits). |
+
+</details>
+
+<details open>
+<summary><b>Products & offers</b></summary>
+
+| Tool | Description |
+|---|---|
+| `ah_search_products` | Search one or more keywords at once; Dutch terms work best. Filter by `bonus=true` or by `filters` (organic, vegan, gluten_free and other diets, allergens and labels), and `sort` by price, what you buy most, or Nutri-Score. |
+| `ah_get_products` | Details for one or more products. `include_nutritional_info=true` adds the nutrition table. |
+| `ah_get_product_alternatives` | Similar products and substitutes AH suggests for a product. |
+| `ah_get_bonus_offers` | This week's bonus offers, or next week's with `period=next`. `previously_bought=true` limits them to products you bought before (AH's "Eerder gekocht"). Can filter by keyword. |
+| `ah_get_bonus_group_products` | The individual products behind a group deal such as "2+1 gratis". |
+| `ah_search_stores` | Nearby stores, by postal code or your own address. |
+| `ah_get_last_chance_items` | Vandaag-af markdowns in a store; the one nearest your address by default. |
+
+</details>
+
+<details open>
+<summary><b>Recipes</b></summary>
+
+| Tool | Description |
+|---|---|
+| `ah_search_recipes` | Search Allerhande recipes; Dutch terms work best. |
+| `ah_get_recipe` | Ingredients, steps, and nutrition per serving. `servings` scales the ingredients. |
+| `ah_add_recipe_to_shopping_list` | Match a recipe's ingredients to products and add them to the list in one step. `skip` leaves out what you have; `dry_run=true` previews the matches. |
+
+</details>
+
+<details open>
+<summary><b>Shopping list & favourites</b></summary>
+
+| Tool | Description |
+|---|---|
+| `ah_get_shopping_list` | Your shopping list ("Mijn lijst"), the basket you fill while shopping. |
+| `ah_add_to_shopping_list` | Put products on the list, with a quantity each. |
+| `ah_add_free_text_to_shopping_list` | Add a free-text item, like "verse bloemen". |
+| `ah_remove_from_shopping_list` | Remove products or free-text items. |
+| `ah_clear_shopping_list` | Remove everything. Requires `confirm="yes"`. |
+| `ah_get_favorite_lists` | Your favourite lists ("Mijn lijstjes"). |
+| `ah_add_to_favorite_list` | Add products to a favourite list. |
+| `ah_remove_from_favorite_list` | Take products off a favourite list. |
+| `ah_create_favorite_list` | Start a new, empty favourite list. |
+| `ah_delete_favorite_list` | Delete a favourite list and its items. Requires `confirm="yes"`. |
+
+</details>
+
+<details open>
+<summary><b>Delivery order</b></summary>
+
+Choosing a delivery or pick-up slot in the AH app moves your shopping list into an order. `ah_get_delivery_slots` shows when delivery is possible; the other tools work on that order.
+
+| Tool | Description |
+|---|---|
+| `ah_get_delivery_slots` | Delivery windows at your address for the coming days. |
+| `ah_get_cart` | Products in the active order, with total price and discount. |
+| `ah_update_cart_item` | Change a product's quantity; 0 takes it out. |
+| `ah_remove_from_cart` | Remove a product from the order. |
+| `ah_clear_cart` | Remove everything from the order. Requires `confirm="yes"`. |
+
+</details>
+
+<details open>
+<summary><b>Orders & receipts</b></summary>
+
+| Tool | Description |
+|---|---|
+| `ah_get_orders` | Upcoming delivery orders, or past ones with `past=true`. |
+| `ah_get_order_details` | Products in one order. |
+| `ah_get_frequent_items` | Your most-ordered products, counted over your delivery orders. |
+| `ah_get_receipts` | Recent in-store receipts (kassabonnen). |
+| `ah_get_receipt_details` | Items, discounts and payment for one receipt. |
+
+</details>
+
+### Limitations
+
+- **Delivery orders can't be started through the API.** `ah_get_delivery_slots` lists the windows, but booking one, which starts the order, happens in the AH app or on ah.nl. While the order is active, AH doesn't serve the shopping list; the tools say so and point to the order tools.
+- **Ticking off shopping-list items isn't supported:** the API returns no usable item IDs.
+- **Bonus Box**, AH's personal weekly deals, is not available: its API is unknown.
+
+## Development
+
+```bash
+git clone https://github.com/olekpuchka/albert-heijn-mcp
+cd albert-heijn-mcp
+npm ci
+npm run build    # compile to dist/
+npm run lint     # type-check
+```
+
+Run it from the checkout with `node dist/index.js`, or use `/path/to/albert-heijn-mcp/dist/index.js` as the argument in your client's config with `node` as the command.
+
+| Path | Contents |
+|---|---|
+| [`src/index.ts`](src/index.ts), [`src/config.ts`](src/config.ts) | Entry point, flags and settings |
+| [`src/ahapi/`](src/ahapi) | Client for AH's REST and GraphQL API, on Node's built-in `fetch` |
+| [`src/auth/`](src/auth) | Login code exchange, token storage and refresh |
+| [`src/server/`](src/server) | Streamable HTTP transport and token check |
+| [`src/tools/`](src/tools) | The MCP tools, one file per area |
+| [`deploy/`](deploy) | systemd unit, shipped in the package |
+| [`listing/`](listing) | Name, descriptions and icon to use in connector settings and app directories ([how](listing/README.md)) |
+| [`.github/`](.github) | CI, release workflow and Dependabot |
+| [`assets/`](assets) | Logo for this README and the server icon shown by MCP clients |
+
+The only runtime dependencies are the official [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) and Zod, which the SDK uses for tool schemas.
+
+To call tools by hand, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
+
+```bash
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+Before deploying a change, run a quick check against a real account: log in, search for `melk`, add a product to your shopping list and remove it again, then view your cart and orders.
+
+To release, set the new version in `package.json` and in both places in [`server.json`](server.json), merge it to `main`, and push a tag: `git tag v1.2.3 && git push origin v1.2.3`. The [release workflow](.github/workflows/release.yml) checks that the versions match, builds the package, attaches it to the GitHub release as `albert-heijn-mcp.tgz`, publishes it to npm, and updates the [MCP Registry](https://registry.modelcontextprotocol.io) entry. npm accepts the workflow through [trusted publishing](https://docs.npmjs.com/trusted-publishers), so no npm token is stored.
+
+## Troubleshooting
+
+<details>
+<summary><b>Login fails with "exchange code"</b></summary>
+
+Codes work once and expire quickly. Ask to log in again and paste the new link straight away.
+</details>
+
+<details>
+<summary><b>No "Failed to launch" line after logging in</b></summary>
+
+Open the developer console before you submit the login form, or look for the `appie://login-exit?code=…` request in the Network tab. Browsers other than Chrome may show the link in an error page or dialog instead.
+</details>
+
+<details>
+<summary><b>"Not logged in", or the session seems broken</b></summary>
+
+Log out and back in through the assistant, or delete `tokens.json` from the [token location](#logging-in) and log in again.
+</details>
+
+<details>
+<summary><b>"There is no active delivery order to change"</b></summary>
+
+AH accepts order changes only once an order exists. Choose a delivery slot in the AH app or on ah.nl first.
+</details>
+
+<details>
+<summary><b>"The shopping list is not available while a delivery order is active"</b></summary>
+
+Choosing a slot moved your list into the order. Use `ah_get_cart` and `ah_update_cart_item` until the order is delivered or cancelled.
+</details>
+
+<details>
+<summary><b>Port 3000 is in use</b></summary>
+
+Set `AH_MCP_PORT` to another port, in the environment or `.env`.
+</details>
+
+## License
+
+[Apache 2.0](LICENSE)

package/deploy/albert-heijn-mcp.service

@@ -0,0 +1,42 @@
+[Unit]
+Description=Albert Heijn MCP Server
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+User=albert-heijn-mcp
+EnvironmentFile=/home/albert-heijn-mcp/.env
+ExecStart=/usr/local/bin/albert-heijn-mcp --transport streamable-http --remote
+WorkingDirectory=/home/albert-heijn-mcp
+Restart=on-failure
+RestartSec=5
+
+# Hardening: the server needs only the network and write access to its home
+# directory (tokens live in /home/albert-heijn-mcp/.config). If AH_LOG_FILE points
+# elsewhere, add it to ReadWritePaths. MemoryDenyWriteExecute is left out:
+# Node's JIT compiler needs it off.
+NoNewPrivileges=yes
+UMask=0077
+ProtectSystem=strict
+ReadWritePaths=/home/albert-heijn-mcp
+PrivateTmp=yes
+PrivateDevices=yes
+ProtectKernelTunables=yes
+ProtectKernelModules=yes
+ProtectKernelLogs=yes
+ProtectControlGroups=yes
+ProtectClock=yes
+ProtectHostname=yes
+RestrictNamespaces=yes
+RestrictRealtime=yes
+RestrictSUIDSGID=yes
+LockPersonality=yes
+RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
+CapabilityBoundingSet=
+AmbientCapabilities=
+SystemCallArchitectures=native
+SystemCallFilter=@system-service
+SystemCallErrorNumber=EPERM
+
+[Install]
+WantedBy=multi-user.target

package/dist/ahapi/auth.js

@@ -0,0 +1,18 @@
+import { CLIENT_NAME } from "./client.js";
+/** AH login page. After login it redirects to appie://login-exit?code=... (see exchangeCode). */
+export const LOGIN_URL = `https://login.ah.nl/login?client_id=${CLIENT_NAME}&response_type=code&redirect_uri=appie://login-exit`;
+/** Exchanges an OAuth authorization code for tokens. */
+export function exchangeCode(c, code) {
+    return c.request("/mobile-auth/v1/auth/token", {
+        method: "POST",
+        body: { clientId: CLIENT_NAME, code },
+    });
+}
+/** Exchanges a refresh token for a new pair. The old refresh token stops working (AH rotates them). */
+export function refreshToken(c, refreshToken) {
+    return c.request("/mobile-auth/v1/auth/token/refresh", {
+        method: "POST",
+        body: { clientId: CLIENT_NAME, refreshToken },
+    });
+}
+//# sourceMappingURL=auth.js.map

package/dist/ahapi/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/ahapi/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,WAAW,EAAE,MAAM,aAAa,CAAC;AAEzD,iGAAiG;AACjG,MAAM,CAAC,MAAM,SAAS,GAAG,uCAAuC,WAAW,qDAAqD,CAAC;AAUjI,wDAAwD;AACxD,MAAM,UAAU,YAAY,CAAC,CAAW,EAAE,IAAY;IACpD,OAAO,CAAC,CAAC,OAAO,CAAQ,4BAA4B,EAAE;QACpD,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE;KACtC,CAAC,CAAC;AACL,CAAC;AAED,uGAAuG;AACvG,MAAM,UAAU,YAAY,CAAC,CAAW,EAAE,YAAoB;IAC5D,OAAO,CAAC,CAAC,OAAO,CAAQ,oCAAoC,EAAE;QAC5D,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE;KAC9C,CAAC,CAAC;AACL,CAAC"}