Metadata-Version: 2.4
Name: cargoeffe-mcp
Version: 0.1.2
Summary: MCP server for CargoEffe — AI-powered cargo loading plan design
Author: dollob studio
License: MIT
Keywords: ai,cargo,loading,logistics,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# CargoEffe MCP Server

Connect AI assistants (Claude Desktop, Claude Code, Cursor) to CargoEffe for automated cargo loading plan design.

## Installation

```bash
# Option A: pip install
pip install cargoeffe-mcp

# Option B: uvx (no pre-install needed)
uvx cargoeffe-mcp

# Option C: from source
git clone https://github.com/dollob/cargoeffe-mcp.git
cd cargoeffe-mcp && pip install -e .
```

## Setup

1. Get your MCP token from CargoEffe Settings → MCP Tokens
2. Configure your AI client:

### Claude Code

```json
{
  "mcpServers": {
    "cargoeffe": {
      "command": "uvx",
      "args": ["cargoeffe-mcp"],
      "env": {
        "CARGOEFFE_API_URL": "https://api.dollob.com",
        "CARGOEFFE_MCP_TOKEN": "cfm_YOUR_TOKEN_HERE"
      }
    }
  }
}
```

### Claude Desktop

Add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "cargoeffe": {
      "command": "python",
      "args": ["-m", "cargoeffe_mcp.server"],
      "env": {
        "CARGOEFFE_API_URL": "https://api.dollob.com",
        "CARGOEFFE_MCP_TOKEN": "cfm_YOUR_TOKEN_HERE"
      }
    }
  }
}
```

## Debug Mode

Set `CARGOEFFE_MCP_DEBUG=true` for verbose logging:

```json
{
  "env": {
    "CARGOEFFE_API_URL": "https://api.dollob.com",
    "CARGOEFFE_MCP_TOKEN": "cfm_...",
    "CARGOEFFE_MCP_DEBUG": "true"
  }
}
```

Debug logs appear on stderr (visible in Claude Code's MCP debug panel).

## Available Tools

| Tool | Description |
|---|---|
| `get_context` | Read CargoEffe system context (coordinates, rules) — free |
| `get_axle_templates` | List axle templates with weight limits — free |
| `plan_create` | Create a new load plan |
| `plan_load` | Load plan by ID |
| `plan_list` | List your plans |
| `plan_save` | Save plan to backend |
| `container_list` | List available containers |
| `container_set` | Set container for a plan |
| `cargo_add` | Add cargo items (bulk) |
| `cargo_list` | List cargo items |
| `cargo_update` | Update cargo properties |
| `cargo_remove` | Delete cargo + placements |
| `group_create` | Create loading group |
| `group_list` | List loading groups |
| `group_update` | Rename/reorder groups |
| `save_placements` | Save AI-calculated placements |
| `weight_check` | Get weight distribution analysis |

## Security

This package is a thin protocol bridge — it contains NO business logic, database queries, or API secrets. All sensitive operations happen on the CargoEffe backend.

## License

MIT
