spotgpu-mcp 0.1.0__tar.gz

spotgpu_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: spotgpu-mcp
+Version: 0.1.0
+Summary: SpotGPU MCP server — spot GPU rental prices via GET /v1/spot
+Author: SpotGPU
+License-Expression: MIT
+Project-URL: Homepage, https://spotgpu-api.fly.dev
+Project-URL: Documentation, https://spotgpu-api.fly.dev/docs
+Keywords: mcp,gpu,spot,pricing,vast,runpod
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp<3,>=2
+Requires-Dist: httpx>=0.27.0
+
+# spotgpu-mcp
+
+MCP (Model Context Protocol) server for [SpotGPU](https://spotgpu-api.fly.dev) spot GPU rental prices.
+
+Exposes one tool: **`spot_price`** → `GET /v1/spot` (Vast + RunPod best + alts).
+
+> **Credits ≠ rental.** SpotGPU API credits pay for price lookups.  
+> **`usd_per_hr` is the upstream provider rental price**, not a SpotGPU fee.
+
+<!-- mcp-name: io.github.flowtestpro-svg/spotgpu-mcp -->
+
+## Install / run
+
+Requires Python 3.10+ and a SpotGPU API key (`sk_…` from https://spotgpu-api.fly.dev).
+
+### One-shot (after PyPI publish)
+
+```bash
+uvx spotgpu-mcp
+```
+
+### Local (this monorepo package)
+
+```bash
+cd packages/mcp-spotgpu
+uv sync   # or: pip install -e .
+export SPOTGPU_API_KEY=sk_…
+spotgpu-mcp
+```
+
+Env:
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `SPOTGPU_API_KEY` | **yes** | — |
+| `SPOTGPU_BASE_URL` | no | `https://spotgpu-api.fly.dev` |
+
+Never hardcode keys. The server speaks MCP on **stdio** only (do not print to stdout).
+
+## Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "spotgpu": {
+      "command": "uvx",
+      "args": ["spotgpu-mcp"],
+      "env": {
+        "SPOTGPU_API_KEY": "sk_…"
+      }
+    }
+  }
+}
+```
+
+Local editable install instead of `uvx`:
+
+```json
+{
+  "mcpServers": {
+    "spotgpu": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/spotgpu/packages/mcp-spotgpu", "spotgpu-mcp"],
+      "env": {
+        "SPOTGPU_API_KEY": "sk_…"
+      }
+    }
+  }
+}
+```
+
+## Cursor
+
+Add to `.cursor/mcp.json` (or user MCP config):
+
+```json
+{
+  "mcpServers": {
+    "spotgpu": {
+      "command": "uvx",
+      "args": ["spotgpu-mcp"],
+      "env": {
+        "SPOTGPU_API_KEY": "sk_…"
+      }
+    }
+  }
+}
+```
+
+## Tool: `spot_price`
+
+| Param | Type | Default | Notes |
+|-------|------|---------|-------|
+| `gpu` | string | required | e.g. `RTX_4090` |
+| `qty` | int | `1` | ≥ 1 |
+| `markets` | string | `"vast,runpod"` | comma-separated |
+| `fresh` | bool | `false` | maps to `fresh=1` |
+
+On success returns JSON text of the API body (`best.usd_per_hr`, `alts`, …).
+
+## Attribution
+
+Requests send `X-SpotGPU-Client: mcp-spotgpu`.
+
+## Not published yet
+
+PyPI / Official MCP Registry / Smithery / Glama publish is deferred until Biz Bot approval. `server.json` and `glama.json` stubs are in this package for later.

spotgpu_mcp-0.1.0/README.md

@@ -0,0 +1,109 @@
+# spotgpu-mcp
+
+MCP (Model Context Protocol) server for [SpotGPU](https://spotgpu-api.fly.dev) spot GPU rental prices.
+
+Exposes one tool: **`spot_price`** → `GET /v1/spot` (Vast + RunPod best + alts).
+
+> **Credits ≠ rental.** SpotGPU API credits pay for price lookups.  
+> **`usd_per_hr` is the upstream provider rental price**, not a SpotGPU fee.
+
+<!-- mcp-name: io.github.flowtestpro-svg/spotgpu-mcp -->
+
+## Install / run
+
+Requires Python 3.10+ and a SpotGPU API key (`sk_…` from https://spotgpu-api.fly.dev).
+
+### One-shot (after PyPI publish)
+
+```bash
+uvx spotgpu-mcp
+```
+
+### Local (this monorepo package)
+
+```bash
+cd packages/mcp-spotgpu
+uv sync   # or: pip install -e .
+export SPOTGPU_API_KEY=sk_…
+spotgpu-mcp
+```
+
+Env:
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `SPOTGPU_API_KEY` | **yes** | — |
+| `SPOTGPU_BASE_URL` | no | `https://spotgpu-api.fly.dev` |
+
+Never hardcode keys. The server speaks MCP on **stdio** only (do not print to stdout).
+
+## Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "spotgpu": {
+      "command": "uvx",
+      "args": ["spotgpu-mcp"],
+      "env": {
+        "SPOTGPU_API_KEY": "sk_…"
+      }
+    }
+  }
+}
+```
+
+Local editable install instead of `uvx`:
+
+```json
+{
+  "mcpServers": {
+    "spotgpu": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/spotgpu/packages/mcp-spotgpu", "spotgpu-mcp"],
+      "env": {
+        "SPOTGPU_API_KEY": "sk_…"
+      }
+    }
+  }
+}
+```
+
+## Cursor
+
+Add to `.cursor/mcp.json` (or user MCP config):
+
+```json
+{
+  "mcpServers": {
+    "spotgpu": {
+      "command": "uvx",
+      "args": ["spotgpu-mcp"],
+      "env": {
+        "SPOTGPU_API_KEY": "sk_…"
+      }
+    }
+  }
+}
+```
+
+## Tool: `spot_price`
+
+| Param | Type | Default | Notes |
+|-------|------|---------|-------|
+| `gpu` | string | required | e.g. `RTX_4090` |
+| `qty` | int | `1` | ≥ 1 |
+| `markets` | string | `"vast,runpod"` | comma-separated |
+| `fresh` | bool | `false` | maps to `fresh=1` |
+
+On success returns JSON text of the API body (`best.usd_per_hr`, `alts`, …).
+
+## Attribution
+
+Requests send `X-SpotGPU-Client: mcp-spotgpu`.
+
+## Not published yet
+
+PyPI / Official MCP Registry / Smithery / Glama publish is deferred until Biz Bot approval. `server.json` and `glama.json` stubs are in this package for later.

spotgpu_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spotgpu-mcp"
+version = "0.1.0"
+description = "SpotGPU MCP server — spot GPU rental prices via GET /v1/spot"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "SpotGPU" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+keywords = ["mcp", "gpu", "spot", "pricing", "vast", "runpod"]
+dependencies = [
+  "mcp>=2,<3",
+  "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://spotgpu-api.fly.dev"
+Documentation = "https://spotgpu-api.fly.dev/docs"
+
+[project.scripts]
+spotgpu-mcp = "spotgpu_mcp.server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["spotgpu_mcp*"]

spotgpu_mcp-0.1.0/setup.cfg

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

spotgpu_mcp-0.1.0/src/spotgpu_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""SpotGPU MCP thin client (stdio)."""
+
+__version__ = "0.1.0"

spotgpu_mcp-0.1.0/src/spotgpu_mcp/client.py

@@ -0,0 +1,140 @@
+"""Thin httpx client for SpotGPU GET /v1/spot. No app-internal imports."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+import httpx
+
+DEFAULT_BASE_URL = "https://spotgpu-api.fly.dev"
+CLIENT_HEADER = "mcp-spotgpu"
+TIMEOUT_S = 60.0
+
+
+class SpotGPUError(Exception):
+    """Raised for API/config failures; message is safe for MCP tool errors."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+
+def _base_url() -> str:
+    return (os.environ.get("SPOTGPU_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+
+
+def _api_key() -> str:
+    key = os.environ.get("SPOTGPU_API_KEY")
+    if not key or not key.strip():
+        raise SpotGPUError(
+            "Server misconfigured: SPOTGPU_API_KEY not set. "
+            "Set it in your MCP client env (Claude Desktop / Cursor)."
+        )
+    return key.strip()
+
+
+def _detail_snippet(body: Any) -> str:
+    """Extract a short human detail without leaking secrets."""
+    if body is None:
+        return ""
+    if isinstance(body, str):
+        text = body.strip()
+        return f" — {text[:300]}" if text else ""
+    if isinstance(body, dict):
+        for k in ("message", "detail", "error"):
+            v = body.get(k)
+            if isinstance(v, str) and v.strip():
+                return f" — {v.strip()[:300]}"
+            if isinstance(v, list) and v:
+                return f" — {json.dumps(v)[:300]}"
+        # FastAPI validation often nests under detail
+        detail = body.get("detail")
+        if detail is not None:
+            try:
+                return f" — {json.dumps(detail)[:300]}"
+            except (TypeError, ValueError):
+                return f" — {str(detail)[:300]}"
+    try:
+        return f" — {json.dumps(body)[:300]}"
+    except (TypeError, ValueError):
+        return ""
+
+
+def _map_http_error(status: int, body: Any, base: str) -> SpotGPUError:
+    if status == 401:
+        return SpotGPUError(
+            "Invalid or missing API key — check SPOTGPU_API_KEY"
+            + _detail_snippet(body)
+        )
+    if status == 402:
+        return SpotGPUError(
+            f"Insufficient credits — top up at {base}/topup or POST /v1/checkout"
+            + _detail_snippet(body)
+        )
+    if status == 404:
+        return SpotGPUError(
+            "No offers / unknown GPU" + _detail_snippet(body)
+        )
+    if status == 422:
+        return SpotGPUError("Bad params" + _detail_snippet(body))
+    if status in (502, 503):
+        return SpotGPUError(
+            "Upstream markets unavailable — retry later" + _detail_snippet(body)
+        )
+    return SpotGPUError(f"SpotGPU API HTTP {status}" + _detail_snippet(body))
+
+
+def fetch_spot(
+    *,
+    gpu: str,
+    qty: int = 1,
+    markets: str = "vast,runpod",
+    fresh: bool = False,
+) -> dict[str, Any]:
+    """
+    GET {BASE}/v1/spot with Bearer auth.
+
+    Maps fresh=True → query fresh=1. Returns parsed JSON body on 200.
+    """
+    base = _base_url()
+    key = _api_key()
+    params: dict[str, str | int] = {
+        "gpu": gpu,
+        "qty": qty,
+        "markets": markets,
+    }
+    if fresh:
+        params["fresh"] = 1
+
+    headers = {
+        "Authorization": f"Bearer {key}",
+        "Accept": "application/json",
+        "X-SpotGPU-Client": CLIENT_HEADER,
+    }
+    url = f"{base}/v1/spot"
+
+    try:
+        with httpx.Client(timeout=TIMEOUT_S) as client:
+            resp = client.get(url, params=params, headers=headers)
+    except httpx.TimeoutException as exc:
+        raise SpotGPUError("Connection failed to SpotGPU API (timeout)") from exc
+    except httpx.RequestError as exc:
+        raise SpotGPUError("Connection failed to SpotGPU API") from exc
+
+    if resp.status_code == 200:
+        try:
+            data = resp.json()
+        except json.JSONDecodeError as exc:
+            raise SpotGPUError("SpotGPU API returned non-JSON body") from exc
+        if not isinstance(data, dict):
+            raise SpotGPUError("SpotGPU API returned unexpected JSON shape")
+        return data
+
+    body: Any
+    try:
+        body = resp.json()
+    except json.JSONDecodeError:
+        body = resp.text
+    raise _map_http_error(resp.status_code, body, base)

spotgpu_mcp-0.1.0/src/spotgpu_mcp/server.py

@@ -0,0 +1,61 @@
+"""SpotGPU MCP server (stdio only). Never write non-protocol bytes to stdout."""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+
+from mcp.server import MCPServer
+
+from spotgpu_mcp.client import SpotGPUError, fetch_spot
+
+# Stdio MCP: logging must go to stderr only
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(levelname)s %(name)s: %(message)s",
+    stream=sys.stderr,
+)
+log = logging.getLogger("spotgpu_mcp")
+
+mcp = MCPServer("spotgpu")
+
+
+@mcp.tool()
+def spot_price(
+    gpu: str,
+    qty: int = 1,
+    markets: str = "vast,runpod",
+    fresh: bool = False,
+) -> str:
+    """Get SpotGPU spot rental prices (best + alts) for a GPU type.
+
+    Returns JSON from GET /v1/spot including best.usd_per_hr (upstream
+    provider rental price, not a SpotGPU fee). Credits are for API calls,
+    not GPU rental.
+
+    Args:
+        gpu: GPU type, e.g. RTX_4090, RTX_3090, RTX_A6000
+        qty: Number of GPUs (>= 1). Default 1.
+        markets: Comma-separated markets. Default "vast,runpod".
+        fresh: If true, bypass cache (query fresh=1). Default false.
+    """
+    if qty < 1:
+        raise SpotGPUError("Bad params — qty must be >= 1")
+    try:
+        data = fetch_spot(gpu=gpu, qty=qty, markets=markets, fresh=fresh)
+    except SpotGPUError:
+        raise
+    except Exception as exc:  # noqa: BLE001 — surface unexpected as tool error
+        log.exception("spot_price unexpected failure")
+        raise SpotGPUError(f"SpotGPU client error: {exc}") from exc
+    return json.dumps(data, indent=2)
+
+
+def main() -> None:
+    """CLI entry: spotgpu-mcp — stdio transport only."""
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

spotgpu_mcp-0.1.0/src/spotgpu_mcp.egg-info/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: spotgpu-mcp
+Version: 0.1.0
+Summary: SpotGPU MCP server — spot GPU rental prices via GET /v1/spot
+Author: SpotGPU
+License-Expression: MIT
+Project-URL: Homepage, https://spotgpu-api.fly.dev
+Project-URL: Documentation, https://spotgpu-api.fly.dev/docs
+Keywords: mcp,gpu,spot,pricing,vast,runpod
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp<3,>=2
+Requires-Dist: httpx>=0.27.0
+
+# spotgpu-mcp
+
+MCP (Model Context Protocol) server for [SpotGPU](https://spotgpu-api.fly.dev) spot GPU rental prices.
+
+Exposes one tool: **`spot_price`** → `GET /v1/spot` (Vast + RunPod best + alts).
+
+> **Credits ≠ rental.** SpotGPU API credits pay for price lookups.  
+> **`usd_per_hr` is the upstream provider rental price**, not a SpotGPU fee.
+
+<!-- mcp-name: io.github.flowtestpro-svg/spotgpu-mcp -->
+
+## Install / run
+
+Requires Python 3.10+ and a SpotGPU API key (`sk_…` from https://spotgpu-api.fly.dev).
+
+### One-shot (after PyPI publish)
+
+```bash
+uvx spotgpu-mcp
+```
+
+### Local (this monorepo package)
+
+```bash
+cd packages/mcp-spotgpu
+uv sync   # or: pip install -e .
+export SPOTGPU_API_KEY=sk_…
+spotgpu-mcp
+```
+
+Env:
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `SPOTGPU_API_KEY` | **yes** | — |
+| `SPOTGPU_BASE_URL` | no | `https://spotgpu-api.fly.dev` |
+
+Never hardcode keys. The server speaks MCP on **stdio** only (do not print to stdout).
+
+## Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "spotgpu": {
+      "command": "uvx",
+      "args": ["spotgpu-mcp"],
+      "env": {
+        "SPOTGPU_API_KEY": "sk_…"
+      }
+    }
+  }
+}
+```
+
+Local editable install instead of `uvx`:
+
+```json
+{
+  "mcpServers": {
+    "spotgpu": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/spotgpu/packages/mcp-spotgpu", "spotgpu-mcp"],
+      "env": {
+        "SPOTGPU_API_KEY": "sk_…"
+      }
+    }
+  }
+}
+```
+
+## Cursor
+
+Add to `.cursor/mcp.json` (or user MCP config):
+
+```json
+{
+  "mcpServers": {
+    "spotgpu": {
+      "command": "uvx",
+      "args": ["spotgpu-mcp"],
+      "env": {
+        "SPOTGPU_API_KEY": "sk_…"
+      }
+    }
+  }
+}
+```
+
+## Tool: `spot_price`
+
+| Param | Type | Default | Notes |
+|-------|------|---------|-------|
+| `gpu` | string | required | e.g. `RTX_4090` |
+| `qty` | int | `1` | ≥ 1 |
+| `markets` | string | `"vast,runpod"` | comma-separated |
+| `fresh` | bool | `false` | maps to `fresh=1` |
+
+On success returns JSON text of the API body (`best.usd_per_hr`, `alts`, …).
+
+## Attribution
+
+Requests send `X-SpotGPU-Client: mcp-spotgpu`.
+
+## Not published yet
+
+PyPI / Official MCP Registry / Smithery / Glama publish is deferred until Biz Bot approval. `server.json` and `glama.json` stubs are in this package for later.

spotgpu_mcp-0.1.0/src/spotgpu_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/spotgpu_mcp/__init__.py
+src/spotgpu_mcp/client.py
+src/spotgpu_mcp/server.py
+src/spotgpu_mcp.egg-info/PKG-INFO
+src/spotgpu_mcp.egg-info/SOURCES.txt
+src/spotgpu_mcp.egg-info/dependency_links.txt
+src/spotgpu_mcp.egg-info/entry_points.txt
+src/spotgpu_mcp.egg-info/requires.txt
+src/spotgpu_mcp.egg-info/top_level.txt

spotgpu_mcp-0.1.0/src/spotgpu_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

spotgpu_mcp-0.1.0/src/spotgpu_mcp.egg-info/entry_points.txt

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

spotgpu_mcp-0.1.0/src/spotgpu_mcp.egg-info/requires.txt

@@ -0,0 +1,2 @@
+mcp<3,>=2
+httpx>=0.27.0

spotgpu_mcp-0.1.0/src/spotgpu_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+spotgpu_mcp