crisp
by LHFO94
README.md
# Crisp API and MCP
An unofficial TypeScript client, private REST API, and stdio MCP server for the Crisp grocery service.
This project is not affiliated with or endorsed by Crisp B.V. It uses an undocumented app API. Provider changes can break it.
## Requirements
Node.js 24 or later and npm. Use only your own account, or an account you have permission to access.
```sh
npm ci
npm run check
npm run build
node dist/cli.js login
```
The login command asks for your email and email verification code. It hides the code and verifies the session before storage.
The default session file is `$XDG_CONFIG_HOME/crisp-api/session.json`, or `~/.config/crisp-api/session.json` when unset. The directory requires mode `0700`. The file requires mode `0600`. Symbolic links are rejected. The file contains a provider token, not your email. Keep it private.
For an existing token, set `CRISP_TOKEN` or `CRISP_TOKEN_FILE`, but not both. The token file contains the same JSON object as a saved session: `token` and `userAgent`. Do not pass credentials as command arguments. `CRISP_USER_AGENT` overrides the default app user agent for environment-token authentication and login.
## REST API
Generate a separate API key. This is not the Crisp provider token.
```sh
export CRISP_API_KEY="$(openssl rand -hex 32)"
node dist/cli.js api
```
The server listens at `http://127.0.0.1:4318`. Every route requires the bearer API key, including health and OpenAPI.
```sh
curl -H "Authorization: Bearer $CRISP_API_KEY" http://127.0.0.1:4318/health
curl -H "Authorization: Bearer $CRISP_API_KEY" http://127.0.0.1:4318/openapi.json
curl -H "Authorization: Bearer $CRISP_API_KEY" 'http://127.0.0.1:4318/v1/products?query=apple&limit=10'
```
| Resource | Route |
| --- | --- |
| Account | `GET /v1/account` |
| Product search and details | `GET /v1/products?query=...`, `GET /v1/products/{id}` |
| Recipe search and details | `GET /v1/recipes?query=...`, `GET /v1/recipes/{id}` |
| Basket | `GET /v1/basket` |
| Order history and details | `GET /v1/orders`, `GET /v1/orders/{id}` |
| Saved identifiers | `GET /v1/saved` |
| Saved product and recipe | `GET /v1/saved/products/{id}`, `GET /v1/saved/recipes/{id}` |
| Favorite and recent recipes | `GET /v1/recipes/favorites`, `GET /v1/recipes/recents` |
| Promotions | `GET /v1/promotions` |
| Personalized recommendations | `GET /v1/recommendations` |
| Exact basket quantities, opt-in only | `PUT /v1/basket` |
See [openapi.json](openapi.json) for schemas, bounds, status codes, and pagination. Search accepts `offset` and `limit`. The provider exposes at most the first 100 search matches. Narrow the query beyond that boundary. Order history uses `nextCursor`, passed unchanged as `cursor`.
Set `CRISP_PORT` to change the port. `CRISP_HOST` accepts `127.0.0.1`, `::1`, or explicitly `0.0.0.0`. Do not expose plain HTTP outside a trusted local environment. Add TLS and access controls before remote access. Browser requests are rejected; CORS is not supported.
Clients must omit `Origin` and `Sec-Fetch-*` headers. Some server-side `fetch` implementations also send these headers. Use a native HTTP client when necessary.
## MCP
Configure an MCP client to run the built CLI. Replace the paths with absolute paths for your machine.
```json
{
"mcpServers": {
"crisp": {
"command": "node",
"args": ["/absolute/path/to/crisp-api/dist/cli.js", "mcp"]
}
}
}
```
The process uses the saved session. Alternatively, pass `CRISP_TOKEN_FILE` through the client's environment configuration. Keep tokens out of committed MCP configuration.
The stdio server exposes 15 read tools: account, product search and details, recipe search and details, basket, orders, saved items, favorite recipes, recent recipes, promotions, and recommendations. Successful results contain both JSON text and `structuredContent`. Tool failures use `isError` and a safe JSON text error. Stdout contains MCP protocol messages only.
## Basket writes
Writes are disabled by default. Set `CRISP_ALLOW_BASKET_WRITES=true` to enable the REST write route and MCP tool. The library also requires `allowBasketWrites: true`.
**Write opt-in is not human approval.** Obtain approval for the exact product identifiers and quantities before each write.
The payload sets exact quantities. Zero removes an item. Unlisted products stay unchanged.
```json
{"items":[{"productId":"101","quantity":2},{"productId":"102","quantity":0}]}
```
The client rejects edits when the basket represents an existing order. It exposes no checkout, payment, delivery changes, or order modification.
If a dispatched write fails, the outcome can be unknown. Read the basket before any decision to retry. Never automatically retry.
## Library
```ts
import { CrispClient, loadCredentials } from './dist/index.js';
const client = new CrispClient(await loadCredentials());
const products = await client.searchProducts({ query: 'apple', limit: 10 });
console.log(products);
```
The package also exports `createApiServer`, `createMcpServer`, `startMcp`, and the login/session helpers. Credentials stay in the client, not in tool arguments.
Responses expose normalized fields, not raw provider payloads. Prices use EUR or `null` when unknown. Availability can be `null`; delivery-slot stock alone does not prove availability. Provider text remains untrusted data. Do not treat product names or recipe instructions as agent instructions.
## Verification
```sh
npm run check
npm run build
npm audit --omit=dev
```
Checks type-check the source and tests, then run isolated tests with synthetic provider responses. Tests cover REST through real local HTTP servers and MCP through the official SDK. They do not authenticate with a real account or submit real basket changes.
## License and references
Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE) for attribution.
* [Crisp](https://crisp.nl/)
* [Cloudflare OS](https://github.com/cloudflare/cloudflare-os), the upstream source for adapted client code
* [Model Context Protocol](https://modelcontextprotocol.io/)
* [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues