# Deftship MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) server for the
[Deftship](https://deftship.com) multi-carrier shipping API. It lets any MCP-capable AI
client (Claude Desktop, Claude Code, Cursor, Codex CLI, and others) quote, ship, track,
void and manage shipments in natural language using your Deftship API token.

## What it can do

The full shipping lifecycle is exposed as tools:

| Domain | Tools |
| --- | --- |
| **Parcel** | get rates, create draft, ship, void, get/track, merge labels, mark as shipped, list e-commerce orders |
| **Freight** | get rates, create draft, ship, void, get/track |
| **Pickup** | get rates, create, arrange, void, get |
| **Insurance** | get rate, book, void |
| **Batch** (beta) | create, add items, remove items, get, ship |
| **Account** | check balance, address book, validate address, service names, carrier status, create ticket |

A typical flow: `deftship_get_parcel_rates` → choose a `rate_id` → `deftship_ship_parcel`
→ `deftship_get_parcel` to fetch the label and track it.

## Safety guardrails

Because an AI agent can drive this end to end, spending is deliberately hard to do by accident:

- **Sandbox by default.** With `DEFTSHIP_ENV=sandbox` (the default) every operation runs
  against the isolated sandbox with a $10,000 dummy balance and never touches production.
  Going live is a deliberate one-line change.
- **Explicit confirmation.** Every tool that spends your balance or is irreversible
  (`ship`, `void`, `book_insurance`, `arrange_pickup`, `ship_batch`) refuses to run unless
  called with `"confirm": true`, forcing the agent to surface the action to you first.
- **Honest tool hints.** Read-only tools are marked `readOnlyHint`; spending tools are
  marked `destructiveHint`, so clients can prompt for approval.

## Setup

### 1. Get an API token

Generate a **sandbox** token from your Deftship organisation's
[API page](https://app.deftship.com/organisation/api). Use sandbox while you test; switch
to a production token only when you are ready to spend real money.

### 2. Configure your MCP client

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

```json
{
  "mcpServers": {
    "deftship": {
      "command": "npx",
      "args": ["-y", "@deftship/mcp"],
      "env": {
        "DEFTSHIP_API_TOKEN": "bearer-your-token-here",
        "DEFTSHIP_ENV": "sandbox"
      }
    }
  }
}
```

**Codex CLI** (`~/.codex/config.toml`):

```toml
[mcp_servers.deftship]
command = "npx"
args = ["-y", "@deftship/mcp"]
env = { DEFTSHIP_API_TOKEN = "bearer-your-token-here", DEFTSHIP_ENV = "sandbox" }
```

**Cursor** (`.cursor/mcp.json`): same shape as the Claude example above.

### Environment variables

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `DEFTSHIP_API_TOKEN` | yes | — | Your Deftship API token. |
| `DEFTSHIP_ENV` | no | `sandbox` | `sandbox` or `production`. Determines the API URL. |

## Local development

```bash
npm install
npm run build      # compile TypeScript to dist/
npm run dev        # watch mode
DEFTSHIP_API_TOKEN=bearer-... npm start
```

The server speaks MCP over stdio. Do not write anything to stdout in tool code — stdout
carries the JSON-RPC stream; diagnostics go to stderr.

## Project structure

```
src/
  config.ts        env parsing, sandbox/production base URL resolution
  http.ts          fetch wrapper: auth, error + rate-limit normalization
  schemas.ts       shared Zod schemas (address, package, item, ...)
  server.ts        assembles the server and registers all tool modules
  index.ts         stdio entry point
  tools/
    helpers.ts     registration wrapper, confirm gate, result formatting
    parcel.ts freight.ts pickup.ts insurance.ts batch.ts account.ts
```

Tool schemas mirror the field tables in the official Deftship developer docs.

## License

MIT