{
  "markdown": "# Matkorgen — Grocery Shopping MCP Server\n\nAn MCP (Model Context Protocol) server that lets an LLM search for products,\nmanage a shopping cart, and interact with Swedish grocery stores. Currently\nsupports **ICA** via Playwright browser automation.\n\n## Prerequisites\n\n- **Node.js** ≥ 18\n- **npm**\n\n## Setup\n\n```bash\n# 1. Clone the repository\ngit clone https://github.com/JMrtzsn/Matkorgen.git\ncd Matkorgen\n\n# 2. Install dependencies (also builds dist/server.js and downloads Chromium)\nnpm install\n\n# 3. (Optional) Add ICA credentials for cart operations\necho \"ICA_USERNAME=your-ica-username\" > .env\necho \"ICA_PASSWORD=your-ica-password\" >> .env\n```\n\n> **Anonymous mode:** If you skip step 3, the server still works for\n> browsing and searching products — cart operations require authentication\n> via the `login` tool at runtime.\n\n## Usage\n\n### As an MCP server (stdio)\n\n```bash\nnpm start\n# or\nnode dist/server.js\n```\n\nThe server communicates over stdin/stdout using the MCP JSON-RPC protocol.\nConfigure your MCP client to spawn it as a subprocess.\n\n### MCP client configuration\n\nA `.mcp.json` is included in the project root for IDEs that support it (\nJetBrains, VS Code, Cursor):\n\n```json\n{\n    \"servers\": {\n        \"ica-shopping\": {\n            \"type\": \"stdio\",\n            \"command\": \"node\",\n            \"args\": [\n                \"dist/server.js\"\n            ],\n            \"env\": {}\n        }\n    }\n}\n```\n\nYou can also set a default store via environment variable:\n\n```json\n{\n    \"servers\": {\n        \"ica-shopping\": {\n            \"type\": \"stdio\",\n            \"command\": \"node\",\n            \"args\": [\n                \"dist/server.js\"\n            ],\n            \"env\": {\n                \"ICA_STORE_ID\": \"1003577\"\n            }\n        }\n    }\n}\n```\n\n### Testing with the MCP Inspector\n\n```bash\nnpx @modelcontextprotocol/inspector node dist/server.js\n```\n\nThis opens a web UI where you can call tools interactively.\n\n## Gemini Extension\n\nThis project is also a **Gemini Extension** — Gemini Pro users can install it\ndirectly without setting up a local MCP client.\n\n### Install from GitHub\n\n```bash\ngemini extensions install https://github.com/JMrtzsn/Matkorgen\n\n# Build the bundle and install Playwright (Gemini CLI does not run npm install automatically)\ncd ~/.gemini/extensions/matkorgen && npm install\n```\n\n> `npm install` runs a `postinstall` script that bundles the TypeScript source\n> with esbuild and downloads a Chromium binary for the login flow.\n\n### Install from a local clone\n\n```bash\ncd matkorgen\nnpm install\ngemini extensions link .\n```\n\n### Verify\n\nLaunch the Gemini CLI and confirm the extension is registered:\n\n```bash\ngemini\n> /mcp list\n# Should show \"ica-shopping\" with its tools\n```\n\n### Configuration\n\nOn first use Gemini will prompt you for the settings declared in\n`gemini-extension.json`:\n\n| Setting        | Env Var        | Description                                                       |\n|----------------|----------------|-------------------------------------------------------------------|\n| `ICA_STORE_ID` | `ICA_STORE_ID` | Default store ID (optional — can also use `set_store` at runtime) |\n| `ICA_USERNAME` | `ICA_USERNAME` | ICA account email (required for cart operations)                  |\n| `ICA_PASSWORD` | `ICA_PASSWORD` | ICA account password (sensitive, required for cart operations)    |\n\n### Usage\n\nOnce installed, just ask Gemini naturally:\n\n> *\"Search for milk at ICA store 1003577 and add 2 to my cart\"*\n\nGemini will call `set_store`, `login`, `search_products`, and `add_to_cart`\nautomatically.\n\n## Tools\n\n| Tool                 | Description                                        | Inputs                                           |\n|----------------------|----------------------------------------------------|--------------------------------------------------|\n| `set_store`          | Initialise a grocery store session.                | `chain` (string, e.g. \"ica\"), `storeId` (string) |\n| `login`              | Authenticate with the active store.                | `username` (string), `password` (string)         |\n| `search_products`    | Search for products by name or ingredient.         | `query` (string)                                 |\n| `get_favourites`     | Retrieve starred/favourite products.               | —                                                |\n| `get_purchase_history` | Retrieve frequently purchased products (regulars). | —                                              |\n| `add_to_cart`        | Add a product to the cart.                         | `productId` (string), `quantity` (int)           |\n| `get_cart`           | Retrieve current cart contents.                    | —                                                |\n| `edit_cart`          | Set product quantity in the cart. Use 0 to remove. | `productId` (string), `quantity` (int ≥ 0)       |\n\n### Example flow (what an LLM does)\n\n1. **`set_store(\"ica\", \"1003577\")`** — target a specific ICA store\n2. **`login(\"user@example.com\", \"password\")`** — authenticate\n3. **`search_products(\"mjölk\")`** — find milk products\n4. **`add_to_cart(\"2000697\", 2)`** — add 2× Mjölk 3% Laktosfri\n5. **`get_cart()`** — verify cart contents\n6. **`edit_cart(\"2000697\", 1)`** — reduce to 1\n7. **`edit_cart(\"2000697\", 0)`** — remove from cart\n\n## Tests\n\n```bash\n# Build & run unit tests\nnpm test\n\n# Build & run end-to-end tests (requires ICA_USERNAME / ICA_PASSWORD in .env)\nnpm run test:e2e\n```\n\n## Project Structure\n\n```\nsrc/\n  server.ts                  — MCP server entry point (stdio transport, tool registration)\n  stores/\n    types.ts                 — Shared domain types & GroceryStore adapter interface\n    ica/\n      ica.ts                 — ICA adapter (session, HTTP API, Playwright auth)\n      login-flow.ts          — Shared Playwright login helpers (used by ica.ts)\ntests/\n  e2e/\n    e2e.test.ts              — End-to-end MCP server test (Client + StdioClientTransport)\nspecs/                       — Feature specifications\n.mcp.json                    — MCP server registration for IDEs\ngemini-extension.json        — Gemini Extension manifest\n.auth/                       — Session state (gitignored)\n```\n",
  "bytes": 6155,
  "sha": "e3b22b38c9c5d8955d1d00f8a91a767c2ad1a4cf24e641bc7a527a28322babc4",
  "repo_slug": "jmrtzsn/matkorgen",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_jmrtzsn_matkorgen_85b93fb1/readme"
}