# woocommerce-mcp

Private MCP connector for one WooCommerce store, selected as the merchant tool for the project brief. It is intended for an Agent Studio-compatible MCP host; registration in Agent Studio and a real-store pilot are not yet complete.

| Deliverable | Source of truth | Verification |
|---|---|---|
| API-key authentication | `src/config.ts`, `src/client.ts` | `npm test` |
| Read and optional write tools | `src/tools.ts` | `npm test` |
| Rate-limit and retry handling | `src/client.ts` | `npm test` |
| MCP tool specification | `docs/tool-spec.json` | `npm run spec` |
| Agent capabilities and limits | `docs/CONNECTOR.md` | `npm test` |

## What it is

The connector exposes WooCommerce REST API operations through MCP. It uses a consumer key and consumer secret with HTTP Basic authentication. Read tools are available by default; write tools are registered only when `WOO_ALLOW_WRITES=true`.

## Quick start

Install and build:

```sh
npm ci
npm run build
```

### Local stdio

Set the variables from `.env.example` in the process environment, then run:

```sh
npm start
```

### Hosted HTTP

Start the server with:

```sh
npm run start:http
```

It exposes `GET /healthz` and `POST /mcp`. Each MCP request must provide `x-woo-store-url`, `x-woo-consumer-key`, and `x-woo-consumer-secret`. Credentials are passed per request and are not stored server-side. Set `PORT` to change the default port `3000`.

### Docker

```sh
docker build -t woocommerce-mcp .
docker run --rm -p 3000:3000 \
  -e WOO_STORE_URL=https://your-store.example.com \
  -e WOO_CONSUMER_KEY=ck_xxxxxxxx \
  -e WOO_CONSUMER_SECRET=cs_xxxxxxxx \
  woocommerce-mcp
```

The Docker image runs the hosted HTTP entry point.

## Demo and checks

`npm run demo` builds the project and runs a scripted flow against the built-in mock store; it needs no credentials. `npm run demo:store` starts only that mock store, defaulting to port `8080`, so it can be used by an external MCP client. Set `PORT` if that port is occupied.

```sh
npm test
npm run spec
npm run demo
npm run demo:store
```

## Configuration

| Variable | Required | Default | Purpose |
|---|---:|---:|---|
| `WOO_STORE_URL` | yes for stdio | none | WooCommerce store URL; HTTPS is required except configured local HTTP |
| `WOO_CONSUMER_KEY` | yes for stdio | none | WooCommerce REST API consumer key |
| `WOO_CONSUMER_SECRET` | yes for stdio | none | WooCommerce REST API consumer secret |
| `WOO_ALLOW_WRITES` | no | `false` | Register the four write tools when `true` |
| `WOO_ALLOW_INSECURE_LOCALHOST` | no | unset | Allow HTTP only for `localhost` or `127.0.0.1` when `1` |
| `WOO_MIN_INTERVAL_MS` | no | `250` | Minimum interval between store requests |
| `WOO_MAX_RETRIES` | no | `4` | Maximum retries for retryable requests |
| `WOO_DEADLINE_MS` | no | `30000` | Per-call request deadline in milliseconds |

Hosted HTTP receives store credentials through request headers instead of these three credential variables. `PORT` controls the HTTP and mock-store listeners and defaults to `3000` for HTTP or `8080` for the mock store.

## Limitations and next steps

Agent Studio registration has not yet been done. A real-store pilot has not yet been done. The demos use a mock store. The connector does not provide deletes, refunds, payments, webhooks, analytics, or bulk operations; see `docs/CONNECTOR.md` for the complete tool contract.