# kitcommerce-mcp

A standalone [Model Context Protocol](https://modelcontextprotocol.io) server that
exposes the **admin** side of `kitcommerce-api` as MCP tools, so an AI assistant
(Claude Desktop, Claude Code, Cursor, …) can manage a store: products,
categories, collections, coupons, orders, inventory, customers and dashboard.

It talks to the API over HTTP — it does **not** import the API code — so it can
point at any deployment (local, staging, prod) via environment variables.

## How it works

- Transport: **stdio** (spawned by the MCP client).
- Auth: sends the admin **API key** as the `authorization` header (matched
  against `ApiKey.secret` in the API) and the store id as `x-litekart-store`.
- Tools are a curated CRUD set over the core commerce entities (see below).

## Setup

```bash
cd mcp
npm install
npm run build
```

Configure credentials (copy `.env.example` for reference — the MCP client
supplies these as `env`, see below):

| Variable                | Description                                              |
| ----------------------- | -------------------------------------------------------- |
| `KITCOMMERCE_API_URL`   | Base URL of the API, e.g. `https://api.litekart.in`      |
| `KITCOMMERCE_API_KEY`   | Admin API key secret (sent as `authorization`)           |
| `KITCOMMERCE_STORE_ID`  | Store id (sent as `x-litekart-store`)                    |

Create the API key in the admin **API keys** section; it is tied to a store and
a user/role, which determines what the MCP server is allowed to do.

## Register with an MCP client

### Claude Desktop / Claude Code (`claude_desktop_config.json` or `.mcp.json`)

```json
{
  "mcpServers": {
    "kitcommerce": {
      "command": "node",
      "args": ["D:/projects/lk/kitcommerce-api/mcp/dist/index.js"],
      "env": {
        "KITCOMMERCE_API_URL": "http://localhost:3000",
        "KITCOMMERCE_API_KEY": "your_admin_api_key_secret",
        "KITCOMMERCE_STORE_ID": "your_store_id"
      }
    }
  }
}
```

For local development you can skip the build and run from source with `tsx`:

```json
{
  "command": "npx",
  "args": ["tsx", "D:/projects/lk/kitcommerce-api/mcp/src/index.ts"]
}
```

## Tools

| Group       | Tools                                                                             |
| ----------- | --------------------------------------------------------------------------------- |
| Products    | `list_products`, `get_product`, `create_product`, `update_product`, `delete_product`, `bulk_update_product_status` |
| Categories  | `list_categories`, `get_category`, `create_category`, `update_category`, `delete_category` |
| Collections | `list_collections`, `get_collection`, `create_collection`, `update_collection`, `delete_collection` |
| Coupons     | `list_coupons`, `get_coupon`, `create_coupon`, `update_coupon`, `delete_coupon`   |
| Orders      | `list_orders`, `get_order`, `update_order`                                         |
| Inventory   | `list_inventory`, `get_inventory`, `update_inventory`                              |
| Customers   | `list_customers`, `get_customer`                                                   |
| Dashboard   | `get_dashboard_summary`                                                            |

`list_*` tools accept `page`, `page_size`, `search`, `sort`, `status`, and a
free-form `filters` object for any additional query params. `create_*` /
`update_*` accept a `data` object sent as the JSON body — call the matching
`get_*` on an existing record first to learn the exact field shape.

## Extending

Tools are declared in `src/tools.ts`. Add a resource with the `crud()` helper or
push a bespoke `ToolDef`. Keep the set curated — most MCP clients cap the number
of tools they will load.