{"_id":"@diarmind/kanpla-mcp","name":"@diarmind/kanpla-mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@diarmind/kanpla-mcp","version":"0.1.0","description":"Unofficial read-only Model Context Protocol server that reads your Kanpla canteen menu.","keywords":["mcp","model-context-protocol","kanpla","canteen","menu","ai","llm"],"license":"MIT","author":{"name":"Dmitrii Poponkin","url":"https://github.com/diarmind"},"homepage":"https://github.com/diarmind/kanpla-mcp#readme","repository":{"type":"git","url":"git+https://github.com/diarmind/kanpla-mcp.git"},"bugs":{"url":"https://github.com/diarmind/kanpla-mcp/issues"},"type":"module","bin":{"kanpla-mcp":"dist/index.js"},"exports":{".":"./dist/index.js"},"engines":{"node":">=18"},"publishConfig":{"access":"public"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","dotenv":"^17.0.0","zod":"^3.25.0"},"devDependencies":{"@types/node":"^22.0.0","tsx":"^4.19.0","typescript":"^5.6.0","vite":"^8.0.0"},"scripts":{"build":"vite build","dev":"tsx watch src/index.ts","start":"node dist/index.js","typecheck":"tsc --noEmit"},"_id":"@diarmind/kanpla-mcp@0.1.0","_integrity":"sha512-XwdVZ4+UB5QKkSF5F/XUeQ+NCrJlQxVDjjgAsPmToaTiGrb6Z2eZ0SqkTFMDrn8baMYm9LTkbvO0/s8gdt3xqg==","_resolved":"/private/var/folders/s6/jwj5j5kd2jd660zrpj123cfc0000gn/T/954f605d7b1b58c5ecb760096f20fd01/diarmind-kanpla-mcp-0.1.0.tgz","_from":"file:diarmind-kanpla-mcp-0.1.0.tgz","_nodeVersion":"20.19.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-XwdVZ4+UB5QKkSF5F/XUeQ+NCrJlQxVDjjgAsPmToaTiGrb6Z2eZ0SqkTFMDrn8baMYm9LTkbvO0/s8gdt3xqg==","shasum":"e9c35ca6729da085ffa17b8f537566b82144025e","tarball":"https://registry.npmjs.org/@diarmind/kanpla-mcp/-/kanpla-mcp-0.1.0.tgz","fileCount":5,"unpackedSize":46169,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDyxQPUVa1eNO26ovRcnPgqLJa8q9J1vVrdq4DxAz01dAiBtfIvdEOQfk53MDIKbJ3FKWGE+l/uUyuh/U56Z35XxcQ=="}]},"_npmUser":{"name":"ybelion","email":"mitia.poponkin@gmail.com"},"directories":{},"maintainers":[{"name":"ybelion","email":"mitia.poponkin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/kanpla-mcp_0.1.0_1783788016748_0.22312938579635544"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-11T16:40:16.633Z","0.1.0":"2026-07-11T16:40:16.879Z","modified":"2026-07-11T16:40:17.053Z"},"maintainers":[{"name":"ybelion","email":"mitia.poponkin@gmail.com"}],"description":"Unofficial read-only Model Context Protocol server that reads your Kanpla canteen menu.","homepage":"https://github.com/diarmind/kanpla-mcp#readme","keywords":["mcp","model-context-protocol","kanpla","canteen","menu","ai","llm"],"repository":{"type":"git","url":"git+https://github.com/diarmind/kanpla-mcp.git"},"author":{"name":"Dmitrii Poponkin","url":"https://github.com/diarmind"},"bugs":{"url":"https://github.com/diarmind/kanpla-mcp/issues"},"license":"MIT","readme":"# kanpla-mcp\n\nAn unofficial **read-only** [Model Context Protocol](https://modelcontextprotocol.io) server that lets an agent log in to Kanpla under your account and read the canteen menu.\n\nIt wraps the internal frontend API that the `app.kanpla.io` web app itself uses: Firebase (Google Identity Toolkit) for auth, then a single `load/frontend` call for the offers. Your credentials stay inside the server's environment — the agent only ever sees tool results (menu items), never your e-mail, password, or Firebase key.\n\n> ⚠️ **Disclaimer.** This talks to an **undocumented internal API** (`/api/internal/…`), not Kanpla's official partner API. It can break without notice if Kanpla changes their frontend, and it is not endorsed by Kanpla. Use at your own risk, for your own account only.\n\n---\n\n## Features\n\n- 🔐 Credentials and Firebase key live in server env, never in the model's context.\n- ♻️ Token is cached and auto-refreshed (Firebase idTokens expire ~1h) — the agent never handles tokens.\n- 📅 Menu for today or any specific date, with allergens.\n- 🚫 **Read-only by design.** No ordering, no payments, no account mutations.\n\n---\n\n## Requirements\n\n- Node.js ≥ 18 (uses global `fetch`)\n- A Kanpla account you can log in to with e-mail + password\n- Three account-specific values (see [Getting your values](#getting-your-values))\n\n---\n\n## Installation\n\nInstall from npm:\n\n```bash\nnpm install -g @diarmind/kanpla-mcp\n# or run without installing:\nnpx @diarmind/kanpla-mcp\n```\n\n(The installed command is `kanpla-mcp`.)\n\nOr build from source (uses **pnpm** via Corepack and **Vite**):\n\n```bash\ngit clone https://github.com/diarmind/kanpla-mcp.git\ncd kanpla-mcp\ncorepack enable\npnpm install\npnpm build\n```\n\n---\n\n## Configuration\n\nAll configuration is via environment variables. Create a `.env` (loaded by the server on startup) or export them in your MCP client config.\n\n| Variable                 | Required | Default                  | Description                                                                 |\n| ------------------------ | -------- | ------------------------ | --------------------------------------------------------------------------- |\n| `KANPLA_FIREBASE_API_KEY`| Yes      | —                        | Public Firebase client key (`AIza…`). See below.                            |\n| `KANPLA_EMAIL`           | Yes      | —                        | Your Kanpla login e-mail.                                                    |\n| `KANPLA_PASSWORD`        | Yes      | —                        | Your Kanpla password.                                                        |\n| `KANPLA_MODULE_ID`       | No\\*     | —                        | Canteen/module id. Optional if you use `list_modules` to discover it first. |\n| `KANPLA_BASE`            | No       | `https://app.kanpla.io`  | Might differ for regional accounts.                            |\n| `KANPLA_LANGUAGE`        | No       | `en`                     | Language code for menu text (e.g. `en`, `da`, `nb`).                        |\n\n\\* `KANPLA_MODULE_ID` is not required to start the server, but `get_today_menu` / `get_menu_for_date` need a module id — either from this variable or passed as a tool argument.\n\n### Getting your values\n\nOpen `app.kanpla.io`, launch browser DevTools → **Network**, and log in.\n\n- **`KANPLA_FIREBASE_API_KEY`** — find the request to `identitytoolkit.googleapis.com/…signInWithPassword`. The key is the `AIza…` string in its URL (`?key=AIza…`) or in the `x-goog-api-key` request header. It is a public client key, not a secret.\n- **`KANPLA_MODULE_ID`** — the key under `offers` in the `load/frontend` response, or run the `list_modules` tool once and copy the id.\n\n---\n\n## Running\n\n### Standalone (stdio)\n\n```bash\nnode dist/index.js\n```\n\nThe server speaks MCP over **stdio**. It's meant to be launched by an MCP client, not used interactively.\n\n### With an MCP client (e.g. Claude Desktop)\n\nAdd to your client's MCP servers config:\n\n```json\n{\n  \"mcpServers\": {\n    \"kanpla\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/kanpla-mcp/dist/index.js\"],\n      \"env\": {\n        \"KANPLA_FIREBASE_API_KEY\": \"AIza...\",\n        \"KANPLA_EMAIL\": \"you@example.com\",\n        \"KANPLA_PASSWORD\": \"your-password\",\n        \"KANPLA_MODULE_ID\": \"your-module-id\",\n        \"KANPLA_BASE\": \"https://app.kanpla.io\",\n        \"KANPLA_LANGUAGE\": \"en\"\n      }\n    }\n  }\n}\n```\n\nKeep this config file readable only by you — it contains your password.\n\n### Dev mode\n\n```bash\npnpm dev     # tsx watch, reloads on change\n```\n\n---\n\n## MCP tools\n\nAll tools are read-only.\n\n### `get_today_menu`\n\nReturns the available menu items for today.\n\n**Arguments**\n\n| Name       | Type   | Required | Description                                            |\n| ---------- | ------ | -------- | ------------------------------------------------------ |\n| `moduleId` | string | No       | Overrides `KANPLA_MODULE_ID` for this call.            |\n\n**Returns** — array of:\n\n```jsonc\n{\n  \"name\": \"Chicken breast\",\n  \"description\": \"Served with hummus, roast harissa potatoes & roasted vegetables\",\n  \"allergens\": [\"sesame\", \"milk\"],\n  \"category\": \"Main dish\",\n  \"date\": \"2026-07-13\"\n}\n```\n\n`category` is the section the dish belongs to (e.g. `Main dish`, `Soup`, `Drinks`).\n\nEmpty array means no dishes that day (weekend / closed / wrong module).\n\n---\n\n### `get_menu_for_date`\n\nMenu for a specific day.\n\n**Arguments**\n\n| Name       | Type   | Required | Description                                 |\n| ---------- | ------ | -------- | ------------------------------------------- |\n| `date`     | string | Yes      | ISO date, `YYYY-MM-DD`.                     |\n| `moduleId` | string | No       | Overrides `KANPLA_MODULE_ID` for this call. |\n\n**Returns** — same shape as `get_today_menu`.\n\n---\n\n### `list_modules`\n\nLists the canteens/modules available to your account, so you can find your `moduleId`.\n\n**Arguments** — none.\n\n**Returns** — array of:\n\n```jsonc\n{ \"moduleId\": \"abc123\", \"name\": \"HQ Canteen\" }\n```\n\n---\n\n## How it works\n\n```\n1. Firebase login\n   POST identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=<API_KEY>\n   { email, password, returnSecureToken: true }  ->  idToken, localId\n\n2. (on expiry) refresh\n   POST securetoken.googleapis.com/v1/token?key=<API_KEY>\n   grant_type=refresh_token  ->  new idToken\n\n3. Load offers\n   POST <BASE>/api/internal/load/frontend\n   headers: authorization: Bearer <idToken>, kanpla-app-env: PROD,\n            kanpla-auth-provider: GAuth, origin: <BASE>   # origin is required\n   { userId: localId, url: \"app\", language }  ->  offers[moduleId].items + modules[]\n\n4. For each item (a category) look at item.dates{<unixSeconds>} whose key falls in\n   the target UTC day, keep entries with available !== false and a populated\n   .menu, then expose { name, description, allergens, category, date } — where\n   allergens are the true-valued top-level keys of menu.allergens.\n```\n\n> Module display names come from the top-level `modules[]` list; `offers` is\n> keyed by `moduleId` and carries no name. `origin` must be sent or the backend\n> responds `500 {\"message\":\"Invalid URL\"}`.\n\nThe idToken is cached in memory and refreshed automatically; nothing is persisted to disk.\n\n---\n\n## Project layout\n\n```\nkanpla-mcp/\n├─ src/\n│  ├─ index.ts          # MCP server entry (stdio transport, tool registration)\n│  ├─ kanpla.ts         # Kanpla client: login, token cache, load/frontend\n│  ├─ auth.ts           # Firebase signInWithPassword + securetoken refresh\n│  ├─ menu.ts           # date filtering, item -> menu mapping\n│  └─ config.ts         # env parsing/validation (zod)\n├─ dist/                # bundled output (pnpm build)\n├─ package.json\n├─ tsconfig.json\n├─ vite.config.ts\n└─ README.md\n```\n\n## Scripts\n\n| Command          | Description                             |\n| ---------------- | --------------------------------------- |\n| `pnpm build`     | Bundle to `dist/` with Vite.            |\n| `pnpm dev`       | Watch mode via `tsx`.                   |\n| `pnpm typecheck` | Type-check with `tsc --noEmit`.         |\n| `pnpm start`     | Run the built server (`dist/index.js`). |\n\n---\n\n## Security notes\n\n- Your password and Firebase key are read from env only; they are **never** returned by any tool and never enter the agent's context.\n- The Firebase API key is a public client key — safe to store, but treat the config file as sensitive because it also holds your password.\n- Restrict file permissions on any `.env` or client config: `chmod 600`.\n\n## Limitations\n\n- Depends on an undocumented internal endpoint; may break on Kanpla frontend changes.\n- Not affiliated with or supported by Kanpla ApS.\n- Read-only: ordering and payments are intentionally out of scope.\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-41a6a8e391c314366170680a7a97d4ab"}