Metadata-Version: 2.5
Name: colleag-mcp-ups
Version: 0.1.0
Summary: MCP server for UPS shipping: rate shopping, tracking, landed cost — on your own UPS account
Project-URL: Homepage, https://colleag.ai
Project-URL: Source, https://github.com/colleag-ai/mcp-ups
Author-email: "Colleag.ai (CargoBeacon AB)" <support@cargobeacon.com>
License: MIT License
        
        Copyright (c) 2026 Colleag.ai
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: logistics,mcp,model-context-protocol,shipping,ups
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2.0.0,>=1.26.0
Requires-Dist: pydantic>=2.5
Description-Content-Type: text/markdown

# colleag-mcp-ups

An [MCP](https://modelcontextprotocol.io) server for **UPS shipping**, running
against **your own UPS account**: rate shopping with negotiated prices,
live tracking (with an interactive [MCP Apps](https://modelcontextprotocol.io/seps/1865-mcp-apps-interactive-user-interfaces-for-mcp)
card), and landed-cost estimates for international shipments.

Built by [Colleag.ai](https://colleag.ai), a CargoBeacon AB company. Works with any MCP host —
Colleag.ai, Claude Desktop, VS Code, or your own client.

> **Read-only by design (v0.1).** This release quotes, tracks and estimates —
> it never books shipments or spends money. Side-effecting tools (booking,
> pickup scheduling) will follow once host-side human-in-the-loop
> confirmation conventions are settled; a host, not a connector, should own
> the "are you sure?" step for actions that cost money.

## Tools

| Tool | What it does |
|---|---|
| `get_rates` | Compare every available UPS service on a lane (or price one `service_code`) with negotiated account prices and estimated delivery dates |
| `track_shipment` | Current status, delivery estimate and scan history for a tracking number. Ships an MCP Apps tracking card for hosts that support the `io.modelcontextprotocol/ui` extension |
| `landed_cost` | Duties, VAT and brokerage estimate for an international shipment (per-commodity lines, incoterm-aware) |

## Setup

1. Create an app on [developer.ups.com](https://developer.ups.com) (*"I want
   to integrate UPS technology into my business"*) and enable the Rating,
   Tracking and Landed Cost products. This gives you a Client ID and Secret
   tied to your UPS account.
2. Configure environment variables:

```bash
UPS_CLIENT_ID=...          # required
UPS_CLIENT_SECRET=...      # required, secret
UPS_ACCOUNT_NUMBER=...     # required — your 6-character shipper number
UPS_ENVIRONMENT=test       # 'test' (CIE sandbox, default) or 'production'
SHIP_FROM_NAME="Acme AB"   # optional defaults for the quoting origin
SHIP_FROM_ADDRESS="Industrigatan 1"
SHIP_FROM_CITY=Stockholm
SHIP_FROM_POSTAL_CODE="112 46"
SHIP_FROM_COUNTRY=SE
SHIP_FROM_PHONE="+468..."
```

3. Run:

```bash
uv run colleag-mcp-ups            # stdio (default)
MCP_TRANSPORT=streamable-http uv run colleag-mcp-ups   # HTTP
```

### Claude Desktop

```json
{
  "mcpServers": {
    "ups": {
      "command": "uvx",
      "args": ["colleag-mcp-ups"],
      "env": {
        "UPS_CLIENT_ID": "...",
        "UPS_CLIENT_SECRET": "...",
        "UPS_ACCOUNT_NUMBER": "...",
        "UPS_ENVIRONMENT": "test"
      }
    }
  }
}
```

### Try it without credentials

`npx @modelcontextprotocol/inspector uv run colleag-mcp-ups` lists the tools
and the `ui://colleag-mcp-ups/tracking-card` resource; calls will return a
structured configuration error until UPS credentials are set.

## Notes

- **Access tokens** are cached per `expires_in` (UPS cut lifetimes to 1 h in
  April 2026 — never hardcode refresh intervals).
- **Rate limits** are not published by UPS; the server surfaces HTTP 429 as a
  structured `UPS_RATE_LIMITED` error for the host to back off on.
- **Tracking retention**: UPS purges tracking data after ~120 days; keep your
  own shipment history if you need longer memory.
- The MCP Apps tracking card is rendered by the host in a sandboxed iframe;
  hosts without the UI extension simply use the JSON tool result.

## License

MIT — see [LICENSE](LICENSE).
