orb-cloud-mcp 0.1.0__py3-none-any.whl

orb_cloud_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""MCP server for Orb Cloud device management."""
+
+__version__ = "0.1.0"

orb_cloud_mcp/cache.py

@@ -0,0 +1,25 @@
+"""Shared TTL cache for stable Orb Cloud API responses."""
+
+import os
+
+from cachetools import TTLCache
+
+_DEFAULT_TTL = 300  # seconds
+
+
+def _ttl() -> int:
+    return int(os.environ.get("ORB_CLOUD_CACHE_TTL", _DEFAULT_TTL))
+
+
+# Module-level cache shared across tools. Sized generously; in practice only a
+# handful of organizations and their device lists will ever be stored.
+cache: TTLCache = TTLCache(maxsize=256, ttl=_ttl())
+
+
+def cache_key(*args: object) -> tuple:
+    """Build a cache key scoped to the current API token.
+
+    The token is hashed so it is never stored in plaintext as a dict key,
+    preventing accidental exposure in logs or debug output.
+    """
+    return (hash(os.environ.get("ORB_CLOUD_API_KEY")), *args)

orb_cloud_mcp/client.py

@@ -0,0 +1,20 @@
+"""Orb Cloud client factory, reads credentials from environment."""
+
+import os
+
+from orb_cloud_client.client import OrbCloudClientAsync
+
+
+def get_client() -> OrbCloudClientAsync:
+    """Return an authenticated async Orb Cloud client.
+
+    Raises:
+        RuntimeError: If ORB_CLOUD_API_KEY is not set.
+    """
+    token = os.environ.get("ORB_CLOUD_API_KEY")
+    if not token:
+        raise RuntimeError(
+            "ORB_CLOUD_API_KEY environment variable is not set. "
+            "Set it to your Orb Cloud API token."
+        )
+    return OrbCloudClientAsync(token=token)

orb_cloud_mcp/server.py

@@ -0,0 +1,43 @@
+"""FastMCP server for Orb Cloud."""
+
+from fastmcp import FastMCP
+
+from orb_cloud_mcp.tools.organizations import list_organizations
+from orb_cloud_mcp.tools.devices import list_devices, get_device_telemetry
+from orb_cloud_mcp.tools.speedtest import trigger_speedtest
+from orb_cloud_mcp.tools.datasets import configure_temp_datasets
+
+mcp = FastMCP(
+    name="orb-cloud",
+    instructions="Manage Orb Cloud devices, organizations, and run diagnostics.",
+)
+
+# --- Tools ---
+
+mcp.tool()(list_organizations)
+mcp.tool()(list_devices)
+mcp.tool()(get_device_telemetry)
+mcp.tool()(trigger_speedtest)
+mcp.tool()(configure_temp_datasets)
+
+# --- Resources ---
+
+
+@mcp.resource("orb://organizations")
+async def resource_organizations() -> list:
+    """All Orb Cloud organizations accessible with the configured API key."""
+    return await list_organizations()
+
+
+@mcp.resource("orb://organizations/{organization_id}/devices")
+async def resource_devices(organization_id: str) -> list:
+    """Stable configuration details for all devices in an Orb Cloud organization."""
+    return await list_devices(organization_id)
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

orb_cloud_mcp/tools/datasets.py

@@ -0,0 +1,108 @@
+"""MCP tool to configure temporary dataset push on Orb Cloud devices."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from orb_cloud_mcp.client import get_client
+
+
+class DataPushConfig(BaseModel):
+    """Configuration for pushing data to a custom HTTP endpoint."""
+
+    url: str = Field(..., description="Destination URL to push data to.")
+    datasets: list[str] | None = Field(
+        None,
+        description="Dataset names to include (e.g. ['responsiveness_1s', 'speed_results']).",
+    )
+    enabled: bool | None = Field(None, description="Whether pushing is enabled.")
+    identifiable: bool | None = Field(
+        None, description="Whether to include identifiable data."
+    )
+    format: str | None = Field(None, description="Payload format (e.g. 'json').")
+    interval_ms: int | None = Field(None, description="Push interval in milliseconds.")
+    buffer_kb: int | None = Field(None, description="Buffer size in kilobytes.")
+
+
+class DataAPIConfig(BaseModel):
+    """Configuration for exposing a local data API on the device."""
+
+    enabled: bool | None = Field(None, description="Whether the data API is enabled.")
+    datasets: list[str] | None = Field(
+        None, description="Dataset names to expose via the API."
+    )
+    identifiable: bool | None = Field(
+        None, description="Whether to include identifiable data."
+    )
+    api_key: str | None = Field(None, description="API key for the local data API.")
+    port: int | None = Field(None, description="Port for the local data API.")
+    buffer: int | None = Field(None, description="Buffer size.")
+
+
+class DatasetsConfig(BaseModel):
+    """Top-level dataset configuration."""
+
+    datasets: list[str] | None = Field(None, description="Dataset names to collect.")
+    enabled: bool | None = Field(
+        None, description="Whether data collection is enabled."
+    )
+    push: DataPushConfig | None = Field(
+        None, description="Push data to a custom HTTP endpoint."
+    )
+    cloud_push: DataPushConfig | None = Field(
+        None, description="Push data to Orb Cloud."
+    )
+    api: DataAPIConfig | None = Field(
+        None, description="Expose data via a local API endpoint on the device."
+    )
+
+
+async def configure_temp_datasets(
+    device_id: str,
+    duration: str = Field(
+        ..., description="How long to enable (e.g. '30m', '1h', '2h')."
+    ),
+    datasets_config: DatasetsConfig | None = None,
+) -> dict[str, Any]:
+    """Configure temporary dataset collection and push for an Orb Cloud device.
+
+    Enables the device to push data to a custom endpoint or expose a local API
+    for a fixed duration. After the duration expires, the device reverts to its
+    default configuration.
+
+    Args:
+        device_id: The Orb device ID to configure.
+        duration: How long to enable the configuration (e.g. '30m', '1h').
+        datasets_config: Dataset collection and push configuration. If omitted,
+            only the duration is updated.
+    """
+    from orb_cloud_client.models.generic import TempDatasetsRequest
+    from orb_cloud_client.models.config import Datasets, DataPush, DataAPI
+
+    def _to_data_push(cfg: DataPushConfig | None) -> DataPush | None:
+        if cfg is None:
+            return None
+        return DataPush(**cfg.model_dump(exclude_none=True))
+
+    def _to_data_api(cfg: DataAPIConfig | None) -> DataAPI | None:
+        if cfg is None:
+            return None
+        return DataAPI(**cfg.model_dump(exclude_none=True))
+
+    sdk_datasets: Datasets | None = None
+    if datasets_config is not None:
+        sdk_datasets = Datasets(
+            datasets=datasets_config.datasets,
+            enabled=datasets_config.enabled,
+            push=_to_data_push(datasets_config.push),
+            cloud_push=_to_data_push(datasets_config.cloud_push),
+            api=_to_data_api(datasets_config.api),
+        )
+
+    request = TempDatasetsRequest(
+        duration=duration,
+        datasets_config=sdk_datasets,
+    )
+
+    async with get_client() as client:
+        return await client.configure_temporary_datasets(device_id, request)

orb_cloud_mcp/tools/devices.py

@@ -0,0 +1,138 @@
+"""MCP tools for Orb Cloud devices."""
+
+from typing import Any
+
+from orb_cloud_client.models.generic import Device, OrbScore
+
+from orb_cloud_mcp.cache import cache, cache_key
+from orb_cloud_mcp.client import get_client
+
+_CACHE_KEY = "list_devices"
+
+
+async def list_devices(organization_id: str) -> list[dict[str, Any]]:
+    """List devices in an Orb Cloud organization with stable configuration details.
+
+    Returns device identity, hardware info, location, and configuration — data
+    that changes rarely. For real-time connectivity and performance scores, use
+    get_device_telemetry instead.
+
+    Args:
+        organization_id: The organization ID to list devices for.
+    """
+    key = cache_key(_CACHE_KEY, organization_id)
+    if key in cache:
+        return cache[key]
+
+    async with get_client() as client:
+        devices = await client.get_organization_devices(organization_id)
+    result = [_serialize_stable(d) for d in devices]
+    cache[key] = result
+    return result
+
+
+async def get_device_telemetry(
+    organization_id: str,
+    device_id: str | None = None,
+) -> list[dict[str, Any]]:
+    """Get live telemetry for devices in an Orb Cloud organization.
+
+    Returns real-time connectivity status and Orb performance scores. If
+    device_id is provided, returns telemetry for that device only.
+
+    Args:
+        organization_id: The organization ID to query devices for.
+        device_id: Optional Orb device ID to filter to a single device.
+    """
+    async with get_client() as client:
+        devices = await client.get_organization_devices(organization_id)
+
+    if device_id is not None:
+        devices = [d for d in devices if d.orb_id == device_id]
+
+    return [_serialize_telemetry(d) for d in devices]
+
+
+def _serialize_score(score: OrbScore | None) -> dict[str, Any] | None:
+    if score is None:
+        return None
+    result: dict[str, Any] = {
+        "score": score.score,
+        "display": score.display,
+        "included": score.included,
+        "value": score.value,
+        "duration_ms": score.duration_ms,
+        "score_version": score.score_version,
+    }
+    if score.components:
+        result["components"] = {
+            k: _serialize_score(v) for k, v in score.components.items()
+        }
+    return result
+
+
+def _serialize_stable(device: Device) -> dict[str, Any]:
+    """Serialize the stable, slowly-changing fields of a device."""
+    info: dict[str, Any] = {}
+    if device.summary:
+        s = device.summary
+        info["firmware_version"] = s.version
+        if s.tags:
+            if s.tags.geoip:
+                g = s.tags.geoip
+                info["geoip"] = {
+                    "city": g.city,
+                    "state": g.state,
+                    "country": g.country,
+                    "country_code": g.country_code,
+                    "isp_name": g.isp_name,
+                    "latitude": g.latitude,
+                    "longitude": g.longitude,
+                }
+            if s.tags.device_info:
+                di = s.tags.device_info
+                info["device_info"] = {
+                    "name": di.name,
+                    "full_name": di.full_name,
+                    "version": di.version,
+                    "cpu_count": di.cpu_count,
+                    "operating_system": di.operating_system,
+                }
+            if s.tags.network_interface:
+                ni = s.tags.network_interface
+                info["network_interface"] = {
+                    "name": ni.name,
+                    "type": ni.type,
+                    "local_ip": ni.local_ip,
+                    "mac_address": ni.mac_address,
+                }
+
+    return {
+        "orb_id": device.orb_id,
+        "name": device.name,
+        "can_notify": device.can_notify,
+        "tags": device.tags,
+        "config": device.config,
+        "created_ts": device.created_ts,
+        **info,
+    }
+
+
+def _serialize_telemetry(device: Device) -> dict[str, Any]:
+    """Serialize the live, frequently-changing fields of a device."""
+    scores: dict[str, Any] = {}
+    if device.summary:
+        s = device.summary
+        scores["summary_ts"] = s.created_ts
+        if s.orb_score:
+            scores["orb_score"] = _serialize_score(s.orb_score)
+        if s.orb_scores:
+            scores["orb_scores"] = [_serialize_score(sc) for sc in s.orb_scores]
+
+    return {
+        "orb_id": device.orb_id,
+        "name": device.name,
+        "is_connected": device.is_connected.value,
+        "is_connected_updated_at": device.is_connected_updated_at,
+        **scores,
+    }

orb_cloud_mcp/tools/organizations.py

@@ -0,0 +1,57 @@
+"""MCP tools and resources for Orb Cloud organizations."""
+
+from typing import Any
+
+from orb_cloud_client.models.server import OrganizationsResponse
+
+from orb_cloud_mcp.cache import cache, cache_key
+from orb_cloud_mcp.client import get_client
+
+_CACHE_KEY = "list_organizations"
+
+
+async def list_organizations() -> list[dict[str, Any]]:
+    """List all Orb Cloud organizations accessible with the configured API key."""
+    key = cache_key(_CACHE_KEY)
+    if key in cache:
+        return cache[key]
+
+    async with get_client() as client:
+        orgs = await client.get_organizations()
+    result = [_serialize_org(o) for o in orgs]
+    cache[key] = result
+    return result
+
+
+def _serialize_org(org: OrganizationsResponse) -> dict[str, Any]:
+    plan = None
+    if org.plan:
+        limits = None
+        if org.plan.limits:
+            limits = {
+                "devices": org.plan.limits.devices,
+                "users": org.plan.limits.users,
+                "deployment_tokens": org.plan.limits.deployment_tokens,
+            }
+        plan = {
+            "name": org.plan.name,
+            "features": org.plan.features,
+            "limits": limits,
+        }
+
+    usage = None
+    if org.usage:
+        usage = {
+            "devices": org.usage.devices,
+            "users": org.usage.users,
+            "deployment_tokens": org.usage.deployment_tokens,
+        }
+
+    return {
+        "organization_id": org.organization_id,
+        "name": org.name,
+        "customer_id": org.customer_id,
+        "subscription_id": org.subscription_id,
+        "plan": plan,
+        "usage": usage,
+    }

orb_cloud_mcp/tools/speedtest.py

@@ -0,0 +1,20 @@
+"""MCP tool to trigger speed tests on Orb Cloud devices."""
+
+from typing import Any, Literal
+
+from orb_cloud_mcp.client import get_client
+
+
+async def trigger_speedtest(
+    device_id: str,
+    test_type: Literal["content", "top"],
+) -> dict[str, Any]:
+    """Trigger a speed test on an Orb Cloud device.
+
+    Args:
+        device_id: The Orb device ID to run the speed test on.
+        test_type: The type of speed test — 'content' measures content delivery
+            performance, 'top' measures peak throughput.
+    """
+    async with get_client() as client:
+        return await client.trigger_speedtest(device_id, test_type)

orb_cloud_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: orb-cloud-mcp
+Version: 0.1.0
+Summary: MCP server for Orb Cloud device management and data analysis
+Author: Brian Connelly
+Author-email: Brian Connelly <bdc@bconnelly.net>
+License-Expression: MIT
+Requires-Dist: cachetools>=7.0.4
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: orb-cloud-client>=1.3.3
+Requires-Dist: pydantic>=2.0
+Requires-Python: >=3.10

orb_cloud_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+orb_cloud_mcp/__init__.py,sha256=iwtL2XPlsOy5MtEiGxCo2RlWFykz_dN8mE9j92hblV4,73
+orb_cloud_mcp/cache.py,sha256=pbEIlyf6gGVYPZ7UuiQOiuDfU4FyK8HcRHU8km0Pvxc,731
+orb_cloud_mcp/client.py,sha256=m_gjsp_tTuxtay2C-rNMJ1u3_nqoblqZreoaiYO61MI,574
+orb_cloud_mcp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+orb_cloud_mcp/server.py,sha256=d_DU7v65X1iz4OYgEW0FzA4E-C_O__gV5aOL0mRshvs,1177
+orb_cloud_mcp/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+orb_cloud_mcp/tools/datasets.py,sha256=x0cvwbmw-Zxdg4dT9dRUKiPNrnVwrR-v1nIStnDcAzo,4087
+orb_cloud_mcp/tools/devices.py,sha256=P3QkPkjCDsyP8Vc8gzkDdL-RAjP_7ZUoXFjBbvMCBJU,4555
+orb_cloud_mcp/tools/organizations.py,sha256=CFnSkSa9-uWzH30vieDmdypFRFMPkie3CqQ2pfkZZww,1604
+orb_cloud_mcp/tools/speedtest.py,sha256=skTpedUdS07ZHaFJ_MoXrbyDZvFNH5532gZ2fHNzcpI,632
+orb_cloud_mcp-0.1.0.dist-info/WHEEL,sha256=mydTeHxOpFHo-DnYhAd_3ATePms-g4rrYvM7wJK8P-U,80
+orb_cloud_mcp-0.1.0.dist-info/entry_points.txt,sha256=px4lDagsuu_DHSLjW0IaQ0qvkXLp-7Yff6CvYMddamg,61
+orb_cloud_mcp-0.1.0.dist-info/METADATA,sha256=WpWZmZ_kiSF8H5A8J2Zr1zvQRg7a5UE_fbBC1PQk2Vw,376
+orb_cloud_mcp-0.1.0.dist-info/RECORD,,

orb_cloud_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.10.9
+Root-Is-Purelib: true
+Tag: py3-none-any

orb_cloud_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+orb-cloud-mcp = orb_cloud_mcp.server:main
+