Metadata-Version: 2.4
Name: tuma250-mcp
Version: 0.1.9
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

[![PyPI version](https://badge.fury.io/py/tuma250-mcp.svg)](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](https://raw.githubusercontent.com/Yann-J/tuma250_mcp/main/docs/tuma-mcp.png)

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

The skill definition can be copied from [`skills/tuma250/SKILL.md`](https://github.com/Yann-J/tuma250_mcp/main/skills/tuma250/SKILL.md) (requires the `mcporter` skill to be enabled, and the MCP server added to its configuration)

![Tuma250 Skill](https://raw.githubusercontent.com/Yann-J/tuma250_mcp/main/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
