Metadata-Version: 2.4
Name: aetherx-mcp
Version: 0.1.1
Summary: MCP server for the Aether-X Port Congestion Oracle API
Author: Aether-X
License-Expression: MIT
Project-URL: Homepage, https://aether-x-oracle-production.up.railway.app
Project-URL: Repository, https://github.com/belegante-byte/aetherx-mcp
Project-URL: Documentation, https://aether-x-oracle-production.up.railway.app/docs
Project-URL: Terms, https://aether-x-oracle-production.up.railway.app/terms
Keywords: mcp,model-context-protocol,port,congestion,shipping,logistics,quant,agents,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<3,>=2.0.0
Requires-Dist: httpx>=0.24.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"
Dynamic: license-file

# aetherx-mcp

<!-- mcp-name: io.github.belegante-byte/aetherx-mcp -->

**MCP server for the [Aether-X Port Congestion Oracle](https://aether-x-oracle-production.up.railway.app)** — gives any MCP-compatible agent (Claude Desktop, Cursor, VS Code, custom LLM agents) predictive port congestion signals for global trade and quantitative finance.

## Install

```bash
pip install aetherx-mcp
# or run without installing (recommended for MCP clients):
uvx aetherx-mcp
```

## Configure your MCP client

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "aetherx-oracle": {
      "command": "uvx",
      "args": ["aetherx-mcp"],
      "env": { "RAPIDAPI_KEY": "SUA_RAPIDAPI_KEY" }
    }
  }
}
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "aetherx-oracle": {
      "command": "uvx",
      "args": ["aetherx-mcp"],
      "env": { "RAPIDAPI_KEY": "SUA_RAPIDAPI_KEY" }
    }
  }
}
```

## Tools

| Tool | Arguments | Returns |
|------|-----------|---------|
| `get_port_risk` | `port_id` (UN/LOCODE) | Congestion score, ETA delay, waiting vessels, freight volatility |
| `get_ports_risk` | `port_ids` (list) | Same, for a whole portfolio, fetched in parallel |
| `list_supported_ports` | — | The 15 pre-seeded ports (id, name, country) |

Every response is a typed payload:

```json
{
  "port_id": "BRSSZ",
  "port_name": "Santos",
  "country": "Brasil",
  "congestion_score": 0.78,
  "eta_delay_days": 1.6,
  "waiting_vessels": 12,
  "freight_volatility_index": 0.42,
  "updated_at": "2026-09-17 15:46:53"
}
```

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `RAPIDAPI_KEY` | — | When set, requests are routed through the RapidAPI gateway (metered billing) |
| `RAPIDAPI_HOST` | `aether-x-port-congestion-oracle.p.rapidapi.com` | RapidAPI host |
| `AETHERX_BASE_URL` | `https://aether-x-oracle-production.up.railway.app` | Direct API base URL |

Without `RAPIDAPI_KEY`, the server calls the public production API directly.

## Example agent prompts

- *"What's the congestion risk at Santos right now?"*
- *"Rank these ports by congestion: BRSSZ, CNSHA, NLRTM, USLAX."*
- *"Which of my Asian ports has the highest freight volatility index?"*

## License

MIT — see [LICENSE](LICENSE). The signals are provided "AS IS" and do not constitute investment advice. See the [Terms of Service](https://aether-x-oracle-production.up.railway.app/terms).
