mlspace-plugin 0.2.1__py3-none-any.whl

mlspace_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""mlspace_mcp — MCP server for the Cloud.ru MLSpace public API v2."""
+
+__version__ = "0.2.1"

mlspace_mcp/__main__.py

@@ -0,0 +1,125 @@
+"""CLI entry point for mlspace-plugin."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import sys
+from pathlib import Path
+
+from . import __version__
+from .config import load_settings, user_config_file
+from .server import build_server
+
+
+def _configure_logging() -> None:
+    """Basic stderr logging so the server's logger.warning/exception emit in prod.
+    Level via MLSPACE_LOG_LEVEL (default INFO). stderr keeps stdout clean for stdio MCP.
+    """
+    level = os.environ.get("MLSPACE_LOG_LEVEL", "INFO").upper()
+    logging.basicConfig(
+        level=getattr(logging, level, logging.INFO),
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        stream=sys.stderr,
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="mlspace-plugin",
+        description="MCP server for the Cloud.ru MLSpace public API v2.",
+    )
+    parser.add_argument("--version", action="version", version=f"mlspace-plugin {__version__}")
+    parser.add_argument(
+        "--transport",
+        choices=["streamable-http", "stdio"],
+        help="Override MLSPACE_TRANSPORT.",
+    )
+    parser.add_argument(
+        "--list-tools",
+        action="store_true",
+        help="Print the tools that would be registered, then exit (no credentials needed).",
+    )
+    # Optional subcommand: with none given the CLI serves, as it always has.
+    sub = parser.add_subparsers(dest="command")
+    setup = sub.add_parser(
+        "setup",
+        help="Set up access keys, workspaces, MCP clients and skills.",
+        description=(
+            "Ask for Cloud.ru Key ID and Key Secret, discover MLSpace workspaces, and write them to "
+            f"{user_config_file()} with mode 600. Runs in your terminal: the values "
+            "are never sent to a model."
+        ),
+    )
+    setup.add_argument("--path", type=Path, help="Write somewhere else than the user config.")
+    setup.add_argument("--force", action="store_true", help="Overwrite an existing file.")
+    setup.add_argument(
+        "--base-url",
+        help="MLSpace API endpoint to save (defaults to production or the existing target).",
+    )
+    setup.add_argument(
+        "--no-verify", action="store_true", help="Save unverified config offline; requires --config-only and --workspace."
+    )
+    setup.add_argument("--client", dest="clients", action="append", choices=["claude-code", "codex", "opencode"], help="Connect this client (repeat for several); default: auto-detect.")
+    setup.add_argument("--client-path", dest="client_paths", action="append", metavar="CLIENT=PATH", help="Explicit client executable when not in PATH.")
+    setup.add_argument("--config-only", action="store_true", help="Only configure credentials/workspaces; do not register clients or skills.")
+    setup.add_argument("--non-interactive", action="store_true", help="Never prompt; require explicit workspace IDs and credential source or saved keys.")
+    setup.add_argument("--from-env", action="store_true", help="Use MLSPACE_CLIENT_ID / MLSPACE_CLIENT_SECRET from the environment.")
+    setup.add_argument("--credentials-file", type=Path, help="Import keys from an existing dotenv file without printing them.")
+    setup.add_argument("--replace-credentials", action="store_true", help="Ask for new keys instead of reusing saved keys.")
+    setup.add_argument("--workspace", dest="workspace_ids", action="append", help="Exact workspace ID to select (repeat for several).")
+    setup.add_argument("--ca-file", type=Path, help="Trusted corporate CA PEM; a copy is saved for subsequent MCP launches.")
+    setup.add_argument("--list-workspaces", action="store_true", help="Return a bounded JSON list without saving or installing anything.")
+    setup.add_argument("--search", default="", help="Filter workspace JSON by name, project or ID.")
+    setup.add_argument("--offset", type=int, default=0)
+    setup.add_argument("--limit", type=int, default=20, help="Workspace JSON page size (1–100).")
+    args = parser.parse_args(argv)
+
+    if args.command == "setup":
+        from .init_cli import run_init
+
+        return run_init(
+            args.path,
+            force=args.force,
+            verify=not args.no_verify,
+            base_url=args.base_url,
+            config_only=args.config_only, non_interactive=args.non_interactive,
+            from_env=args.from_env, credentials_file=args.credentials_file,
+            workspace_ids=args.workspace_ids, clients=args.clients, client_paths=args.client_paths,
+            ca_file=args.ca_file, replace_credentials=args.replace_credentials,
+            list_workspaces=args.list_workspaces, search=args.search, offset=args.offset, limit=args.limit,
+        )
+
+    _configure_logging()
+    settings = load_settings()
+    if args.transport:
+        settings.transport = args.transport
+
+    if args.list_tools:
+        mcp = build_server(settings)
+        tools = mcp._tool_manager.list_tools()
+        mode = "read-only" if settings.readonly else "read-write"
+        print(f"mlspace-plugin {__version__} — {len(tools)} tools ({mode}):")
+        for tool in sorted(tools, key=lambda t: t.name):
+            print(f"  {tool.name}")
+        return 0
+
+    settings.validate_bind()
+    settings.require_credentials()
+    mcp = build_server(settings)
+
+    if settings.transport == "stdio":
+        mcp.run(transport="stdio")
+    else:
+        print(
+            f"mlspace-plugin serving streamable-HTTP on "
+            f"http://{settings.host}:{settings.port}/mcp",
+            file=sys.stderr,
+        )
+        mcp.run(transport="streamable-http")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mlspace_mcp/_status.py

@@ -0,0 +1,18 @@
+"""Single source of truth for the JobStatus canonical spelling map.
+
+Kept in its own tiny leaf module (it imports NOTHING from the package) so both
+``registry.py`` and ``formatting.py`` can share ONE copy without reintroducing a
+tools -> registry -> formatting import cycle. Previously each held an intentional
+twin copy guarded by a drift test; now there is exactly one.
+"""
+
+from __future__ import annotations
+
+# Mirrors the spec ``JobStatus-Input`` enum: casefold -> canonical spelling.
+JOB_STATUS_CANON: dict[str, str] = {
+    s.casefold(): s
+    for s in (
+        "Completed", "Completing", "Deleted", "Failed", "Pending", "Running",
+        "Stopped", "Succeeded", "Terminated", "Terminating", "Restarting",
+    )
+}

mlspace_mcp/auth.py

@@ -0,0 +1,109 @@
+"""Service-account token management for the MLSpace API.
+
+``POST /public/v2/service_auth`` exchanges ``{client_id, client_secret}`` for a
+short-lived (≈1h) bearer token. The response nests the token:
+``{"token": {"access_token": "...", "expires_in": 3600}}`` — the sibling
+status/error_* fields are deprecated and must NOT be read.
+
+Refresh is single-flight: concurrent callers (and concurrent 401 retries against
+a revoked token) collapse into exactly one ``/service_auth`` call.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+
+import httpx
+
+from .errors import MLSpaceError, error_from_exception, error_from_response
+
+_EXPIRY_SKEW = 60.0  # refresh this many seconds before the token actually expires
+
+
+class TokenManager:
+    def __init__(
+        self,
+        http: httpx.AsyncClient,
+        base_url: str,
+        client_id: str,
+        client_secret: str,
+    ):
+        self._http = http
+        self._url = base_url.rstrip("/") + "/public/v2/service_auth"
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._token: str | None = None
+        self._expiry: float = 0.0
+        self._version: int = 0
+        self._lock = asyncio.Lock()
+
+    @staticmethod
+    def _now() -> float:
+        return time.monotonic()
+
+    def _valid(self) -> bool:
+        return self._token is not None and self._now() < self._expiry
+
+    async def get_token(self) -> tuple[str, int]:
+        """Return ``(token, version)``, refreshing if missing/expired."""
+        if self._valid():
+            return self._token, self._version  # type: ignore[return-value]
+        async with self._lock:
+            if self._valid():  # someone refreshed while we waited
+                return self._token, self._version  # type: ignore[return-value]
+            await self._refresh()
+            return self._token, self._version  # type: ignore[return-value]
+
+    async def refresh_after_401(self, used_version: int) -> tuple[str, int]:
+        """Force a refresh after a 401, but only if no one else already has.
+
+        All concurrent 401s share the same ``used_version`` so they collapse into
+        a single ``/service_auth`` call.
+        """
+        async with self._lock:
+            if self._version != used_version and self._valid():
+                return self._token, self._version  # type: ignore[return-value]
+            await self._refresh()
+            return self._token, self._version  # type: ignore[return-value]
+
+    async def _refresh(self) -> None:
+        # IMPORTANT: never send Authorization/x-api-key/x-workspace-id here.
+        try:
+            resp = await self._http.post(
+                self._url,
+                json={"client_id": self._client_id, "client_secret": self._client_secret},
+            )
+        except Exception as exc:  # transport-level
+            raise error_from_exception(exc) from exc
+
+        if resp.status_code == 401:
+            raise MLSpaceError(
+                "Invalid service-account credentials (401 from /service_auth).",
+                status=401,
+                hint="Check MLSPACE_CLIENT_ID and MLSPACE_CLIENT_SECRET.",
+            )
+        if resp.status_code >= 400:
+            raise error_from_response(resp)
+
+        try:
+            payload = resp.json()
+        except Exception as exc:
+            raise MLSpaceError("Auth response was not valid JSON.") from exc
+
+        token_obj = (payload or {}).get("token") or {}
+        access_token = token_obj.get("access_token")
+        expires_in = token_obj.get("expires_in")
+        if not access_token:
+            raise MLSpaceError(
+                "Auth response missing token.access_token.",
+                hint="Unexpected /service_auth response shape.",
+            )
+        try:
+            ttl = float(expires_in) if expires_in is not None else 3600.0
+        except (TypeError, ValueError):
+            ttl = 3600.0
+        self._token = access_token
+        # non-positive TTL (0 / negative) -> treat as already expired, refresh next call
+        self._expiry = self._now() + (max(ttl - _EXPIRY_SKEW, 1.0) if ttl > 0 else 0.0)
+        self._version += 1

mlspace_mcp/bodyspec.py

@@ -0,0 +1,184 @@
+"""Spec-driven request-body help + LENIENT validation.
+
+Schemas come from the bundled build artifact ``spec/body_schemas.json`` (one
+self-contained JSON Schema per "METHOD /path", refs under ``$defs``). Loaded once.
+
+Design stance (deliberate — see DESIGN.md): the live API is the real validator.
+``lint`` is **fail-open** — it reports only HIGH-CONFIDENCE structural problems
+(missing required field incl. nested, clear scalar-type mismatch, enum
+violation) and stays silent on anything it can't be sure about (anyOf/oneOf
+variants, unknown constructs, extra properties). It must never reject a body the
+API would accept; the goal is to catch the obvious "forgot a required field"
+before a round-trip, not to re-implement OpenAPI validation.
+"""
+
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+_ARTIFACT = Path(__file__).parent / "spec" / "body_schemas.json"
+_MAX_DEPTH = 8
+
+
+@lru_cache(maxsize=1)
+def _all() -> dict[str, dict]:
+    if not _ARTIFACT.exists():
+        return {}
+    return json.loads(_ARTIFACT.read_text())
+
+
+def schema_for(method: str, path: str) -> dict | None:
+    return _all().get(f"{method.upper()} {path}")
+
+
+def _resolve(node: Any, defs: dict) -> Any:
+    """Resolve a $ref / single-ref allOf to its target schema (one hop)."""
+    seen = 0
+    while isinstance(node, dict) and seen < 16:
+        if "$ref" in node:
+            name = node["$ref"].split("/")[-1]
+            node = defs.get(name, {})
+        elif "allOf" in node and len(node["allOf"]) == 1 and "$ref" in node["allOf"][0]:
+            name = node["allOf"][0]["$ref"].split("/")[-1]
+            target = defs.get(name, {})
+            # merge sibling keys (e.g. description) over the target
+            node = {**target, **{k: v for k, v in node.items() if k != "allOf"}}
+        else:
+            break
+        seen += 1
+    return node
+
+
+def _types(schema: dict) -> set[str]:
+    t = schema.get("type")
+    if isinstance(t, str):
+        return {t}
+    if isinstance(t, list):
+        return set(t)
+    return set()
+
+
+def _enum_str(schema: dict) -> str:
+    e = schema.get("enum")
+    if not isinstance(e, list):
+        return ""
+    if len(e) <= 6:
+        return ":" + "|".join(str(x) for x in e)
+    return f":<{len(e)} options>"  # mark long enums instead of dropping silently
+
+
+# ---- description hint -------------------------------------------------------
+
+
+def summarize(schema: dict) -> str:
+    """One-line shape hint for the tool description (required fields + nested)."""
+    defs = schema.get("$defs", {})
+    root = _resolve(schema, defs)
+    if not isinstance(root, dict) or "properties" not in root:
+        return ""
+    required = root.get("required", []) or []
+    props = root.get("properties", {})
+
+    def field(name: str) -> str:
+        sub = _resolve(props.get(name, {}), defs)
+        if "object" in _types(sub) or "properties" in sub:
+            sub_req = sub.get("required", []) or []
+            inner = ", ".join(
+                n + _enum_str(_resolve(sub.get("properties", {}).get(n, {}), defs))
+                for n in sub_req
+            )
+            return f"{name}{{{inner}}}" if inner else f"{name}{{...}}"
+        return name + _enum_str(sub)
+
+    req = [field(n) for n in required]
+    optional_all = [n for n in props if n not in required]
+    optional = optional_all[:6]
+    parts = []
+    if req:
+        parts.append("required: " + ", ".join(req))
+    if optional:
+        more = f" (+{len(optional_all) - len(optional)} more)" if len(optional_all) > len(optional) else ""
+        parts.append("optional: " + ", ".join(optional) + more)
+    return "; ".join(parts)
+
+
+# ---- lenient validation -----------------------------------------------------
+
+_JSON_TYPE: dict[str, Any] = {
+    "string": str,
+    "integer": int,
+    "number": (int, float),
+    "boolean": bool,
+    "array": list,
+    "object": dict,
+}
+
+
+def _type_ok(value: Any, types: set[str]) -> bool:
+    if not types:
+        return True
+    if value is None:
+        return "null" in types or True  # nullability is often implicit; stay lenient
+    for t in types:
+        py = _JSON_TYPE.get(t)
+        if py is None:
+            return True  # unknown type token -> don't judge
+        if t in ("integer", "number") and isinstance(value, bool):
+            continue  # bool is not a number here
+        if t == "integer" and isinstance(value, float) and value.is_integer():
+            return True  # 5.0 for an integer field: backends coerce — don't reject
+        if isinstance(value, py):
+            return True
+    return False
+
+
+def lint(schema: dict, value: Any) -> list[str]:
+    """Return high-confidence problems with ``value`` against ``schema`` (or [])."""
+    defs = schema.get("$defs", {})
+    errors: list[str] = []
+
+    def check(node: Any, val: Any, path: str, depth: int) -> None:
+        if depth > _MAX_DEPTH:
+            return
+        node = _resolve(node, defs)
+        if not isinstance(node, dict):
+            return
+        # unions / combinators: too ambiguous to enforce safely -> skip
+        if any(k in node for k in ("anyOf", "oneOf")) or (
+            "allOf" in node and len(node.get("allOf", [])) > 1
+        ):
+            return
+
+        types = _types(node)
+        if types and not _type_ok(val, types):
+            errors.append(f"{path or 'body'}: expected {'/'.join(sorted(types))}, got {type(val).__name__}")
+            return
+
+        # NOTE: enum membership is deliberately NOT enforced here. Enums are exactly
+        # what a cloud platform expands over time (new regions/connectors/...); a
+        # hard local check would fail-closed on a value the live API now accepts,
+        # violating this module's fail-open contract. The API (422) validates enums;
+        # summarize() still surfaces the known values as a hint to the model.
+
+        if ("object" in types or "properties" in node) and isinstance(val, dict):
+            for req in node.get("required", []) or []:
+                # flag only when the KEY is absent; explicit null is left to the API
+                # (a required+nullable field sent as null is valid — never reject it)
+                if req not in val:
+                    errors.append(f"{path + '.' if path else ''}{req}: required field is missing")
+            for key, sub in (node.get("properties") or {}).items():
+                if key in val and val[key] is not None:
+                    check(sub, val[key], f"{path + '.' if path else ''}{key}", depth + 1)
+        elif "array" in types and isinstance(val, list):
+            items = node.get("items")
+            if isinstance(items, dict) and val:
+                check(items, val[0], f"{path}[]", depth + 1)
+
+    try:
+        check(schema, value, "", 0)
+    except Exception:
+        return []  # fail-open: never block on an internal hiccup
+    return errors

mlspace_mcp/client.py

@@ -0,0 +1,170 @@
+"""The single HTTP entry point to the MLSpace API.
+
+The client owns ALL header injection (Authorization + x-api-key + x-workspace-id),
+path templating, query encoding (repeated keys for list values), and JSON bodies
+(attached for any method, including DELETE). Tools never touch headers.
+
+Frozen contract (do not change without updating every tools/*.py):
+
+    async def request(
+        self,
+        method: str,
+        path_template: str,
+        *,
+        path_params: dict[str, str] | None = None,
+        params: dict | list[tuple] | None = None,
+        json_body: Any | None = None,
+    ) -> Any
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from typing import Any
+
+import httpx
+
+from .auth import TokenManager
+from .errors import MLSpaceError, error_from_exception, error_from_response
+
+# Defence-in-depth: even values that reach the client WITHOUT going through
+# resolve_request's per-segment encoding (the guard/namespace prechecks call
+# ``request`` directly with a raw id) must never carry a traversal or control char
+# into the final path. resolve_request is the primary route-confusion guard; this
+# is the last line before the wire.
+_CTRL_RE = re.compile(r"[\x00-\x1f\x7f]")
+
+
+def _assert_safe_path(path: str) -> None:
+    if _CTRL_RE.search(path):
+        raise MLSpaceError("Refusing to send a request whose path contains control chars.")
+    for seg in path.split("/"):
+        if seg in ("..", "."):
+            raise MLSpaceError(
+                f"Refusing a request whose path contains a '{seg}' traversal segment "
+                f"({path!r}) — a path parameter must be a single opaque id/name."
+            )
+
+
+class MLSpaceClient:
+    def __init__(
+        self,
+        http: httpx.AsyncClient,
+        tokens: TokenManager,
+        *,
+        base_url: str,
+        api_key: str,
+        workspace_id: str,
+        namespace: str = "",
+    ):
+        self._http = http
+        self._tokens = tokens
+        self._base = base_url.rstrip("/")
+        self._api_key = api_key
+        self._workspace_id = workspace_id
+        # k8s namespace of the configured workspace; resolved lazily from
+        # workspace_id when not pinned via config.
+        self._namespace: str | None = namespace or None
+        self._ns_lock = asyncio.Lock()
+
+    @property
+    def workspace_id(self) -> str:
+        return self._workspace_id
+
+    async def workspace_namespace(self) -> str | None:
+        """The configured workspace's k8s namespace, resolved once and cached.
+
+        Returns None if it can't be determined (caller then falls back to asking
+        the model for it). Single-flight: concurrent first-callers collapse into
+        one ``workspaces/v3/{id}`` lookup.
+        """
+        if self._namespace is not None:
+            return self._namespace
+        async with self._ns_lock:
+            if self._namespace is not None:
+                return self._namespace
+            try:
+                data = await self.request(
+                    "GET",
+                    "/public/v2/workspaces/v3/{workspace_id}",
+                    path_params={"workspace_id": self._workspace_id},
+                )
+            except Exception:
+                return None  # leave uncached: retry on a later call
+            ns = data.get("namespace") if isinstance(data, dict) else None
+            if ns:
+                self._namespace = ns
+            return ns
+
+    def _headers(self, token: str) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {token}",
+            "x-api-key": self._api_key,
+            "x-workspace-id": self._workspace_id,
+        }
+
+    async def request(
+        self,
+        method: str,
+        path_template: str,
+        *,
+        path_params: dict[str, str] | None = None,
+        params: Any = None,
+        json_body: Any = None,
+    ) -> Any:
+        if path_params:
+            try:
+                path = path_template.format(**path_params)
+            except KeyError as exc:
+                raise MLSpaceError(
+                    f"Missing path parameter {exc} for {path_template}."
+                ) from exc
+        else:
+            path = path_template
+        _assert_safe_path(path)
+        url = self._base + path
+
+        token, version = await self._tokens.get_token()
+        resp = await self._send(method, url, token, params, json_body)
+
+        if resp.status_code == 401:
+            # token may be revoked/expired-early — single-flight force refresh, retry once
+            token, _ = await self._tokens.refresh_after_401(version)
+            resp = await self._send(method, url, token, params, json_body)
+
+        if resp.status_code >= 400:
+            raise error_from_response(resp)
+        return self._parse(resp)
+
+    async def _send(
+        self, method: str, url: str, token: str, params: Any, json_body: Any
+    ) -> httpx.Response:
+        kwargs: dict[str, Any] = {"headers": self._headers(token)}
+        if params is not None:
+            kwargs["params"] = params
+        if json_body is not None:
+            kwargs["json"] = json_body  # attached for any method, incl. DELETE
+        try:
+            return await self._http.request(method, url, **kwargs)
+        except MLSpaceError:
+            raise
+        except Exception as exc:
+            raise error_from_exception(exc) from exc
+
+    @staticmethod
+    def _parse(resp: httpx.Response) -> Any:
+        if resp.status_code == 204 or not resp.content:
+            return None
+        ctype = resp.headers.get("content-type", "").lower()
+        # explicit binary (e.g. dalle image) — don't dump raw bytes into context
+        if ctype.startswith(("image/", "audio/", "video/", "application/octet-stream")):
+            return f"<binary response, {len(resp.content)} bytes, content-type={ctype}>"
+        # json / text / unknown-or-missing content-type — try json, then text
+        try:
+            return resp.json()
+        except Exception:
+            try:
+                return resp.text
+            except Exception:
+                return f"<{len(resp.content)} bytes, content-type={ctype or 'unknown'}>"