cursor-cloud-mcp 0.3.1__py3-none-any.whl

cursor_cloud_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Local MCP server for the Cursor Cloud Agents v1 API."""
+
+__version__ = "0.3.1"

cursor_cloud_mcp/__main__.py

@@ -0,0 +1,11 @@
+"""Entry point ``python -m cursor_cloud_mcp`` and console script ``cursor-cloud-mcp``."""
+
+from cursor_cloud_mcp.server import run_stdio
+
+
+def main() -> None:
+    run_stdio()
+
+
+if __name__ == "__main__":
+    main()

cursor_cloud_mcp/activity.py

@@ -0,0 +1,158 @@
+"""Activity summary of a run, built from its event stream.
+
+The run object says little: a RUNNING run keeps the ``updatedAt`` of its creation, an ERROR run
+carries neither ``error`` nor ``result``, and FINISHED only means the agent ended its turn. The
+stream says more: event ids are millisecond timestamps (liveness), and tool calls show the last
+command and the background tasks the agent started and awaited. Everything here is the last
+*observed* state, never a guarantee about the VM.
+"""
+
+import datetime as dt
+import re
+from typing import Any
+
+from cursor_cloud_mcp.config import ACTIVITY_TEXT_MAX_CHARS
+from cursor_cloud_mcp.models import ActivityView, BackgroundTaskView, RunEventView, ToolCallSummaryView
+from cursor_cloud_mcp.shapes import clip, tool_payload
+
+# Stream ids look like Redis stream ids: "<milliseconds>-<sequence>" (checked 2026-10-06).
+_EVENT_ID = re.compile(r"^(\d{12,14})-\d+$")
+# Bounds a parsed timestamp must fall within to be trusted: 2020-01-01 to 2100-01-01.
+_MIN_MS = 1_577_836_800_000
+_MAX_MS = 4_102_444_800_000
+_MAX_TASKS = 20
+
+
+def event_time(event_id: str | None) -> dt.datetime | None:
+    """UTC time encoded in an event id, or None if the id does not have the expected shape."""
+    if event_id is None:
+        return None
+    match = _EVENT_ID.match(event_id)
+    if match is None:
+        return None
+    ms = int(match.group(1))
+    if not _MIN_MS <= ms <= _MAX_MS:
+        return None
+    return dt.datetime.fromtimestamp(ms / 1000, tz=dt.UTC)
+
+
+def iso(moment: dt.datetime | None) -> str | None:
+    if moment is None:
+        return None
+    return moment.isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+class ActivityTracker:
+    """Fed with every stream event, in order; keeps only what the summary needs."""
+
+    def __init__(self) -> None:
+        self.last_event_id: str | None = None
+        self.scanned = 0
+        self._assistant: list[str] = []
+        self._assistant_open = False
+        self._last_assistant: str | None = None
+        self._last_tool: RunEventView | None = None
+        self._tasks: dict[str, dict[str, Any]] = {}
+
+    def feed(self, event_id: str | None, kind: str, payload: object, view: RunEventView | None) -> None:
+        if event_id:
+            self.last_event_id = event_id
+        if kind in {"heartbeat", "interaction_update"}:
+            return
+        self.scanned += 1
+        if kind == "assistant":
+            text = view.text if view is not None else None
+            if not self._assistant_open:
+                self._assistant = []
+                self._assistant_open = True
+            if text:
+                self._assistant.append(text)
+            return
+        if self._assistant_open:
+            self._close_assistant()
+        if kind == "tool_call" and view is not None:
+            self._last_tool = view
+            self._track_task(event_id, tool_payload(payload))
+
+    def summary(self, *, run_terminal: bool | None, now: dt.datetime | None = None) -> ActivityView:
+        if self._assistant_open:
+            self._close_assistant()
+        now = now or dt.datetime.now(dt.UTC)
+        last_at = event_time(self.last_event_id)
+        # Counted over every task: the oldest one may be the job still running.
+        running = sum(1 for task in self._tasks.values() if task.get("state") == "running")
+        tasks = [
+            BackgroundTaskView(
+                task_id=task_id,
+                command=task.get("command"),
+                last_state=task.get("state", "unknown"),
+                runtime_ms=task.get("runtime_ms"),
+                observed_at=iso(event_time(task.get("event_id"))),
+            )
+            for task_id, task in list(self._tasks.items())[-_MAX_TASKS:]
+        ]
+        tool = self._last_tool
+        return ActivityView(
+            last_event_id=self.last_event_id,
+            last_event_at=iso(last_at),
+            idle_seconds=None if last_at is None else max(0, int((now - last_at).total_seconds())),
+            last_assistant_text=self._last_assistant,
+            last_tool_call=None
+            if tool is None
+            else ToolCallSummaryView(
+                name=tool.tool_name,
+                status=tool.tool_status,
+                args=tool.tool_args,
+                result=tool.tool_result,
+            ),
+            background_tasks=tasks or None,
+            background_tasks_total=len(self._tasks) or None,
+            unfinished_background_tasks=running if self._tasks else None,
+            run_terminal=run_terminal,
+            scanned_events=self.scanned,
+        )
+
+    def _close_assistant(self) -> None:
+        text = "".join(self._assistant).strip()
+        if text:
+            # The end of a long message is what tells where the agent stands.
+            self._last_assistant = text if len(text) <= ACTIVITY_TEXT_MAX_CHARS else "…" + text[-ACTIVITY_TEXT_MAX_CHARS:]
+        self._assistant_open = False
+
+    def _track_task(self, event_id: str | None, payload: dict[str, Any]) -> None:
+        """Background launches (run_terminal_cmd) and their observed states (await)."""
+        if payload.get("status") != "completed":
+            return
+        name = payload.get("name")
+        args = payload.get("args") if isinstance(payload.get("args"), dict) else {}
+        result = payload.get("result") if isinstance(payload.get("result"), dict) else {}
+        success = result.get("success") if isinstance(result.get("success"), dict) else {}
+        if name == "run_terminal_cmd" and (args.get("isBackground") is True or result.get("isBackground") is True):
+            task_id = success.get("shellId")
+            if task_id is None:
+                return
+            command = success.get("command") or args.get("command")
+            self._tasks[str(task_id)] = {
+                "command": clip(command)[0],
+                "state": "running",
+                "runtime_ms": None,
+                "event_id": event_id,
+            }
+            return
+        if name == "await":
+            for state, key in (("running", "stillRunning"), ("complete", "complete")):
+                observed = success.get(key)
+                if isinstance(observed, dict) and observed.get("taskId") is not None:
+                    task_id = str(observed["taskId"])
+                    task = self._tasks.setdefault(task_id, {"command": None})
+                    task.update(state=state, runtime_ms=_int(observed.get("runtimeMs")), event_id=event_id)
+                    # Keep insertion order meaningful: the most recently observed task comes last.
+                    self._tasks[task_id] = self._tasks.pop(task_id)
+                    return
+
+
+def _int(value: object) -> int | None:
+    try:
+        return int(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return None

cursor_cloud_mcp/artifacts.py

@@ -0,0 +1,156 @@
+"""List, URL and text reading of artifacts. The download does not send the Cursor key."""
+
+import asyncio
+import logging
+from typing import Literal
+
+import httpx
+
+from cursor_cloud_mcp import budget
+from cursor_cloud_mcp.client import CursorCloudClient, ResponseTooLarge, close_quietly, read_bounded
+from cursor_cloud_mcp.config import ARTIFACT_MAX_BYTES, DEFAULT_DEADLINE_SECONDS
+from cursor_cloud_mcp.errors import ErrorCode, failure
+from cursor_cloud_mcp.models import (
+    ArtifactItemView,
+    ArtifactListView,
+    ArtifactReadView,
+    ArtifactUrlView,
+)
+from cursor_cloud_mcp.slicing import slice_text
+from cursor_cloud_mcp.validation import require_artifact_path
+
+logger = logging.getLogger(__name__)
+_REDIRECTS = {301, 302, 303, 307, 308}
+
+
+async def list_artifacts(client: CursorCloudClient, agent_id: str) -> ArtifactListView:
+    remote = await client.list_artifacts(agent_id)
+    return ArtifactListView(
+        items=[
+            ArtifactItemView(path=item.path, size_bytes=item.sizeBytes, updated_at=item.updatedAt)
+            for item in remote.items
+        ]
+    )
+
+
+async def artifact_url(client: CursorCloudClient, agent_id: str, path: str) -> ArtifactUrlView:
+    checked = require_artifact_path(path)
+    remote = await client.artifact_download(agent_id, checked)
+    _require_presigned(remote.url)
+    return ArtifactUrlView(path=checked, url=remote.url, expires_at=remote.expiresAt)
+
+
+async def read_artifact(
+    client: CursorCloudClient,
+    agent_id: str,
+    path: str,
+    *,
+    offset: int,
+    limit: int,
+    url_only: bool = False,
+) -> ArtifactReadView:
+    """UTF-8 text of at most 5 MB. Otherwise, or on request, the presigned URL to download elsewhere."""
+    located = await artifact_url(client, agent_id, path)
+    if url_only:
+        return ArtifactReadView(path=located.path, expires_at=located.expires_at, url=located.url)
+    try:
+        raw = await fetch_presigned(
+            located.url,
+            transport=client.download_transport,
+            max_bytes=ARTIFACT_MAX_BYTES,
+            deadline=DEFAULT_DEADLINE_SECONDS,
+        )
+    except _TooLarge:
+        return _unreadable(located, "too_large")
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeError:
+        return _unreadable(located, "not_utf8")
+    chunk, truncated, next_offset = slice_text(text, offset, limit)
+    return ArtifactReadView(
+        path=located.path,
+        text=chunk,
+        offset=offset,
+        limit=limit,
+        total_chars=len(text),
+        truncated=truncated,
+        next_offset=next_offset,
+        expires_at=located.expires_at,
+    )
+
+
+class _TooLarge(Exception):
+    """Artifact beyond the text-reading limit: the URL is returned instead."""
+
+
+def _unreadable(located: ArtifactUrlView, reason: Literal["not_utf8", "too_large"]) -> ArtifactReadView:
+    return ArtifactReadView(
+        path=located.path,
+        expires_at=located.expires_at,
+        url=located.url,
+        text_unavailable=reason,
+    )
+
+
+async def fetch_presigned(
+    url: str,
+    *,
+    transport: httpx.AsyncBaseTransport | None,
+    max_bytes: int,
+    deadline: float,
+) -> bytes:
+    """Download bounded end to end: connection, reading and closing."""
+    _require_presigned(url)
+    deadline_at = budget.deadline_at(deadline)
+    remaining = deadline_at - asyncio.get_running_loop().time()
+    if remaining <= 0:
+        raise failure(ErrorCode.TIMEOUT, "Tool budget exhausted before the artifact download.")
+    try:
+        async with asyncio.timeout_at(deadline_at):
+            async with httpx.AsyncClient(
+                transport=transport,
+                follow_redirects=False,
+                timeout=httpx.Timeout(remaining),
+            ) as http:
+                request = http.build_request("GET", url)
+                if "authorization" in {name.lower() for name in request.headers}:
+                    raise failure(ErrorCode.VALIDATION, "The download must not carry the Cursor key.")
+                response = await http.send(request, stream=True)
+                try:
+                    return await _read_download(response, max_bytes)
+                finally:
+                    await close_quietly(response)
+    except (TimeoutError, httpx.TimeoutException):
+        raise failure(ErrorCode.TIMEOUT, "Timed out during the artifact download.") from None
+    except httpx.RequestError:
+        raise failure(ErrorCode.TIMEOUT, "Artifact download interrupted.") from None
+
+
+async def _read_download(response: httpx.Response, max_bytes: int) -> bytes:
+    logger.info("artifact_download status=%s", response.status_code)
+    if response.status_code in _REDIRECTS:
+        raise failure(ErrorCode.INCOMPATIBLE_RESPONSE, "Download redirect refused.")
+    if response.status_code != 200:
+        raise failure(
+            ErrorCode.UPSTREAM,
+            f"Artifact download refused ({response.status_code}).",
+        )
+    try:
+        return await read_bounded(response, max_bytes)
+    except ResponseTooLarge:
+        raise _TooLarge from None
+
+
+def _require_presigned(url: str) -> None:
+    try:
+        parsed = httpx.URL(url)
+    except httpx.InvalidURL:
+        raise failure(ErrorCode.VALIDATION, "Invalid artifact URL.") from None
+    host = parsed.host
+    if parsed.scheme != "https" or not host.endswith(".amazonaws.com"):
+        raise failure(
+            ErrorCode.VALIDATION,
+            "The download only accepts an HTTPS URL whose host ends with .amazonaws.com.",
+        )
+    if parsed.username or parsed.password:
+        raise failure(ErrorCode.VALIDATION, "The artifact URL must not contain credentials.")

cursor_cloud_mcp/budget.py

@@ -0,0 +1,34 @@
+"""Absolute budget of a tool call. Sub-operations receive the remaining time."""
+
+import asyncio
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+
+_DEADLINE: ContextVar[float | None] = ContextVar("cursor_mcp_tool_deadline", default=None)
+
+
+@contextmanager
+def tool_budget(seconds: float) -> Iterator[None]:
+    """Set the deadline of the current call. A nested budget can only shorten it."""
+    now = asyncio.get_running_loop().time()
+    current = _DEADLINE.get()
+    wanted = now + seconds
+    token = _DEADLINE.set(wanted if current is None else min(current, wanted))
+    try:
+        yield
+    finally:
+        _DEADLINE.reset(token)
+
+
+def deadline_at(cap_seconds: float) -> float:
+    """Absolute deadline: the nearer of ``cap_seconds`` and the tool budget."""
+    now = asyncio.get_running_loop().time()
+    local = now + cap_seconds
+    budget = _DEADLINE.get()
+    return local if budget is None else min(local, budget)
+
+
+def remaining(cap_seconds: float) -> float:
+    """Remaining time, capped by ``cap_seconds``. May be negative or zero."""
+    return deadline_at(cap_seconds) - asyncio.get_running_loop().time()

cursor_cloud_mcp/catalog.py

@@ -0,0 +1,155 @@
+"""Resolution of the model and reasoning level from the Cursor catalog."""
+
+from cursor_cloud_mcp.errors import ErrorCode, failure
+from cursor_cloud_mcp.models import (
+    ModelParam,
+    RemoteModel,
+    RemoteModelList,
+    RemoteModelParameter,
+)
+
+_REASONING_IDS = ("effort", "reasoning_effort", "reasoning")
+
+
+def reasoning_parameter(model: RemoteModel) -> RemoteModelParameter | None:
+    """First exposed reasoning parameter, in the order effort, reasoning_effort, reasoning."""
+    by_id = {parameter.id: parameter for parameter in model.parameters or []}
+    for name in _REASONING_IDS:
+        found = by_id.get(name)
+        if found is not None:
+            return found
+    return None
+
+
+def find_model(catalog: RemoteModelList, model_id: str) -> RemoteModel:
+    """A catalog id, or an alias that designates only one model."""
+    exact = next((item for item in catalog.items if item.id == model_id), None)
+    if exact is not None:
+        return exact
+    matches = [item for item in catalog.items if model_id in (item.aliases or [])]
+    if len(matches) == 1:
+        return matches[0]
+    if matches:
+        raise failure(
+            ErrorCode.VALIDATION,
+            f"The alias {model_id} designates several models: {', '.join(item.id for item in matches)}. "
+            "Choose an id.",
+        )
+    raise failure(
+        ErrorCode.VALIDATION,
+        f"{model_id} is neither an id nor an alias in the Cursor catalog. Call cursor_list_models.",
+    )
+
+
+def default_selection(model: RemoteModel) -> dict[str, str] | None:
+    """Values of the default variant, limited to the published parameters."""
+    published = {parameter.id for parameter in model.parameters or []}
+    for variant in model.variants or []:
+        if variant.isDefault:
+            values = {item.id: item.value for item in variant.params if item.id in published}
+            return values or None
+    return None
+
+
+def restricted(model: RemoteModel) -> bool:
+    """True if the catalog does not offer every combination of published values."""
+    if not model.variants or not model.parameters:
+        return False
+    return len(_published_combinations(model)) < _product(model)
+
+
+def resolve_model_selection(
+    catalog: RemoteModelList,
+    *,
+    model_id: str,
+    model_params: list[ModelParam] | None,
+    reasoning_level: str | None,
+) -> dict[str, object]:
+    """Build ``model`` for POST /v1/agents. Refuses an id, a value or a combination outside the catalog."""
+    model = find_model(catalog, model_id)
+    ordered: list[tuple[str, str]] = []
+    seen: set[str] = set()
+    for item in model_params or []:
+        _require_param(model, item.id, item.value)
+        if item.id in seen:
+            raise failure(ErrorCode.VALIDATION, f"The parameter {item.id} is repeated.")
+        seen.add(item.id)
+        ordered.append((item.id, item.value))
+    if reasoning_level is not None:
+        parameter = reasoning_parameter(model)
+        if parameter is None:
+            raise failure(
+                ErrorCode.VALIDATION,
+                f"{model.id} does not expose a reasoning level (effort, reasoning_effort or reasoning).",
+            )
+        allowed = _values(parameter)
+        if reasoning_level not in allowed:
+            raise failure(
+                ErrorCode.VALIDATION,
+                f"{parameter.id} for {model.id} accepts: {', '.join(allowed)}. "
+                "No translation is done: xhigh and extra-high stay distinct.",
+            )
+        if parameter.id in seen:
+            current = next(value for key, value in ordered if key == parameter.id)
+            if current != reasoning_level:
+                raise failure(ErrorCode.VALIDATION, "reasoning_level contradicts model_params.")
+        else:
+            ordered.append((parameter.id, reasoning_level))
+            seen.add(parameter.id)
+    _require_combination(model, ordered)
+    body: dict[str, object] = {"id": model.id}
+    if ordered:
+        body["params"] = [{"id": key, "value": value} for key, value in ordered]
+    return body
+
+
+def _require_combination(model: RemoteModel, chosen: list[tuple[str, str]]) -> None:
+    """A partial selection must fit within at least one published variant."""
+    if not chosen or not model.variants:
+        return
+    wanted = set(chosen)
+    if any(wanted <= combination for combination in _published_combinations(model)):
+        return
+    text = ", ".join(f"{key}={value}" for key, value in chosen)
+    raise failure(
+        ErrorCode.VALIDATION,
+        f"Combination refused by the catalog of {model.id}: {text}. "
+        f"cursor_list_models with model_id={model.id} lists the valid variants.",
+    )
+
+
+def _published_combinations(model: RemoteModel) -> list[set[tuple[str, str]]]:
+    published = {parameter.id for parameter in model.parameters or []}
+    found: list[set[tuple[str, str]]] = []
+    for variant in model.variants or []:
+        combination = {(item.id, item.value) for item in variant.params if item.id in published}
+        if combination not in found:
+            found.append(combination)
+    return found
+
+
+def _product(model: RemoteModel) -> int:
+    total = 1
+    for parameter in model.parameters or []:
+        total *= len(parameter.values)
+    return total
+
+
+def _values(parameter: RemoteModelParameter) -> list[str]:
+    return [item.value for item in parameter.values]
+
+
+def _require_param(model: RemoteModel, param_id: str, value: str) -> None:
+    found = next((parameter for parameter in model.parameters or [] if parameter.id == param_id), None)
+    if found is None:
+        names = ", ".join(parameter.id for parameter in model.parameters or []) or "none"
+        raise failure(
+            ErrorCode.VALIDATION,
+            f"Unknown parameter {param_id} for {model.id}. Parameters: {names}.",
+        )
+    allowed = _values(found)
+    if value not in allowed:
+        raise failure(
+            ErrorCode.VALIDATION,
+            f"{param_id} for {model.id} accepts: {', '.join(allowed)}.",
+        )