iotamine-mcp 0.1.0__tar.gz

iotamine_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,54 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  test:
+    name: Run tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - run: python -m pip install -e ".[dev]"
+      - run: pytest
+
+  build:
+    name: Build distribution
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/iotamine-mcp
+    permissions:
+      # The whole point of trusted publishing — this lets GitHub Actions
+      # prove its identity to PyPI via OIDC (matching the "pending
+      # publisher" configured at pypi.org/manage/account/publishing/:
+      # repo=piyushladhar/iotamine-mcp, workflow=publish.yml,
+      # environment=pypi) with no API token stored anywhere at all.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

iotamine_mcp-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/

iotamine_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: iotamine-mcp
+Version: 0.1.0
+Summary: MCP server for the Iotamine cloud VPS platform — inspect your VPS instances, billing, and infrastructure from any MCP-compatible client (Claude Desktop, Claude Code, Cursor, ...).
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# iotamine-mcp
+
+An [MCP](https://modelcontextprotocol.io) server for the [Iotamine](https://iotamine.com) cloud VPS
+platform. Connect it to Claude Desktop, Claude Code, Cursor, or any other MCP-compatible client to
+let it read your VPS instances, billing, quota, and infrastructure directly.
+
+This is a thin, read-only wrapper around the real Iotamine REST API — the exact same API your
+[dashboard](https://iotamine.com/control) already uses. It doesn't duplicate any account logic,
+store any of your data, or run any service of its own; it just translates MCP tool calls into
+ordinary API requests on your behalf, using your own API key.
+
+**Every tool in this server is read-only.** Nothing here can start, stop, create, resize, or
+destroy a VPS, or spend money. (Write actions are planned for a future release, gated behind a
+separate `read_write`-scoped key — see [Scopes](#scopes) below.)
+
+## Setup
+
+### 1. Get an API key
+
+From your [Iotamine dashboard](https://iotamine.com/control/api_keys) → API Keys → Create Key.
+Leave the scope as **Read-only** — that's all this server needs.
+
+### 2. Install and run
+
+Using [`uv`](https://docs.astral.sh/uv/) (recommended — no separate install step):
+
+```bash
+uvx iotamine-mcp
+```
+
+Or with `pip`:
+
+```bash
+pip install iotamine-mcp
+iotamine-mcp
+```
+
+### 3. Add it to your MCP client
+
+**Claude Code:**
+
+```bash
+claude mcp add iotamine uvx --args iotamine-mcp --env IOTAMINE_API_KEY="your-key-here"
+```
+
+**Claude Desktop / Cursor** (`claude_desktop_config.json` or your client's equivalent):
+
+```json
+{
+  "mcpServers": {
+    "iotamine": {
+      "command": "uvx",
+      "args": ["iotamine-mcp"],
+      "env": {
+        "IOTAMINE_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+Set `IOTAMINE_API_KEY` as an environment variable in your client's config, not hardcoded anywhere
+else — the same rule any API key deserves.
+
+## Tools
+
+| Tool | What it returns |
+|---|---|
+| `list_vps` | Every VPS instance on the account |
+| `get_vps` | Full detail for one VPS by id |
+| `get_quota` | Resource limits, current usage, and tier |
+| `get_account_balance` | Wallet balance and basic profile |
+| `list_invoices` | Every invoice, most recent first |
+| `get_usage_billing` | Current unbilled usage + historical billed cost |
+| `list_os_images` | Available operating systems |
+| `list_regions` | Available Points of Presence |
+| `list_ip_addresses` | Every standalone IP address on the account |
+| `list_volumes` | Every standalone storage volume on the account |
+| `list_ssh_keys` | Every SSH key saved on the account |
+
+## Scopes
+
+An Iotamine API key has a `scope` — **read-only** (default) or **read & write**. This server only
+ever needs a read-only key. If you paste a read & write key instead, nothing changes: every tool
+here still only ever sends `GET` requests.
+
+## Configuration
+
+| Environment variable | Required | Default |
+|---|---|---|
+| `IOTAMINE_API_KEY` | Yes | — |
+| `IOTAMINE_API_URL` | No | `https://iotamine.com/api/` |
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```

iotamine_mcp-0.1.0/README.md

@@ -0,0 +1,100 @@
+# iotamine-mcp
+
+An [MCP](https://modelcontextprotocol.io) server for the [Iotamine](https://iotamine.com) cloud VPS
+platform. Connect it to Claude Desktop, Claude Code, Cursor, or any other MCP-compatible client to
+let it read your VPS instances, billing, quota, and infrastructure directly.
+
+This is a thin, read-only wrapper around the real Iotamine REST API — the exact same API your
+[dashboard](https://iotamine.com/control) already uses. It doesn't duplicate any account logic,
+store any of your data, or run any service of its own; it just translates MCP tool calls into
+ordinary API requests on your behalf, using your own API key.
+
+**Every tool in this server is read-only.** Nothing here can start, stop, create, resize, or
+destroy a VPS, or spend money. (Write actions are planned for a future release, gated behind a
+separate `read_write`-scoped key — see [Scopes](#scopes) below.)
+
+## Setup
+
+### 1. Get an API key
+
+From your [Iotamine dashboard](https://iotamine.com/control/api_keys) → API Keys → Create Key.
+Leave the scope as **Read-only** — that's all this server needs.
+
+### 2. Install and run
+
+Using [`uv`](https://docs.astral.sh/uv/) (recommended — no separate install step):
+
+```bash
+uvx iotamine-mcp
+```
+
+Or with `pip`:
+
+```bash
+pip install iotamine-mcp
+iotamine-mcp
+```
+
+### 3. Add it to your MCP client
+
+**Claude Code:**
+
+```bash
+claude mcp add iotamine uvx --args iotamine-mcp --env IOTAMINE_API_KEY="your-key-here"
+```
+
+**Claude Desktop / Cursor** (`claude_desktop_config.json` or your client's equivalent):
+
+```json
+{
+  "mcpServers": {
+    "iotamine": {
+      "command": "uvx",
+      "args": ["iotamine-mcp"],
+      "env": {
+        "IOTAMINE_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+Set `IOTAMINE_API_KEY` as an environment variable in your client's config, not hardcoded anywhere
+else — the same rule any API key deserves.
+
+## Tools
+
+| Tool | What it returns |
+|---|---|
+| `list_vps` | Every VPS instance on the account |
+| `get_vps` | Full detail for one VPS by id |
+| `get_quota` | Resource limits, current usage, and tier |
+| `get_account_balance` | Wallet balance and basic profile |
+| `list_invoices` | Every invoice, most recent first |
+| `get_usage_billing` | Current unbilled usage + historical billed cost |
+| `list_os_images` | Available operating systems |
+| `list_regions` | Available Points of Presence |
+| `list_ip_addresses` | Every standalone IP address on the account |
+| `list_volumes` | Every standalone storage volume on the account |
+| `list_ssh_keys` | Every SSH key saved on the account |
+
+## Scopes
+
+An Iotamine API key has a `scope` — **read-only** (default) or **read & write**. This server only
+ever needs a read-only key. If you paste a read & write key instead, nothing changes: every tool
+here still only ever sends `GET` requests.
+
+## Configuration
+
+| Environment variable | Required | Default |
+|---|---|---|
+| `IOTAMINE_API_KEY` | Yes | — |
+| `IOTAMINE_API_URL` | No | `https://iotamine.com/api/` |
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```

iotamine_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "iotamine-mcp"
+version = "0.1.0"
+description = "MCP server for the Iotamine cloud VPS platform — inspect your VPS instances, billing, and infrastructure from any MCP-compatible client (Claude Desktop, Claude Code, Cursor, ...)."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "mcp>=2.0,<3",
+    "httpx>=0.27",
+]
+
+[project.scripts]
+iotamine-mcp = "iotamine_mcp.__main__:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "respx>=0.21",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/iotamine_mcp"]

iotamine_mcp-0.1.0/src/iotamine_mcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

iotamine_mcp-0.1.0/src/iotamine_mcp/__main__.py

@@ -0,0 +1,25 @@
+import sys
+
+from iotamine_mcp.client import IotamineConfigError
+from iotamine_mcp.server import build_server
+
+
+def main():
+    try:
+        mcp, client = build_server()
+    except IotamineConfigError as exc:
+        # A clear, early failure on stderr — most MCP clients don't
+        # surface a crashed server's own stderr nicely, but anyone
+        # running this by hand to debug it (the whole point of it being
+        # a plain local process) still deserves a real message instead
+        # of every tool call failing one at a time with a 401.
+        print(f"iotamine-mcp: {exc}", file=sys.stderr)
+        sys.exit(1)
+    try:
+        mcp.run(transport="stdio")
+    finally:
+        client.close()
+
+
+if __name__ == "__main__":
+    main()

iotamine_mcp-0.1.0/src/iotamine_mcp/client.py

@@ -0,0 +1,99 @@
+"""Thin wrapper around the real Iotamine REST API (iotamine_backend_django)
+— every tool in iotamine_mcp.tools goes through this, and nothing here
+duplicates any business logic the backend already owns. Auth is a plain
+Iotamine API key (core.authentications.APIKeyAuthentication), sent the
+same way any other REST client already sends one.
+"""
+import os
+
+import httpx
+
+DEFAULT_BASE_URL = "https://iotamine.com/api/"
+
+
+class IotamineConfigError(Exception):
+    """Raised at startup when IOTAMINE_API_KEY isn't set — a clear,
+    early failure instead of every tool call failing with a confusing
+    401 one at a time."""
+
+
+class IotamineAPIError(Exception):
+    """Wraps a non-2xx response from the real API. `message` is the
+    backend's own {"message": ...} (or {"error": ...}) body when it sent
+    one — always shown to the model as-is rather than a generic
+    "something went wrong", since it's already written to be a clear,
+    actionable string (see e.g. core.views's own KYC/VPS error
+    messages)."""
+
+    def __init__(self, status_code, message):
+        super().__init__(f"{status_code}: {message}")
+        self.status_code = status_code
+        self.message = message
+
+
+def _extract_message(response):
+    try:
+        data = response.json()
+    except ValueError:
+        return response.text[:500] or f"HTTP {response.status_code}"
+    if isinstance(data, dict):
+        return data.get("message") or data.get("error") or data.get("detail") or str(data)
+    return str(data)
+
+
+class IotamineClient:
+    """One instance per server process — httpx.Client is safe to reuse
+    across calls, unlike creating a fresh connection per tool call."""
+
+    def __init__(self, api_key=None, base_url=None):
+        self.api_key = api_key or os.environ.get("IOTAMINE_API_KEY")
+        if not self.api_key:
+            raise IotamineConfigError(
+                "IOTAMINE_API_KEY is not set. Generate an API key from your Iotamine "
+                "dashboard (Account -> API Keys) and set it as an environment variable "
+                "in your MCP client's config for this server."
+            )
+        self.base_url = (base_url or os.environ.get("IOTAMINE_API_URL") or DEFAULT_BASE_URL).rstrip("/") + "/"
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers={"Authorization": f"Api-Key {self.api_key}", "Accept": "application/json"},
+            timeout=httpx.Timeout(connect=10, read=60, write=15, pool=10),
+        )
+
+    def close(self):
+        self._client.close()
+
+    def _request(self, method, path, *, params=None, json=None):
+        try:
+            response = self._client.request(method, path.lstrip("/"), params=params, json=json)
+        except httpx.RequestError as exc:
+            raise IotamineAPIError(None, f"Could not reach the Iotamine API: {exc}") from exc
+        if response.status_code == 401:
+            raise IotamineAPIError(401, "This API key is invalid, inactive, or IP-restricted. Check it on your Iotamine dashboard's API Keys page.")
+        if response.status_code == 403:
+            raise IotamineAPIError(403, _extract_message(response) or "This API key doesn't have permission for this action — it may be read-only (see APIKey.scope on your dashboard).")
+        if not response.is_success:
+            raise IotamineAPIError(response.status_code, _extract_message(response))
+        if not response.content:
+            return None
+        return response.json()
+
+    def get(self, path, params=None):
+        return self._request("GET", path, params=params)
+
+    def post(self, path, json=None):
+        return self._request("POST", path, json=json)
+
+    def get_list(self, path, params=None):
+        """Normalizes the two list shapes the real API actually returns
+        (see individual view comments — some endpoints always paginate,
+        some only conditionally): a plain JSON array, or DRF's
+        {count, next, previous, results} envelope. Callers always get a
+        plain list back either way — an MCP tool has no use for a
+        pagination cursor a model can't act on."""
+        data = self.get(path, params=params)
+        if isinstance(data, dict) and "results" in data:
+            return data["results"]
+        if isinstance(data, list):
+            return data
+        return [] if data is None else [data]

iotamine_mcp-0.1.0/src/iotamine_mcp/server.py

@@ -0,0 +1,24 @@
+"""Builds the MCP server: one MCPServer instance, one IotamineClient,
+every tools.* module registers its own tools against both. No tool
+logic lives in this file — see iotamine_mcp/tools/ for that."""
+from mcp.server.mcpserver import MCPServer
+
+from iotamine_mcp.client import IotamineClient
+from iotamine_mcp.tools import billing, infra, vps
+
+INSTRUCTIONS = (
+    "Tools for managing your Iotamine cloud VPS account: listing and inspecting VPS "
+    "instances, checking quota/balance/invoices/usage, and viewing OS images, regions, "
+    "IP addresses, volumes, and SSH keys. Every tool in this server is read-only — "
+    "nothing here can start, stop, create, resize, or destroy anything, or spend money. "
+    "Data comes directly from the same API https://iotamine.com's own dashboard uses."
+)
+
+
+def build_server(client=None):
+    mcp = MCPServer(name="iotamine", title="Iotamine Cloud", instructions=INSTRUCTIONS)
+    client = client or IotamineClient()
+    vps.register(mcp, client)
+    billing.register(mcp, client)
+    infra.register(mcp, client)
+    return mcp, client

iotamine_mcp-0.1.0/src/iotamine_mcp/tools/billing.py

@@ -0,0 +1,34 @@
+"""Billing/account read tools — quota, balance, invoices, usage."""
+from mcp.types import ToolAnnotations
+
+READ_ONLY = ToolAnnotations(read_only_hint=True, idempotent_hint=True, open_world_hint=False)
+
+
+def register(mcp, client):
+    @mcp.tool(annotations=READ_ONLY)
+    def get_quota() -> dict:
+        """This account's resource limits (VPS count / vCPU / RAM / disk
+        / IP caps), current usage against each, and its current tier —
+        core.quotas's balance-driven tier system, exactly what the
+        dashboard's own Tier page shows."""
+        return client.get("account/quota/")
+
+    @mcp.tool(annotations=READ_ONLY)
+    def get_account_balance() -> dict:
+        """This account's current wallet balance, currency, and basic
+        profile (name, email, country, verification status)."""
+        return client.get("users/me/")
+
+    @mcp.tool(annotations=READ_ONLY)
+    def list_invoices() -> list:
+        """List every invoice on this account (paid, unpaid, and
+        cancelled), most recent first — amount, status, due date, and
+        line items."""
+        return client.get_list("invoices/", params={"page_size": 100})
+
+    @mcp.tool(annotations=READ_ONLY)
+    def get_usage_billing() -> dict:
+        """Current unbilled usage (a live snapshot) plus historical
+        already-billed cost broken down by Compute/Storage/Network/Other
+        — the same data the dashboard's own Usage Billing page shows."""
+        return client.get("usage-billing/overview/")

iotamine_mcp-0.1.0/src/iotamine_mcp/tools/infra.py

@@ -0,0 +1,39 @@
+"""Infrastructure inventory tools — everything else a VPS is built from
+or attached to: OS images, regions, IPs, volumes, SSH keys.
+"""
+from mcp.types import ToolAnnotations
+
+READ_ONLY = ToolAnnotations(read_only_hint=True, idempotent_hint=True, open_world_hint=False)
+
+
+def register(mcp, client):
+    @mcp.tool(annotations=READ_ONLY)
+    def list_os_images() -> list:
+        """List every operating system image available to deploy a VPS
+        with (name, distro, virtualization type)."""
+        return client.get_list("os/", params={"page_size": 200})
+
+    @mcp.tool(annotations=READ_ONLY)
+    def list_regions() -> list:
+        """List every Point of Presence (region/data-center location)
+        VPS instances can be deployed in."""
+        return client.get_list("pop/", params={"page_size": 200})
+
+    @mcp.tool(annotations=READ_ONLY)
+    def list_ip_addresses() -> list:
+        """List every standalone IP address on this account (attached
+        to a VPS or not), independent of any VPS — see how a boot
+        volume/IP can be detached and reattached on Iotamine."""
+        return client.get_list("ip-addresses/", params={"page_size": 200})
+
+    @mcp.tool(annotations=READ_ONLY)
+    def list_volumes() -> list:
+        """List every standalone storage volume on this account
+        (attached to a VPS or not, boot or non-boot)."""
+        return client.get_list("volumes/", params={"page_size": 200})
+
+    @mcp.tool(annotations=READ_ONLY)
+    def list_ssh_keys() -> list:
+        """List every SSH public key saved on this account (title only
+        — the public key material itself, never anything private)."""
+        return client.get_list("sshkey/", params={"page_size": 200})

iotamine_mcp-0.1.0/src/iotamine_mcp/tools/vps.py

@@ -0,0 +1,24 @@
+"""VPS read tools — thin passthroughs to vps.views.VPSViewSet. Response
+shapes are whatever VPSSerializer already returns; nothing here
+re-derives or reshapes them, so they never drift out of sync with the
+real API.
+"""
+from mcp.types import ToolAnnotations
+
+READ_ONLY = ToolAnnotations(read_only_hint=True, idempotent_hint=True, open_world_hint=False)
+
+
+def register(mcp, client):
+    @mcp.tool(annotations=READ_ONLY)
+    def list_vps() -> list:
+        """List every VPS instance on this Iotamine account — hostname,
+        status, specs (cores/ram/disk/traffic), IP addresses, OS, node
+        location, and machine_status (Running/Stopped/Building/...) for
+        each one."""
+        return client.get_list("vps/", params={"all": "true"})
+
+    @mcp.tool(annotations=READ_ONLY)
+    def get_vps(vps_id: str) -> dict:
+        """Get full detail for one VPS instance by its id (a UUID, as
+        returned by list_vps's own "id" field)."""
+        return client.get(f"vps/{vps_id}/")

iotamine_mcp-0.1.0/tests/conftest.py

@@ -0,0 +1,19 @@
+from unittest.mock import MagicMock
+
+import pytest
+
+from iotamine_mcp.server import build_server
+
+
+@pytest.fixture
+def fake_client():
+    """A MagicMock standing in for IotamineClient — every tool test
+    asserts against how it was called, not real HTTP (test_client.py's
+    respx-based tests already cover the real request/response shapes)."""
+    return MagicMock()
+
+
+@pytest.fixture
+def mcp_server(fake_client):
+    mcp, _ = build_server(client=fake_client)
+    return mcp

iotamine_mcp-0.1.0/tests/test_client.py

@@ -0,0 +1,92 @@
+import httpx
+import pytest
+import respx
+
+from iotamine_mcp.client import IotamineAPIError, IotamineClient, IotamineConfigError
+
+
+def test_missing_api_key_raises_a_clear_config_error(monkeypatch):
+    monkeypatch.delenv("IOTAMINE_API_KEY", raising=False)
+    with pytest.raises(IotamineConfigError, match="IOTAMINE_API_KEY"):
+        IotamineClient()
+
+
+def test_default_base_url_is_the_real_production_api():
+    client = IotamineClient(api_key="k")
+    assert client.base_url == "https://iotamine.com/api/"
+    client.close()
+
+
+def test_base_url_override_via_env(monkeypatch):
+    monkeypatch.setenv("IOTAMINE_API_URL", "http://127.0.0.1:8003/api")
+    client = IotamineClient(api_key="k")
+    assert client.base_url == "http://127.0.0.1:8003/api/"
+    client.close()
+
+
+@respx.mock
+def test_get_sends_the_api_key_header():
+    route = respx.get("https://iotamine.com/api/vps/").mock(
+        return_value=httpx.Response(200, json=[])
+    )
+    client = IotamineClient(api_key="my-secret-key")
+    client.get("vps/")
+    client.close()
+    assert route.called
+    assert route.calls.last.request.headers["Authorization"] == "Api-Key my-secret-key"
+
+
+@respx.mock
+def test_401_raises_a_clear_invalid_key_message():
+    respx.get("https://iotamine.com/api/vps/").mock(return_value=httpx.Response(401))
+    client = IotamineClient(api_key="bad-key")
+    with pytest.raises(IotamineAPIError) as exc_info:
+        client.get("vps/")
+    client.close()
+    assert exc_info.value.status_code == 401
+    assert "API Keys page" in exc_info.value.message
+
+
+@respx.mock
+def test_403_surfaces_the_backends_real_message():
+    respx.post("https://iotamine.com/api/sshkey/").mock(
+        return_value=httpx.Response(403, json={"message": "This API key is read-only. Generate a read & write key to perform this action."})
+    )
+    client = IotamineClient(api_key="ro-key")
+    with pytest.raises(IotamineAPIError) as exc_info:
+        client.post("sshkey/", json={"title": "x"})
+    client.close()
+    assert exc_info.value.status_code == 403
+    assert "read-only" in exc_info.value.message
+
+
+@respx.mock
+def test_network_failure_is_wrapped_not_raised_raw():
+    respx.get("https://iotamine.com/api/vps/").mock(side_effect=httpx.ConnectError("refused"))
+    client = IotamineClient(api_key="k")
+    with pytest.raises(IotamineAPIError) as exc_info:
+        client.get("vps/")
+    client.close()
+    assert "Could not reach" in exc_info.value.message
+
+
+@respx.mock
+def test_get_list_unwraps_a_paginated_envelope():
+    respx.get("https://iotamine.com/api/invoices/").mock(
+        return_value=httpx.Response(200, json={"count": 2, "next": None, "previous": None, "results": [{"id": 1}, {"id": 2}]})
+    )
+    client = IotamineClient(api_key="k")
+    result = client.get_list("invoices/")
+    client.close()
+    assert result == [{"id": 1}, {"id": 2}]
+
+
+@respx.mock
+def test_get_list_passes_through_a_plain_array():
+    respx.get("https://iotamine.com/api/vps/").mock(
+        return_value=httpx.Response(200, json=[{"id": "a"}, {"id": "b"}])
+    )
+    client = IotamineClient(api_key="k")
+    result = client.get_list("vps/")
+    client.close()
+    assert result == [{"id": "a"}, {"id": "b"}]

iotamine_mcp-0.1.0/tests/test_tools.py

@@ -0,0 +1,87 @@
+import json
+
+import pytest
+
+
+def _texts(result):
+    """Every tool test just needs to see what got returned, not fight
+    the SDK's own content-block framing (a list-returning tool comes
+    back as one TextContent block per item; a dict-returning tool comes
+    back as one block holding the whole object)."""
+    return [json.loads(block.text) for block in result.content]
+
+
+@pytest.mark.asyncio
+async def test_list_vps_calls_the_right_endpoint_with_all_true(mcp_server, fake_client):
+    fake_client.get_list.return_value = [{"id": "v1"}]
+    result = await mcp_server.call_tool("list_vps", {})
+    fake_client.get_list.assert_called_once_with("vps/", params={"all": "true"})
+    assert _texts(result) == [{"id": "v1"}]
+
+
+@pytest.mark.asyncio
+async def test_get_vps_passes_the_id_into_the_path(mcp_server, fake_client):
+    fake_client.get.return_value = {"id": "v1", "hostname": "box"}
+    result = await mcp_server.call_tool("get_vps", {"vps_id": "v1"})
+    fake_client.get.assert_called_once_with("vps/v1/")
+    assert _texts(result) == [{"id": "v1", "hostname": "box"}]
+
+
+@pytest.mark.asyncio
+async def test_get_quota(mcp_server, fake_client):
+    fake_client.get.return_value = {"tier": "Tier 2"}
+    result = await mcp_server.call_tool("get_quota", {})
+    fake_client.get.assert_called_once_with("account/quota/")
+    assert _texts(result) == [{"tier": "Tier 2"}]
+
+
+@pytest.mark.asyncio
+async def test_get_account_balance_hits_users_me(mcp_server, fake_client):
+    fake_client.get.return_value = {"balance": "42.00"}
+    result = await mcp_server.call_tool("get_account_balance", {})
+    fake_client.get.assert_called_once_with("users/me/")
+    assert _texts(result) == [{"balance": "42.00"}]
+
+
+@pytest.mark.asyncio
+async def test_list_invoices(mcp_server, fake_client):
+    fake_client.get_list.return_value = [{"id": 1}]
+    result = await mcp_server.call_tool("list_invoices", {})
+    fake_client.get_list.assert_called_once_with("invoices/", params={"page_size": 100})
+    assert _texts(result) == [{"id": 1}]
+
+
+@pytest.mark.asyncio
+async def test_get_usage_billing(mcp_server, fake_client):
+    fake_client.get.return_value = {"unbilled": 5.0}
+    result = await mcp_server.call_tool("get_usage_billing", {})
+    fake_client.get.assert_called_once_with("usage-billing/overview/")
+    assert _texts(result) == [{"unbilled": 5.0}]
+
+
+@pytest.mark.parametrize("tool_name,path", [
+    ("list_os_images", "os/"),
+    ("list_regions", "pop/"),
+    ("list_ip_addresses", "ip-addresses/"),
+    ("list_volumes", "volumes/"),
+    ("list_ssh_keys", "sshkey/"),
+])
+@pytest.mark.asyncio
+async def test_infra_list_tools_hit_the_right_endpoint(mcp_server, fake_client, tool_name, path):
+    fake_client.get_list.return_value = [{"id": 1}]
+    result = await mcp_server.call_tool(tool_name, {})
+    fake_client.get_list.assert_called_once_with(path, params={"page_size": 200})
+    assert _texts(result) == [{"id": 1}]
+
+
+@pytest.mark.asyncio
+async def test_every_registered_tool_is_marked_read_only(mcp_server):
+    """The whole point of Phase 1 shipping read-only-only: nothing here
+    should ever be annotated otherwise, or a client that trusts
+    readOnlyHint could let a model call it without confirmation."""
+    tools = await mcp_server.list_tools()
+    assert len(tools) == 11
+    for tool in tools:
+        assert tool.annotations is not None
+        assert tool.annotations.read_only_hint is True
+        assert not tool.annotations.destructive_hint