aetherx-mcp 0.1.0__tar.gz

aetherx_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aether-X
+
+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.

aetherx_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: aetherx-mcp
+Version: 0.1.0
+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-oracle
+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 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).

aetherx_mcp-0.1.0/README.md

@@ -0,0 +1,84 @@
+# 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).

aetherx_mcp-0.1.0/aetherx_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Aether-X Oracle MCP server package."""
+from aetherx_mcp.server import mcp
+
+__all__ = ["mcp"]
+__version__ = "0.1.0"

aetherx_mcp-0.1.0/aetherx_mcp/server.py

@@ -0,0 +1,120 @@
+"""Aether-X Oracle MCP server.
+
+Exposes the Aether-X Port Congestion Oracle to MCP-compatible agents
+(Claude Desktop, Cursor, VS Code, custom LLM agents).
+
+Run (stdio):
+
+    RAPIDAPI_KEY=xxxx aetherx-mcp
+
+By default it calls the public production API. When ``RAPIDAPI_KEY`` is set,
+requests are routed through the RapidAPI gateway (metered billing).
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Any
+
+import httpx
+from mcp.server.mcpserver import MCPServer
+
+PRODUCTION_URL = "https://aether-x-oracle-production.up.railway.app"
+DEFAULT_RAPIDAPI_HOST = "aether-x-port-congestion-oracle.p.rapidapi.com"
+
+SUPPORTED_PORTS: list[dict[str, str]] = [
+    {"port_id": "AEDXB", "port_name": "Dubai / Jebel Ali", "country": "EAU"},
+    {"port_id": "BRRIO", "port_name": "Rio de Janeiro", "country": "Brasil"},
+    {"port_id": "BRSSZ", "port_name": "Santos", "country": "Brasil"},
+    {"port_id": "CNNGB", "port_name": "Ningbo-Zhoushan", "country": "China"},
+    {"port_id": "CNSHA", "port_name": "Shanghai", "country": "China"},
+    {"port_id": "DEHAM", "port_name": "Hamburg", "country": "Alemanha"},
+    {"port_id": "GBLGP", "port_name": "London Gateway", "country": "Reino Unido"},
+    {"port_id": "KRPUS", "port_name": "Busan", "country": "Coreia do Sul"},
+    {"port_id": "MPTNG", "port_name": "Tanger Med", "country": "Marrocos"},
+    {"port_id": "MXZLO", "port_name": "Manzanillo", "country": "México"},
+    {"port_id": "NLRTM", "port_name": "Rotterdam", "country": "Holanda"},
+    {"port_id": "SGSIN", "port_name": "Singapore", "country": "Cingapura"},
+    {"port_id": "USLAX", "port_name": "Los Angeles", "country": "EUA"},
+    {"port_id": "USNYC", "port_name": "New York", "country": "EUA"},
+    {"port_id": "ZACPT", "port_name": "Cape Town", "country": "África do Sul"},
+]
+
+mcp = MCPServer(
+    "aetherx-oracle",
+    title="Aether-X Port Congestion Oracle",
+    description=(
+        "Predictive port congestion signals for global trade, supply chain and "
+        "quantitative finance."
+    ),
+    instructions=(
+        "Predictive port congestion signals for global trade, supply chain and "
+        "quantitative finance. Use get_port_risk for a single port and "
+        "get_ports_risk to scan a portfolio of ports in parallel."
+    ),
+    version="0.1.0",
+    website_url="https://aether-x-oracle-production.up.railway.app",
+)
+
+
+def _base_url() -> str:
+    return os.getenv("AETHERX_BASE_URL", PRODUCTION_URL).rstrip("/")
+
+
+def _headers() -> dict[str, str]:
+    key = os.getenv("RAPIDAPI_KEY")
+    if not key:
+        return {}
+    return {
+        "X-RapidAPI-Key": key,
+        "X-RapidAPI-Host": os.getenv("RAPIDAPI_HOST", DEFAULT_RAPIDAPI_HOST),
+    }
+
+
+def _client() -> httpx.AsyncClient:
+    return httpx.AsyncClient(timeout=30.0)
+
+
+async def _fetch(port_id: str) -> dict[str, Any]:
+    url = f"{_base_url()}/v1/port-risk"
+    async with _client() as client:
+        resp = await client.get(
+            url, params={"port_id": port_id}, headers=_headers()
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+
+@mcp.tool()
+async def get_port_risk(port_id: str) -> dict[str, Any]:
+    """Return the predictive congestion signal for a single port.
+
+    Args:
+        port_id: UN/LOCODE of the port, e.g. "BRSSZ" (Santos), "CNSHA" (Shanghai).
+    """
+    return await _fetch(port_id.strip().upper())
+
+
+@mcp.tool()
+async def get_ports_risk(port_ids: list[str]) -> list[dict[str, Any]]:
+    """Return congestion signals for several ports in parallel.
+
+    Args:
+        port_ids: list of UN/LOCODEs, e.g. ["BRSSZ", "CNSHA", "NLRTM"].
+    """
+    ids = [p.strip().upper() for p in port_ids if p and p.strip()]
+    return list(await asyncio.gather(*(_fetch(p) for p in ids)))
+
+
+@mcp.tool()
+def list_supported_ports() -> list[dict[str, str]]:
+    """List the 15 ports pre-seeded in the oracle (id, name, country)."""
+    return SUPPORTED_PORTS
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

aetherx_mcp-0.1.0/aetherx_mcp.egg-info/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: aetherx-mcp
+Version: 0.1.0
+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-oracle
+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 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).

aetherx_mcp-0.1.0/aetherx_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+aetherx_mcp/__init__.py
+aetherx_mcp/server.py
+aetherx_mcp.egg-info/PKG-INFO
+aetherx_mcp.egg-info/SOURCES.txt
+aetherx_mcp.egg-info/dependency_links.txt
+aetherx_mcp.egg-info/entry_points.txt
+aetherx_mcp.egg-info/requires.txt
+aetherx_mcp.egg-info/top_level.txt
+tests/test_server.py

aetherx_mcp-0.1.0/aetherx_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

aetherx_mcp-0.1.0/aetherx_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+aetherx-mcp = aetherx_mcp.server:main

aetherx_mcp-0.1.0/aetherx_mcp.egg-info/requires.txt

@@ -0,0 +1,6 @@
+mcp<3,>=2.0.0
+httpx>=0.24.0
+
+[test]
+pytest>=7.0
+pytest-asyncio>=0.23

aetherx_mcp-0.1.0/aetherx_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+aetherx_mcp

aetherx_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=77.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aetherx-mcp"
+version = "0.1.0"
+description = "MCP server for the Aether-X Port Congestion Oracle API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Aether-X" }]
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "port",
+    "congestion",
+    "shipping",
+    "logistics",
+    "quant",
+    "agents",
+    "llm",
+]
+dependencies = [
+    "mcp>=2.0.0,<3",
+    "httpx>=0.24.0",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7.0", "pytest-asyncio>=0.23"]
+
+[project.scripts]
+aetherx-mcp = "aetherx_mcp.server:main"
+
+[project.urls]
+Homepage = "https://aether-x-oracle-production.up.railway.app"
+Repository = "https://github.com/belegante-byte/aetherx-oracle"
+Documentation = "https://aether-x-oracle-production.up.railway.app/docs"
+Terms = "https://aether-x-oracle-production.up.railway.app/terms"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["aetherx_mcp*"]

aetherx_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aetherx_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,59 @@
+import asyncio
+
+import httpx
+
+from aetherx_mcp import server
+
+
+def _mock_transport() -> httpx.MockTransport:
+    def handler(request: httpx.Request) -> httpx.Response:
+        port = request.url.params.get("port_id", "")
+        return httpx.Response(
+            200,
+            json={
+                "port_id": port,
+                "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",
+            },
+        )
+
+    return httpx.MockTransport(handler)
+
+
+def test_list_supported_ports_returns_fifteen() -> None:
+    ports = server.list_supported_ports()
+    assert len(ports) == 15
+    assert any(p["port_id"] == "BRSSZ" for p in ports)
+
+
+def test_get_port_risk_normalizes_locode(monkeypatch) -> None:
+    transport = _mock_transport()
+    monkeypatch.setattr(
+        server, "_client", lambda: httpx.AsyncClient(transport=transport)
+    )
+    result = asyncio.run(server.get_port_risk(" brssz "))
+    assert result["port_id"] == "BRSSZ"
+    assert result["congestion_score"] == 0.78
+
+
+def test_get_ports_risk_batch(monkeypatch) -> None:
+    transport = _mock_transport()
+    monkeypatch.setattr(
+        server, "_client", lambda: httpx.AsyncClient(transport=transport)
+    )
+    results = asyncio.run(server.get_ports_risk(["BRSSZ", "CNSHA", "NLRTM"]))
+    assert [r["port_id"] for r in results] == ["BRSSZ", "CNSHA", "NLRTM"]
+
+
+def test_rapidapi_headers_only_when_key_present(monkeypatch) -> None:
+    monkeypatch.delenv("RAPIDAPI_KEY", raising=False)
+    assert server._headers() == {}
+    monkeypatch.setenv("RAPIDAPI_KEY", "secret")
+    headers = server._headers()
+    assert headers["X-RapidAPI-Key"] == "secret"
+    assert "X-RapidAPI-Host" in headers