# logiwa-mcp-server

An [MCP](https://modelcontextprotocol.io) server for the **Logiwa IO (WMS)** API. It lets MCP clients
(Claude Desktop, Claude Code, etc.) work with your Logiwa warehouse data through well-described tools:
products, inventory, shipment/purchase/return orders, warehouses & locations, customers/vendors/retailers,
key reports, and reference lookups.

- **Language / transport:** TypeScript · stdio
- **API base:** `https://myapi.logiwa.com` (override with `LOGIWA_BASE_URL`)
- **Auth:** JWT bearer — fetched from email/password, or a pre-issued token
- **Tools:** 32 (see [Tools](#tools))

Built with the [`mcp-builder`](https://github.com/anthropics/skills/tree/main/skills/mcp-builder) skill.

---

## Prerequisites

- **Node.js ≥ 18**
- A **Logiwa IO account.** Each user authenticates with their own credentials (email/password or a pre-issued JWT). The server calls the Logiwa API on behalf of whoever's credentials are configured — **no credentials are bundled in this repo**, so every user must supply their own.

## Setup

```bash
git clone https://github.com/cgtykctn/Logiwa-IO-WMS--MCP-.git
cd Logiwa-IO-WMS--MCP-
npm install
npm run build
```

Then verify the build without needing credentials:

```bash
node dist/index.js --list-tools   # prints the 32 registered tools
```

## Authentication

The server authenticates with a JWT bearer token. Provide credentials via environment variables
(see [`.env.example`](./.env.example)):

| Variable | Description |
|---|---|
| `LOGIWA_EMAIL` + `LOGIWA_PASSWORD` | **Recommended.** The server `POST`s these to `/v3.1/Authorize/token`, caches the returned JWT in memory, and re-authenticates automatically on a 401. |
| `LOGIWA_API_TOKEN` | A pre-issued JWT. If set, it takes precedence and no login call is made. |
| `LOGIWA_BASE_URL` | Optional. API base URL (default `https://myapi.logiwa.com`). |
| `LOGIWA_TIMEOUT_MS` | Optional. Per-request timeout in ms (default `30000`). |

Credentials are read from the process environment only — nothing is written to disk or logged.

## Register with an MCP client

> Replace `/absolute/path/to/Logiwa-IO-WMS--MCP-` with the real path where you cloned the repo, and use **your own** Logiwa email/password. The server runs locally (stdio) alongside your MCP client — each user installs and configures it on their own machine.

### Claude Code (CLI)

```bash
claude mcp add logiwa \
  --env LOGIWA_EMAIL=you@example.com \
  --env LOGIWA_PASSWORD=your-password \
  -- node "/absolute/path/to/Logiwa-IO-WMS--MCP-/dist/index.js"
```

### Claude Desktop

Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "logiwa": {
      "command": "node",
      "args": ["/absolute/path/to/Logiwa-IO-WMS--MCP-/dist/index.js"],
      "env": {
        "LOGIWA_EMAIL": "you@example.com",
        "LOGIWA_PASSWORD": "your-password"
      }
    }
  }
}
```

Restart the client after editing. Tools then appear under the `logiwa` server.

## Tools

All list/report tools paginate with `page` (1-based) and `page_size` (≤200), and accept
`response_format` (`markdown` default, or `json` for full structured data). Logiwa's list endpoints
paginate by page index only (no server-side text filter), so page through results or use a `get`/`lookup`
tool when you already know an identifier. Write tools expose the API's required fields plus an
`additional_fields` escape hatch for any other Logiwa body field.

**Products** — `logiwa_list_products`, `logiwa_get_product`, `logiwa_create_product`, `logiwa_update_product`
**Inventory** — `logiwa_list_inventory`, `logiwa_add_inventory`, `logiwa_adjust_inventory`, `logiwa_remove_inventory`, `logiwa_transfer_inventory`
**Shipment orders** — `logiwa_list_shipment_orders`, `logiwa_get_shipment_order`, `logiwa_create_shipment_order`, `logiwa_update_shipment_order`, `logiwa_cancel_shipment_order`, `logiwa_ship_shipment_orders`
**Purchase orders** — `logiwa_list_purchase_orders`, `logiwa_get_purchase_order`, `logiwa_create_purchase_order`, `logiwa_receive_purchase_order`
**Return orders** — `logiwa_list_return_orders`, `logiwa_create_return_order`, `logiwa_cancel_return_order`
**Warehouses** — `logiwa_list_warehouses`, `logiwa_list_warehouse_locations`
**Partners** — `logiwa_list_customers`, `logiwa_list_vendors`, `logiwa_list_retailers`
**Reports** — `logiwa_report_total_inventory`, `logiwa_report_shipment_history`, `logiwa_report_receiving_history`, `logiwa_report_available_to_promise`
**Lookups** — `logiwa_lookup` (clients, warehouses, types, reasons, carriers, …)

> Tip: start with `logiwa_lookup` to resolve the `clientIdentifier`, type names, and currency ids that
> the create/update tools require.

## Development

```bash
npm run dev          # tsx watch (auto-reload)
npm run build        # tsc -> dist/
npm start            # node dist/index.js
npx @modelcontextprotocol/inspector node dist/index.js   # interactive testing
```

## Project structure

```
src/
├── index.ts              # entry point: wires up tools, stdio transport, --list-tools
├── constants.ts          # base URL, limits, defaults
├── types.ts              # response envelope types
├── registry.ts           # registerTool wrapper that records tool names
├── services/
│   ├── client.ts         # auth (token fetch + cache + 401 retry) and HTTP
│   └── format.ts         # list/object formatting, pagination, truncation, error messages
├── schemas/
│   └── common.ts         # shared Zod fragments (pagination, line items, packing)
└── tools/                # one file per domain
    ├── products.ts  inventory.ts  shipmentOrders.ts  purchaseOrders.ts
    ├── returnOrders.ts  warehouses.ts  partners.ts  reports.ts  helpers.ts
    └── simpleList.ts     # factory for simple read-only list tools
```

## Scope & notes

- Covers the **core** Logiwa domains (the API has 200+ endpoints). Niche areas — robotics, billing,
  count plans, warehouse tasks, webhooks, data-setup CRUD, user/role admin — are intentionally omitted
  from this first version and can be added the same way.
- Destructive operations (`*_cancel_*`, `*_remove_*`, `*_adjust_*`) are flagged with `destructiveHint`.
- For Logiwa field references, see the developer docs at <https://mydeveloper.logiwa.com/> and the
  Swagger UI at <https://myapi.logiwa.com/swagger/index.html>.

## License

Licensed under the [Apache License 2.0](./LICENSE).