stackless-mcp 1.0.0b2__py3-none-any.whl

stackless_mcp/__init__.py

@@ -0,0 +1,22 @@
+"""Stackless MCP server package."""
+
+import tomllib
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+__all__ = ["__version__"]
+
+
+def _resolve_version() -> str:
+    try:
+        return version("stackless-mcp")
+    except PackageNotFoundError:
+        pyproject = Path(__file__).resolve().parents[1] / "pyproject.toml"
+        try:
+            with pyproject.open("rb") as handle:
+                return str(tomllib.load(handle)["tool"]["poetry"]["version"])
+        except Exception:
+            return "0.0.0"
+
+
+__version__ = _resolve_version()

stackless_mcp/auth.py

@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+import json
+import os
+import secrets
+import stat
+import threading
+import time
+import webbrowser
+from dataclasses import dataclass
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from typing import Any
+from urllib.parse import parse_qs, urlencode, urlparse
+
+import httpx
+
+from stackless_mcp.client import DEFAULT_TIMEOUT_SECONDS
+
+KEYRING_SERVICE = "stackless-mcp"
+FILE_MODE = 0o600
+
+
+@dataclass(frozen=True)
+class StoredCredential:
+    base_url: str
+    token: str
+    expires_at: str | None = None
+    user_id: str | None = None
+
+
+class CredentialStore:
+    def __init__(self, storage: str = "keyring") -> None:
+        if storage not in {"keyring", "file"}:
+            raise ValueError("auth storage must be 'keyring' or 'file'")
+        self.storage = storage
+
+    def load(self, base_url: str) -> StoredCredential | None:
+        if self.storage == "keyring":
+            return self._load_keyring(base_url)
+        return self._load_file(base_url)
+
+    def save(self, credential: StoredCredential) -> None:
+        if self.storage == "keyring":
+            self._save_keyring(credential)
+        else:
+            self._save_file(credential)
+
+    def delete(self, base_url: str) -> None:
+        if self.storage == "keyring":
+            self._delete_keyring(base_url)
+        else:
+            self._delete_file(base_url)
+
+    @staticmethod
+    def _username(base_url: str) -> str:
+        return base_url.rstrip("/")
+
+    @staticmethod
+    def _payload(credential: StoredCredential) -> str:
+        return json.dumps(
+            {
+                "base_url": credential.base_url.rstrip("/"),
+                "token": credential.token,
+                "expires_at": credential.expires_at,
+                "user_id": credential.user_id,
+            },
+            sort_keys=True,
+        )
+
+    @staticmethod
+    def _credential_from_payload(payload: str | None) -> StoredCredential | None:
+        if not payload:
+            return None
+        data = json.loads(payload)
+        token = str(data.get("token") or "")
+        base_url = str(data.get("base_url") or "")
+        if not token or not base_url:
+            return None
+        return StoredCredential(
+            base_url=base_url,
+            token=token,
+            expires_at=data.get("expires_at"),
+            user_id=data.get("user_id"),
+        )
+
+    def _keyring(self):
+        try:
+            import keyring  # type: ignore
+        except Exception as exc:
+            raise RuntimeError(
+                "OS keyring storage is unavailable. Install keyring support or "
+                "rerun with --auth-storage file for an explicit file fallback."
+            ) from exc
+        return keyring
+
+    def _load_keyring(self, base_url: str) -> StoredCredential | None:
+        payload = self._keyring().get_password(
+            KEYRING_SERVICE, self._username(base_url)
+        )
+        return self._credential_from_payload(payload)
+
+    def _save_keyring(self, credential: StoredCredential) -> None:
+        self._keyring().set_password(
+            KEYRING_SERVICE,
+            self._username(credential.base_url),
+            self._payload(credential),
+        )
+
+    def _delete_keyring(self, base_url: str) -> None:
+        try:
+            self._keyring().delete_password(KEYRING_SERVICE, self._username(base_url))
+        except Exception:
+            return
+
+    @staticmethod
+    def _file_path() -> Path:
+        try:
+            from platformdirs import user_config_dir  # type: ignore
+
+            root = Path(user_config_dir("stackless-mcp", "Stackless"))
+        except Exception:
+            root = Path.home() / ".config" / "stackless-mcp"
+        return root / "credentials.json"
+
+    def _load_file(self, base_url: str) -> StoredCredential | None:
+        path = self._file_path()
+        if not path.is_file():
+            return None
+        data = json.loads(path.read_text(encoding="utf-8"))
+        payload = data.get(self._username(base_url))
+        return self._credential_from_payload(json.dumps(payload) if payload else None)
+
+    def _save_file(self, credential: StoredCredential) -> None:
+        path = self._file_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        data: dict[str, Any] = {}
+        if path.is_file():
+            data = json.loads(path.read_text(encoding="utf-8"))
+        data[self._username(credential.base_url)] = json.loads(
+            self._payload(credential)
+        )
+        fd = os.open(str(path), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, FILE_MODE)
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(data, handle, indent=2, sort_keys=True)
+            handle.write("\n")
+        os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)
+
+    def _delete_file(self, base_url: str) -> None:
+        path = self._file_path()
+        if not path.is_file():
+            return
+        data = json.loads(path.read_text(encoding="utf-8"))
+        data.pop(self._username(base_url), None)
+        fd = os.open(str(path), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, FILE_MODE)
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(data, handle, indent=2, sort_keys=True)
+            handle.write("\n")
+        os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)
+
+
+class _LoginCallbackHandler(BaseHTTPRequestHandler):
+    server: "_LoginCallbackServer"
+
+    def do_GET(self) -> None:  # noqa: N802
+        parsed = urlparse(self.path)
+        if parsed.path != "/callback":
+            self.send_error(404)
+            return
+        params = parse_qs(parsed.query)
+        self.server.result = {
+            "code": (params.get("code") or [""])[0],
+            "state": (params.get("state") or [""])[0],
+            "error": (params.get("error") or [""])[0],
+        }
+        body = b"Stackless MCP login complete. You can close this window."
+        self.send_response(200)
+        self.send_header("Content-Type", "text/plain; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def log_message(self, format: str, *args: Any) -> None:
+        return
+
+
+class _LoginCallbackServer(HTTPServer):
+    result: dict[str, str] | None = None
+
+
+def _api_url(base_url: str, path: str) -> str:
+    return f"{base_url.rstrip('/')}/api/v1{path}"
+
+
+def login(
+    *,
+    base_url: str,
+    storage: str = "keyring",
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    open_browser: bool = True,
+    client_name: str = "stackless-mcp",
+) -> StoredCredential:
+    state = secrets.token_urlsafe(24)
+    server = _LoginCallbackServer(("127.0.0.1", 0), _LoginCallbackHandler)
+    redirect_uri = f"http://127.0.0.1:{server.server_port}/callback"
+    login_url = _api_url(
+        base_url,
+        "/mcp/auth/login?"
+        + urlencode(
+            {
+                "state": state,
+                "redirect_uri": redirect_uri,
+                "client_name": client_name,
+            }
+        ),
+    )
+
+    thread = threading.Thread(target=server.handle_request, daemon=True)
+    thread.start()
+    if open_browser:
+        webbrowser.open(login_url)
+    else:
+        print(login_url)
+
+    deadline = time.monotonic() + timeout
+    while server.result is None and time.monotonic() < deadline:
+        time.sleep(0.1)
+    server.server_close()
+    if server.result is None:
+        raise TimeoutError("Timed out waiting for Stackless MCP login callback.")
+    if server.result.get("error"):
+        raise RuntimeError(f"Stackless MCP login failed: {server.result['error']}")
+    code = server.result.get("code") or ""
+    returned_state = server.result.get("state") or ""
+    if not code or returned_state != state:
+        raise RuntimeError("Stackless MCP login callback was missing code or state.")
+
+    response = httpx.post(
+        _api_url(base_url, "/mcp/auth/exchange"),
+        json={"code": code, "state": state, "client_name": client_name},
+        timeout=timeout,
+    )
+    response.raise_for_status()
+    payload = response.json()
+    credential = StoredCredential(
+        base_url=base_url.rstrip("/"),
+        token=payload["token"],
+        expires_at=payload.get("expires_at"),
+        user_id=payload.get("user_id"),
+    )
+    CredentialStore(storage).save(credential)
+    return credential
+
+
+def logout(
+    *,
+    base_url: str,
+    storage: str = "keyring",
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+) -> bool:
+    store = CredentialStore(storage)
+    credential = store.load(base_url)
+    if not credential:
+        return False
+    try:
+        httpx.post(
+            _api_url(base_url, "/mcp/auth/revoke"),
+            headers={"Authorization": f"Bearer {credential.token}"},
+            timeout=timeout,
+        )
+    finally:
+        store.delete(base_url)
+    return True

stackless_mcp/client.py

@@ -0,0 +1,318 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from stackless_mcp import __version__
+
+DEFAULT_TIMEOUT_SECONDS = 120.0
+API_PREFIX = "/api/v1"
+
+
+@dataclass
+class StacklessApiError(Exception):
+    method: str
+    path: str
+    status_code: int
+    detail: Any
+
+    def __str__(self) -> str:
+        detail = self.detail
+        if not isinstance(detail, str):
+            detail = json.dumps(detail, sort_keys=True)
+        return (
+            f"Stackless API {self.method} {self.path} failed "
+            f"with HTTP {self.status_code}: {detail}"
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "error": str(self),
+            "method": self.method,
+            "path": self.path,
+            "status_code": self.status_code,
+            "detail": self.detail,
+        }
+
+
+class StacklessClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        token: str = "",
+        cookie: str = "",
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        if not base_url:
+            raise ValueError("Stackless base URL is required")
+        if not token and not cookie:
+            raise ValueError("Stackless Bearer token or Cookie header is required")
+
+        self.base_url = base_url.rstrip("/")
+        self.token = token.removeprefix("Bearer ").strip() if token else ""
+        self.cookie = cookie.strip()
+        if self.cookie.lower().startswith("cookie:"):
+            self.cookie = self.cookie.split(":", 1)[1].strip()
+        self.timeout = timeout
+        headers = {
+            "Accept": "application/json",
+            "X-Stackless-MCP-Client": f"stackless-mcp/{__version__}",
+        }
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        if self.cookie:
+            headers["Cookie"] = self.cookie
+
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers=headers,
+            follow_redirects=False,
+            transport=transport,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def get(self, path: str, *, params: dict[str, Any] | None = None) -> Any:
+        return self.request("GET", path, params=params)
+
+    def post(
+        self,
+        path: str,
+        *,
+        json_body: Any | None = None,
+        data: dict[str, Any] | None = None,
+        files: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        return self.request(
+            "POST",
+            path,
+            json_body=json_body,
+            data=data,
+            files=files,
+            params=params,
+        )
+
+    def put(self, path: str, *, json_body: Any | None = None) -> Any:
+        return self.request("PUT", path, json_body=json_body)
+
+    def patch(self, path: str, *, json_body: Any | None = None) -> Any:
+        return self.request("PATCH", path, json_body=json_body)
+
+    def delete(self, path: str) -> Any:
+        return self.request("DELETE", path)
+
+    def mcp_tool(
+        self,
+        tool_name: str,
+        *,
+        arguments: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+        confirmation: dict[str, Any] | None = None,
+    ) -> Any:
+        body: dict[str, Any] = {"arguments": arguments or {}}
+        if idempotency_key is not None:
+            body["idempotency_key"] = idempotency_key
+        if confirmation is not None:
+            body["confirmation"] = confirmation
+        return self.post(f"/mcp/tools/{tool_name}", json_body=body)
+
+    def mcp_operation(self, operation_id: str) -> Any:
+        return self.get(f"/mcp/operations/{operation_id}")
+
+    def capabilities(self) -> Any:
+        return self.get("/mcp/capabilities")
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any | None = None,
+        data: dict[str, Any] | None = None,
+        files: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        api_path = self.api_path(path)
+        try:
+            response = self._client.request(
+                method,
+                api_path,
+                json=json_body,
+                data=data,
+                files=files,
+                params=params,
+            )
+        except httpx.RequestError as exc:
+            raise StacklessApiError(
+                method=method,
+                path=api_path,
+                status_code=0,
+                detail={
+                    "message": "Could not reach the Stackless API.",
+                    "error": str(exc),
+                },
+            ) from exc
+        return self._parse_response(method, api_path, response)
+
+    def stream_message(self, conversation_id: str, content: str) -> dict[str, Any]:
+        api_path = self.api_path(f"/agents/conversations/{conversation_id}/messages")
+        text_parts: list[str] = []
+        events: list[dict[str, Any]] = []
+        current_event: str | None = None
+        data_lines: list[str] = []
+
+        try:
+            with self._client.stream(
+                "POST",
+                api_path,
+                json={"content": content},
+                headers={"Accept": "text/event-stream"},
+            ) as response:
+                content_type = response.headers.get("content-type", "").lower()
+                if (
+                    response.status_code >= 300
+                    or "text/event-stream" not in content_type
+                ):
+                    response.read()
+                    parsed = self._parse_response("POST", api_path, response)
+                    if isinstance(parsed, dict):
+                        return parsed
+                    raise StacklessApiError(
+                        method="POST",
+                        path=api_path,
+                        status_code=response.status_code,
+                        detail={
+                            "message": (
+                                "Stackless agent stream returned a non-SSE response."
+                            ),
+                            "content_type": content_type,
+                            "body_preview": self._text_preview(str(parsed)),
+                        },
+                    )
+                for raw_line in response.iter_lines():
+                    line = raw_line.strip()
+                    if not line:
+                        self._consume_sse_event(
+                            current_event,
+                            data_lines,
+                            events,
+                            text_parts,
+                        )
+                        current_event = None
+                        data_lines = []
+                        continue
+                    if line.startswith("event:"):
+                        current_event = line.split(":", 1)[1].strip()
+                    elif line.startswith("data:"):
+                        data_lines.append(line.split(":", 1)[1].strip())
+        except httpx.RequestError as exc:
+            raise StacklessApiError(
+                method="POST",
+                path=api_path,
+                status_code=0,
+                detail={
+                    "message": "Could not reach the Stackless API.",
+                    "error": str(exc),
+                },
+            ) from exc
+
+        self._consume_sse_event(current_event, data_lines, events, text_parts)
+        return {"text": "".join(text_parts), "events": events}
+
+    def api_path(self, path: str) -> str:
+        normalized = path if path.startswith("/") else f"/{path}"
+        if normalized.startswith(API_PREFIX + "/") or normalized == API_PREFIX:
+            return normalized
+        return f"{API_PREFIX}{normalized}"
+
+    @staticmethod
+    def _parse_response(method: str, path: str, response: httpx.Response) -> Any:
+        if response.status_code == 204:
+            return {"ok": True}
+
+        if 300 <= response.status_code < 400:
+            raise StacklessApiError(
+                method=method,
+                path=path,
+                status_code=response.status_code,
+                detail={
+                    "message": (
+                        "Stackless redirected the request. This usually means "
+                        "ALB cookies are missing or expired, or STACKLESS_BASE_URL "
+                        "does not point at the Stackless app origin."
+                    ),
+                    "location": response.headers.get("location", ""),
+                },
+            )
+
+        try:
+            body = response.json()
+        except ValueError:
+            body = response.text
+            if StacklessClient._looks_like_html_response(response, body):
+                raise StacklessApiError(
+                    method=method,
+                    path=path,
+                    status_code=response.status_code,
+                    detail={
+                        "message": (
+                            "Stackless returned HTML instead of JSON. This usually "
+                            "means the request reached the ALB/Cognito login flow "
+                            "instead of the API. Refresh STACKLESS_COOKIE or verify "
+                            "STACKLESS_BASE_URL."
+                        ),
+                        "content_type": response.headers.get("content-type", ""),
+                        "body_preview": StacklessClient._text_preview(body),
+                    },
+                )
+
+        if response.status_code >= 400:
+            detail = body.get("detail", body) if isinstance(body, dict) else body
+            raise StacklessApiError(
+                method=method,
+                path=path,
+                status_code=response.status_code,
+                detail=detail,
+            )
+        return body
+
+    @staticmethod
+    def _looks_like_html_response(response: httpx.Response, body: str) -> bool:
+        content_type = response.headers.get("content-type", "").lower()
+        if "text/html" in content_type:
+            return True
+        stripped = body.lstrip().lower()
+        return stripped.startswith("<!doctype html") or stripped.startswith("<html")
+
+    @staticmethod
+    def _text_preview(text: str, limit: int = 500) -> str:
+        compact = " ".join(text.split())
+        if len(compact) <= limit:
+            return compact
+        return compact[:limit] + "..."
+
+    @staticmethod
+    def _consume_sse_event(
+        event: str | None,
+        data_lines: list[str],
+        events: list[dict[str, Any]],
+        text_parts: list[str],
+    ) -> None:
+        if not event or not data_lines:
+            return
+        data_text = "\n".join(data_lines)
+        try:
+            data = json.loads(data_text)
+        except ValueError:
+            data = {"raw": data_text}
+        events.append({"event": event, "data": data})
+        if event == "text" and isinstance(data, dict):
+            text_parts.append(str(data.get("delta", "")))