cloudrift-mcp 0.1.0__tar.gz

cloudrift_mcp-0.1.0/LICENSE

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

cloudrift_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: cloudrift-mcp
+Version: 0.1.0
+Summary: Read-only MCP server exposing CloudRift cloud-waste findings and verified-savings receipts to AI assistants
+Author-email: CloudRift <support@cloudrift.tech>
+License: MIT
+Project-URL: Homepage, https://cloudrift.tech
+Keywords: mcp,cloudrift,finops,cloud-cost,waste,savings
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<3,>=2
+Requires-Dist: httpx>=0.27
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# cloudrift-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that gives your AI
+assistant (Claude Code, Claude Desktop, Cursor, and any other MCP
+client) read-only access to your own
+[CloudRift](https://cloudrift.tech) data: cloud-waste findings,
+optimization recommendations, cost summaries, budgets, and the
+verified-savings ledger. The thesis is simple: in the agent era, your
+cost data should be queryable by the assistants you already work in -
+"what are my ten most expensive orphaned resources?" or "how much has
+CloudRift actually saved us, and how is that number computed?" should
+be one question away, answered from your tenant's live findings and
+receipts rather than a stale export.
+
+Read-only by construction. Every tool is a GET against the CloudRift
+public API, scoped to the tenant that owns the API key. No tool
+mutates anything, and no tool accepts a credential argument - the key
+comes from the environment only.
+
+## Quickstart
+
+Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/), or pip:
+
+```
+uvx cloudrift-mcp        # no install step
+pip install cloudrift-mcp && cloudrift-mcp
+```
+
+Create an API key in CloudRift (Settings > API Keys) with read-only
+scopes, then export it as `CLOUDRIFT_API_KEY`.
+
+### Claude Code
+
+```
+claude mcp add cloudrift --env CLOUDRIFT_API_KEY=crk_live_... -- uvx cloudrift-mcp
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (Settings > Developer > Edit
+Config):
+
+```json
+{
+  "mcpServers": {
+    "cloudrift": {
+      "command": "uvx",
+      "args": ["cloudrift-mcp"],
+      "env": {
+        "CLOUDRIFT_API_KEY": "crk_live_..."
+      }
+    }
+  }
+}
+```
+
+## Environment variables
+
+| Variable            | Required | Meaning                                            |
+| ------------------- | -------- | -------------------------------------------------- |
+| `CLOUDRIFT_API_KEY` | yes      | A CloudRift API key. Without it the server starts, but every tool returns a clear CONFIG error. |
+| `CLOUDRIFT_API_URL` | no       | API origin; defaults to `https://cloudrift.tech`.  |
+
+## Tools
+
+All tools are read-only GETs with a 30 second timeout. Lists are
+capped, and every capped result states the cap and the full totals, so
+a partial view is never silent.
+
+| Tool                  | Arguments                   | Endpoint                  | Returns |
+| --------------------- | --------------------------- | ------------------------- | ------- |
+| `list_waste_findings` | `account_id?`, `limit?` (default 25, max 100) | `/api/v1/resources` | Waste findings: orphaned resources first, then optimization candidates, monthly cost descending, with full waste totals. |
+| `get_recommendations` | `account_id?` (filtered locally) | `/api/v1/recommendations` | Optimization recommendations, estimated monthly savings descending (top 50), with the summed savings across all matches. |
+| `get_cost_summary`    | -                           | `/api/v1/costs/summary`   | Monthly spend, orphaned (waste) cost, annual savings potential, per-account breakdown, latest scan date. |
+| `get_savings_receipts`| -                           | `/api/v1/receipts`        | The verified-savings ledger: entries labelled estimated / confirmed / billing_verified, per-status totals, and the API's `basis` string verbatim (how returned_to_date is computed). Requires CloudRift >= 2026-09-30. |
+| `get_budgets`         | -                           | `/api/v1/budgets`         | Configured spend budgets with warning / critical thresholds. |
+
+Errors come back as one honest line - `API_ERROR: CloudRift API
+returned 403 for GET /api/v1/costs/summary: This API key is missing
+the required scope: read:costs.` - never a stack trace.
+
+## Security
+
+- **Use a read-only key.** Grant only the `read:*` scopes
+  (`read:resources`, `read:recommendations`, `read:costs`,
+  `read:budgets`) when you mint the key. This server only ever issues
+  GETs, so a broader key buys nothing and risks more.
+- **Env-only auth.** The key is read from `CLOUDRIFT_API_KEY` and sent
+  as `Authorization: Bearer`. No tool accepts a key as an argument (a
+  test enforces that no credential-shaped field exists in any tool
+  schema), and the key is never echoed into tool results or error
+  messages.
+- **Tenant-scoped by the API.** The CloudRift public API scopes every
+  query to the key owner's account; this server adds no cross-tenant
+  reach.
+- **Bounded requests.** At most five pages of 200 items are fetched
+  per tool call, and CloudRift rate-limits each key to 120
+  requests/minute.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

cloudrift_mcp-0.1.0/README.md

@@ -0,0 +1,102 @@
+# cloudrift-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that gives your AI
+assistant (Claude Code, Claude Desktop, Cursor, and any other MCP
+client) read-only access to your own
+[CloudRift](https://cloudrift.tech) data: cloud-waste findings,
+optimization recommendations, cost summaries, budgets, and the
+verified-savings ledger. The thesis is simple: in the agent era, your
+cost data should be queryable by the assistants you already work in -
+"what are my ten most expensive orphaned resources?" or "how much has
+CloudRift actually saved us, and how is that number computed?" should
+be one question away, answered from your tenant's live findings and
+receipts rather than a stale export.
+
+Read-only by construction. Every tool is a GET against the CloudRift
+public API, scoped to the tenant that owns the API key. No tool
+mutates anything, and no tool accepts a credential argument - the key
+comes from the environment only.
+
+## Quickstart
+
+Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/), or pip:
+
+```
+uvx cloudrift-mcp        # no install step
+pip install cloudrift-mcp && cloudrift-mcp
+```
+
+Create an API key in CloudRift (Settings > API Keys) with read-only
+scopes, then export it as `CLOUDRIFT_API_KEY`.
+
+### Claude Code
+
+```
+claude mcp add cloudrift --env CLOUDRIFT_API_KEY=crk_live_... -- uvx cloudrift-mcp
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (Settings > Developer > Edit
+Config):
+
+```json
+{
+  "mcpServers": {
+    "cloudrift": {
+      "command": "uvx",
+      "args": ["cloudrift-mcp"],
+      "env": {
+        "CLOUDRIFT_API_KEY": "crk_live_..."
+      }
+    }
+  }
+}
+```
+
+## Environment variables
+
+| Variable            | Required | Meaning                                            |
+| ------------------- | -------- | -------------------------------------------------- |
+| `CLOUDRIFT_API_KEY` | yes      | A CloudRift API key. Without it the server starts, but every tool returns a clear CONFIG error. |
+| `CLOUDRIFT_API_URL` | no       | API origin; defaults to `https://cloudrift.tech`.  |
+
+## Tools
+
+All tools are read-only GETs with a 30 second timeout. Lists are
+capped, and every capped result states the cap and the full totals, so
+a partial view is never silent.
+
+| Tool                  | Arguments                   | Endpoint                  | Returns |
+| --------------------- | --------------------------- | ------------------------- | ------- |
+| `list_waste_findings` | `account_id?`, `limit?` (default 25, max 100) | `/api/v1/resources` | Waste findings: orphaned resources first, then optimization candidates, monthly cost descending, with full waste totals. |
+| `get_recommendations` | `account_id?` (filtered locally) | `/api/v1/recommendations` | Optimization recommendations, estimated monthly savings descending (top 50), with the summed savings across all matches. |
+| `get_cost_summary`    | -                           | `/api/v1/costs/summary`   | Monthly spend, orphaned (waste) cost, annual savings potential, per-account breakdown, latest scan date. |
+| `get_savings_receipts`| -                           | `/api/v1/receipts`        | The verified-savings ledger: entries labelled estimated / confirmed / billing_verified, per-status totals, and the API's `basis` string verbatim (how returned_to_date is computed). Requires CloudRift >= 2026-09-30. |
+| `get_budgets`         | -                           | `/api/v1/budgets`         | Configured spend budgets with warning / critical thresholds. |
+
+Errors come back as one honest line - `API_ERROR: CloudRift API
+returned 403 for GET /api/v1/costs/summary: This API key is missing
+the required scope: read:costs.` - never a stack trace.
+
+## Security
+
+- **Use a read-only key.** Grant only the `read:*` scopes
+  (`read:resources`, `read:recommendations`, `read:costs`,
+  `read:budgets`) when you mint the key. This server only ever issues
+  GETs, so a broader key buys nothing and risks more.
+- **Env-only auth.** The key is read from `CLOUDRIFT_API_KEY` and sent
+  as `Authorization: Bearer`. No tool accepts a key as an argument (a
+  test enforces that no credential-shaped field exists in any tool
+  schema), and the key is never echoed into tool results or error
+  messages.
+- **Tenant-scoped by the API.** The CloudRift public API scopes every
+  query to the key owner's account; this server adds no cross-tenant
+  reach.
+- **Bounded requests.** At most five pages of 200 items are fetched
+  per tool call, and CloudRift rate-limits each key to 120
+  requests/minute.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

cloudrift_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cloudrift-mcp"
+version = "0.1.0"
+description = "Read-only MCP server exposing CloudRift cloud-waste findings and verified-savings receipts to AI assistants"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "CloudRift", email = "support@cloudrift.tech" }]
+keywords = ["mcp", "cloudrift", "finops", "cloud-cost", "waste", "savings"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+]
+dependencies = [
+    "mcp>=2,<3",
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://cloudrift.tech"
+
+[project.scripts]
+cloudrift-mcp = "cloudrift_mcp.server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

cloudrift_mcp-0.1.0/setup.cfg

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

cloudrift_mcp-0.1.0/src/cloudrift_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""cloudrift-mcp: read-only MCP access to a CloudRift tenant's own data."""
+
+__version__ = "0.1.0"

cloudrift_mcp-0.1.0/src/cloudrift_mcp/client.py

@@ -0,0 +1,102 @@
+"""HTTP access to the CloudRift public API (read-only GETs).
+
+Configuration comes from the environment ONLY:
+
+    CLOUDRIFT_API_KEY   required. A CloudRift API key (crk_live_...).
+                        Without it the server still starts, but every
+                        tool returns a clear CONFIG error.
+    CLOUDRIFT_API_URL   optional. Defaults to https://cloudrift.tech.
+
+The key is sent as `Authorization: Bearer <key>`. It is never accepted
+as a tool argument and never echoed into any tool result or error
+message. All requests are GETs with a 30 second timeout; failures are
+returned as honest one-line tool errors (status + the API's own
+detail), never stack traces.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .errors import API_ERROR, CONFIG, NETWORK_ERROR, tool_error
+
+DEFAULT_API_URL = "https://cloudrift.tech"
+TIMEOUT_SECONDS = 30.0
+
+# Tests set this to an httpx.MockTransport; production leaves it None.
+transport: Optional[httpx.BaseTransport] = None
+
+
+def base_url() -> str:
+    """The API origin, from CLOUDRIFT_API_URL, without a trailing slash."""
+    return (os.environ.get("CLOUDRIFT_API_URL") or DEFAULT_API_URL).rstrip("/")
+
+
+def _api_key() -> str:
+    key = (os.environ.get("CLOUDRIFT_API_KEY") or "").strip()
+    if not key:
+        raise tool_error(
+            CONFIG,
+            "CLOUDRIFT_API_KEY is not set. Create a read-only API key in "
+            "CloudRift (Settings > API Keys) and export it in the "
+            "environment of this MCP server; keys are never accepted as "
+            "tool arguments.")
+    return key
+
+
+def get(path: str, params: Optional[Dict[str, Any]] = None) -> Any:
+    """GET an /api/v1 path and return the parsed JSON body.
+
+    `path` is the part after the origin, e.g. "/api/v1/resources".
+    Raises a ToolError (CONFIG / NETWORK_ERROR / API_ERROR) on any
+    failure; the message carries the status and the API's own `detail`
+    when there is one.
+    """
+    url = base_url() + path
+    headers = {"Authorization": "Bearer " + _api_key()}
+    try:
+        with httpx.Client(timeout=TIMEOUT_SECONDS, transport=transport) as http:
+            response = http.get(url, params=params or {}, headers=headers)
+    except httpx.TimeoutException:
+        raise tool_error(
+            NETWORK_ERROR,
+            f"GET {path} timed out after {int(TIMEOUT_SECONDS)}s "
+            f"({base_url()}).") from None
+    except httpx.HTTPError as exc:
+        # One honest line (e.g. connection refused), never a traceback.
+        raise tool_error(
+            NETWORK_ERROR,
+            f"could not reach {base_url()}: {exc.__class__.__name__}: "
+            f"{exc}") from None
+
+    if response.status_code >= 400:
+        raise tool_error(
+            API_ERROR,
+            f"CloudRift API returned {response.status_code} for GET {path}: "
+            f"{_api_detail(response)}")
+
+    try:
+        return response.json()
+    except ValueError:
+        raise tool_error(
+            API_ERROR,
+            f"CloudRift API returned a non-JSON body for GET {path} "
+            f"(status {response.status_code}).") from None
+
+
+def _api_detail(response: httpx.Response) -> str:
+    """The API's own `detail` string, else a truncated body, else the
+    HTTP reason phrase."""
+    try:
+        body = response.json()
+        if isinstance(body, dict) and body.get("detail"):
+            return str(body["detail"])
+    except ValueError:
+        pass
+    text = (response.text or "").strip()
+    if text:
+        return text[:200]
+    return response.reason_phrase or "no detail provided"

cloudrift_mcp-0.1.0/src/cloudrift_mcp/errors.py

@@ -0,0 +1,19 @@
+"""Structured tool errors.
+
+Every failure a tool can hit is raised as a ToolError whose message
+starts with a stable code, so an agent (or a human reading an editor
+pane) gets "CODE: one clear sentence" and never a stack trace. The MCP
+SDK converts a raised ToolError into an is_error tool result.
+"""
+
+from mcp.server.mcpserver.exceptions import ToolError
+
+CONFIG = "CONFIG"
+INVALID_ARGUMENT = "INVALID_ARGUMENT"
+API_ERROR = "API_ERROR"
+NETWORK_ERROR = "NETWORK_ERROR"
+
+
+def tool_error(code: str, message: str) -> ToolError:
+    """Build (not raise) a ToolError with the standard CODE: message shape."""
+    return ToolError(f"{code}: {message}")