Metadata-Version: 2.4
Name: tuma250-mcp
Version: 0.1.4
Summary: MCP server for the Tuma250 grocery site (Kigali, Rwanda)
Author-email: Yann Jouanique <yann.jouanique@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Yann-J/tuma250_mcp
Project-URL: Repository, https://github.com/Yann-J/tuma250_mcp
Project-URL: Bug Tracker, https://github.com/Yann-J/tuma250_mcp/issues
Keywords: mcp,grocery,tuma250,rwanda,kigali,ecommerce
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2.0,>=1.26
Requires-Dist: playwright<2.0,>=1.51
Requires-Dist: pydantic<3.0,>=2.0
Requires-Dist: pydantic-settings<3.0,>=2.13
Requires-Dist: python-dotenv<2.0,>=1.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Dynamic: license-file

# 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.

![Tuma250 MCP diagram](docs/tuma-mcp.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. Use `get_product_variations` to discover the available options first:

```
1. search_products("fresh carrots")          → returns product URL
2. get_product_variations(product_url)       → lists 250g / 500g / 1kg variants
3. add_to_cart(product_id, variation_id, variation_attributes)
```

## 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.

## License

MIT
