# WooCommerce Connector

A read-only connector for merchant order, customer, and inventory workflows. It exposes REST endpoints and MCP tools backed by a WooCommerce REST API key, without requiring a model-provider key.

## Scope

- Read and search orders, order notes, customers, and products; summarize low stock and sales.
- Authenticate with a dedicated WooCommerce consumer key/secret. External stores must use HTTPS.
- Expose tools through an MCP stdio server and a machine-readable specification at [`mcp_spec/tool_spec.json`](mcp_spec/tool_spec.json).
- Handle upstream throttling and transient failures with a Redis-backed token bucket, bounded retries, and a circuit breaker.

The connector performs reads only. It does not create or modify products, orders, payments, or customers. See [capabilities and limits](CAPABILITIES.md) and the [merchant workflow](docs/MERCHANT_WORKFLOW.md).

## Configure

Create a WooCommerce REST API key for a dedicated user with **Read** permission. Keep the consumer key and secret private.

```powershell
if (-not (Test-Path .env)) { Copy-Item .env.example .env }
```

Edit `.env` and set `WOO_BASE_URL`, `WOO_CONSUMER_KEY`, and `WOO_CONSUMER_SECRET`. Use the store origin (for example, `https://shop.example.com`), not the REST endpoint path. Do not commit `.env` or paste credentials into issues or logs.

## Run

Start Redis, install the dependencies, and run the connector on the host. Running the connector on the host also allows WooCommerce Local domains and locally trusted CA certificates to work without container-specific network configuration.

```powershell
docker compose up -d redis
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m uvicorn src.app:app --host 127.0.0.1 --port 8000
```

Open `http://localhost:8000/docs` for the REST API. Health endpoints are `/health`, `/health/woocommerce`, and `/health/redis`.

## Interfaces

- `GET /api/orders`, `/api/orders/{id}`, and `/api/orders/{id}/notes`
- `GET /api/products` and `/api/products/{id}`
- `GET /api/customers`, `/api/customers/{id}`, and `/api/customers/{id}/orders`
- `GET /api/tools/` lists the allowlisted operations; `POST /api/tools/{name}/execute` runs one.
- MCP stdio exposes the same ten read tools. The canonical input schemas are in `mcp_spec/tool_spec.json`.

For a read-only smoke check, use an existing product ID from your store:

```powershell
Invoke-RestMethod 'http://localhost:8000/api/products?per_page=5'
Invoke-RestMethod 'http://localhost:8000/api/products/PRODUCT_ID'
```

To run the MCP server, stop the REST process and start it from the same repository and environment:

```powershell
.\.venv\Scripts\python.exe -m src.mcp.server
```

Configure an MCP-compatible client to launch `.venv\Scripts\python.exe` with arguments `-m src.mcp.server` and this repository as its working directory. The MCP server uses stdio; do not write logs to stdout.

## Test

Tests use isolated in-process transports and do not need store credentials or customer data.

```powershell
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\ruff.exe check src tests
```

## Operational Boundaries

The API is intended for local evaluation and has no caller authentication or tenant isolation. Keep it bound to loopback; do not expose it publicly without adding an authentication and authorization layer. Responses may contain merchant customer data, so restrict access and logs. Redis caching can return stale results. Low-stock and sales summaries inspect at most 100 records; neither is a replenishment recommendation or a complete large-catalog report. No merchant pilot or business impact is claimed.

See [architecture](docs/ARCHITECTURE.md) for request flow. The repository is MIT licensed; see [LICENSE](LICENSE).