# tuma250-mcp

[![PyPI version](https://img.shields.io/pypi/v/tuma250-mcp?style=for-the-badge&logo=python&logoColor=white&color=green
)](https://pypi.org/project/tuma250-mcp/)

An [MCP](https://modelcontextprotocol.io) server for the [Tuma 250](https://tuma250.com) grocery site (Kigali, Rwanda).

Gives any MCP-compatible AI client (Cursor, Claude Desktop, etc.) the ability to search products, manage a shopping cart, and browse order history on Tuma250 — using a headless Playwright browser under the hood.

## Example uses

### Imported as MCP server in Perplexity (or any other MCP-compatible client)

![Tuma250 MCP diagram](docs/tuma-mcp.png)

### Imported as a skill in [OpenClaw](https://openclaw.ai/)

The skill definition can be copied from [`skills/tuma250/SKILL.md`](skills/tuma250/SKILL.md) (requires the `mcporter` skill to be enabled, and the MCP server added to its configuration)

![Tuma250 Skill](docs/tuma-skill.png)

## Tools

| Tool | Description |
|------|-------------|
| `login` | Authenticate and persist the browser session |
| `search_products` | Search for products by keyword |
| `get_product_variations` | List available variants (size/weight) for a variable product |
| `add_to_cart` | Add a product (or specific variant) to the cart |
| `get_cart` | Retrieve cart contents with full cost breakdown |
| `list_recent_orders` | List recent orders from My Account |
| `get_order_details` | Fetch line items for a specific order |

## Prerequisites

### Playwright with one headless browser

```bash
npm i -g playwright
playwright install chromium
```

## Configuration

The server reads credentials from environment variables (or a `.env` file):

```env
TUMA250_BASE_URL=https://tuma250.com
TUMA250_USERNAME=your-email@example.com
TUMA250_PASSWORD=your-password

# Optional
TUMA250_SESSION_FILE=.tuma250_session.json  # persists login between runs
TUMA250_DEBUG=false                          # set true for headed browser
```

## Usage

### Cursor / Claude Desktop

Add to `~/.cursor/mcp.json` / `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "tuma250": {
      "command": "uvx",
      "args": ["tuma250-mcp"],
      "env": {
        "TUMA250_BASE_URL": "https://tuma250.com",
        "TUMA250_USERNAME": "your-email@example.com",
        "TUMA250_PASSWORD": "your-password"
      }
    }
  }
}
```

### Direct (stdio)

```bash
pip install tuma250-mcp
TUMA250_USERNAME=you@example.com TUMA250_PASSWORD=secret tuma250-mcp
```

## Session persistence

After the first successful login, the browser session (cookies) is saved to `TUMA250_SESSION_FILE` (default: `.tuma250_session.json`). Subsequent runs reuse the saved session and skip the login step entirely.

## Variable products

Some products on Tuma250 require a size/weight selection before they can be added to the cart. Pass the product slug (from `search_products` or `get_order_details`) and optionally `variation_attributes`:

```
1. search_products("fresh carrots")          → returns slug in each result
2. get_product_variations(product_url)       → lists 250g / 500g / 1kg variants
3. add_to_cart(product_slug, quantity=1, variation_attributes={"attribute_quantity": "500g"})
```

## Development

```bash
# Clone and setup
uv venv
source .venv/bin/activate   # or: .venv\Scripts\activate on Windows
uv pip install -e ".[dev]"
playwright install chromium

# Run tests
pytest -v
```

Copy `config-example.env` to `.env` and fill in your Tuma250 credentials before running tests or the server locally.

To test from command line, you may use `mcporter`, e.g.:

```bash
npx mcporter call --stdio "uv run tuma250-mcp" get_cart
npx mcporter call --stdio "uv run tuma250-mcp" 'tuma250.get_order_details(order_id: "193457")'
npx mcporter call --stdio "uv run tuma250-mcp" 'tuma250.add_to_cart(product_slug: "ripe-mango-fruit-1kg")'
npx mcporter call --stdio "uv run tuma250-mcp" add_to_cart --args '{"product_slug": "viande-hachee-de-bouef-ordinaire-regular-ground-beef", "variation_attributes": {"attribute_weight":"1kg"}}'
```

## License

MIT