kaitencloud-mcp 0.2.0__py3-none-any.whl

kaiten_mcp/__init__.py

@@ -0,0 +1,4 @@
+# Copyright 2026 KAITEN INC
+# SPDX-License-Identifier: Apache-2.0
+
+"""Kaiten MCP server."""

kaiten_mcp/__main__.py

@@ -0,0 +1,43 @@
+# Copyright 2026 KAITEN INC
+# SPDX-License-Identifier: Apache-2.0
+
+"""kaiten-mcp: run the server over stdio (local clients) or Streamable HTTP (remote clients)."""
+
+from __future__ import annotations
+
+import argparse
+
+import uvicorn
+
+from .config import settings
+from .server import build, http_app
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="kaiten-mcp", description="Kaiten MCP server")
+    parser.add_argument(
+        "transport",
+        nargs="?",
+        choices=["stdio", "http"],
+        default="stdio",
+        help="stdio for a local client that spawns the server (uses KAITEN_API_TOKEN); "
+        "http to serve Streamable HTTP at /mcp, authenticating each request by its own bearer token",
+    )
+    parser.add_argument("--host", default=settings.host)
+    parser.add_argument("--port", type=int, default=settings.port)
+    parser.add_argument(
+        "--read-only",
+        action="store_true",
+        help="register read tools only (or KAITEN_MCP_READ_ONLY=true)",
+    )
+    args = parser.parse_args()
+
+    mcp = build(writes=False if args.read_only else None)
+    if args.transport == "stdio":
+        mcp.run(transport="stdio", show_banner=False)
+    else:
+        uvicorn.run(http_app(mcp), host=args.host, port=args.port, log_level="info")
+
+
+if __name__ == "__main__":
+    main()

kaiten_mcp/config.py

@@ -0,0 +1,50 @@
+# Copyright 2026 KAITEN INC
+# SPDX-License-Identifier: Apache-2.0
+
+"""Process configuration, read once from the environment."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+def _flag(name: str) -> bool:
+    return os.getenv(name, "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+@dataclass(frozen=True)
+class Settings:
+    # Where the MCP server sends its API calls. It must be the gateway (Envoy),
+    # not the API container: the gateway is what exchanges a ksh_ token for the
+    # internal JWT the API trusts, and a client's ksh_ token reaches this
+    # server untouched.
+    api_base_url: str
+    # Used when no request header carries a credential: the stdio transport,
+    # or a single-user HTTP deployment.
+    api_token: str
+    # Register only the tools that read. The credential still bounds what an
+    # agent can do; this bounds what it can even attempt.
+    read_only: bool
+    host: str
+    port: int
+    timeout: float
+
+
+def load() -> Settings:
+    base = (
+        os.getenv("KAITEN_API_BASE_URL")
+        or os.getenv("KAITEN_API_URL")
+        or "http://localhost:6060/api"
+    )
+    return Settings(
+        api_base_url=base.rstrip("/"),
+        api_token=os.getenv("KAITEN_API_TOKEN", "").strip(),
+        read_only=_flag("KAITEN_MCP_READ_ONLY"),
+        host=os.getenv("MCP_HOST", "0.0.0.0"),
+        port=int(os.getenv("MCP_PORT", "8000")),
+        timeout=float(os.getenv("KAITEN_API_TIMEOUT", "30")),
+    )
+
+
+settings = load()

kaiten_mcp/sdk.py

@@ -0,0 +1,111 @@
+# Copyright 2026 KAITEN INC
+# SPDX-License-Identifier: Apache-2.0
+
+"""Kaiten, reached through the official SDK.
+
+The MCP server declares no API contract of its own: paths, request bodies,
+models, enums and the enforcement arithmetic all come from ``kaitencloud``,
+which is generated from Kaiten's OpenAPI document. One client is shared by the
+whole process; its credential is a callable, read before every request, that
+returns the bearer token of whoever is calling the MCP server -- so an agent
+never acts with more than its own token allows.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastmcp.exceptions import ToolError
+from fastmcp.server.dependencies import get_http_request
+from fastmcp.server.middleware import Middleware
+from kaitencloud import APIStatusError, AsyncKaitenClient, KaitenError, NotFoundError
+
+from .config import settings
+
+_client: AsyncKaitenClient | None = None
+
+
+def caller_token() -> str:
+    """The calling client's token: its Authorization header, else KAITEN_API_TOKEN (stdio)."""
+    try:
+        header = get_http_request().headers.get("authorization") or ""
+    except RuntimeError:  # not inside an HTTP request: stdio
+        header = ""
+    token = header or settings.api_token
+    if token.lower().startswith("bearer "):
+        token = token[7:]
+    if not token.strip():
+        raise ToolError(
+            "No Kaiten credential: send 'Authorization: Bearer ksh_...' to the MCP server, "
+            "or set KAITEN_API_TOKEN for the stdio transport."
+        )
+    return token.strip()
+
+
+def kaiten() -> AsyncKaitenClient:
+    global _client
+    if _client is None:
+        _client = AsyncKaitenClient(
+            token=caller_token, base_url=settings.api_base_url, timeout=settings.timeout
+        )
+    return _client
+
+
+def use(client: AsyncKaitenClient | None) -> None:
+    """Swap the shared client; tests point it at a mocked transport."""
+    global _client
+    _client = client
+
+
+async def get_or_none(call: Any) -> Any:
+    """Await an SDK read, mapping 404 to None."""
+    try:
+        return await call
+    except NotFoundError:
+        return None
+
+
+async def require(call: Any, what: str) -> Any:
+    """Await an SDK read, mapping 404 to an error that tells the agent how to recover."""
+    try:
+        return await call
+    except NotFoundError as e:
+        raise ToolError(
+            f"No {what} found ({e.detail}). Use kaiten_search to find the right slug."
+        ) from e
+
+
+# The SDK wraps every operation an application calls; the targeting authoring
+# endpoints and OFREP evaluation are left to the console and to OpenFeature.
+# These go through the SDK's own transport (credential, retries, typed errors)
+# and decode to plain JSON, until sdk-python grows methods for them.
+
+
+async def call_unwrapped(
+    method: str, path: str, body: Any = None, *, idempotent: bool | None = None
+) -> Any:
+    api = kaiten()._api
+    response = await api.request(method, path, body=body, idempotent=idempotent)
+    return api.decode(response)
+
+
+def describe(e: APIStatusError) -> str:
+    message = f"Kaiten API {e.status_code} {e.code or ''}: {e.detail or e.title or ''}".replace(
+        "  ", " "
+    )
+    for err in e.errors or []:
+        where = getattr(err, "location", None) or ""
+        message += f"\n  - {where}: {getattr(err, 'message', err)}"
+    return message
+
+
+class KaitenErrors(Middleware):
+    """Turn SDK errors into tool errors that carry the API's code and detail, the parts an agent can act on."""
+
+    async def on_call_tool(self, context, call_next):
+        try:
+            return await call_next(context)
+        except APIStatusError as e:
+            raise ToolError(describe(e)) from e
+        except KaitenError as e:
+            raise ToolError(f"Kaiten: {e}") from e

kaiten_mcp/server.py

@@ -0,0 +1,95 @@
+# Copyright 2026 KAITEN INC
+# SPDX-License-Identifier: Apache-2.0
+
+"""The Kaiten MCP server: intent-level tools over Kaiten's API."""
+
+from __future__ import annotations
+
+import os
+from importlib.metadata import PackageNotFoundError, version
+
+import httpx
+from fastmcp import FastMCP
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from .config import settings
+from .sdk import KaitenErrors
+from .tools import register_all
+
+try:
+    VERSION = version("kaitencloud-mcp")
+except PackageNotFoundError:  # running from a source tree
+    VERSION = "0.0.0"
+
+INSTRUCTIONS = """\
+Kaiten is the control plane of a B2B SaaS vendor: what each customer bought, what they may use, how much
+they used, and where it runs. Everything belongs to one organization (the vendor), and is named by slug.
+
+The model, top down:
+- Customer: a client of the vendor. It runs one or more Instances (a deployment of the product for it).
+- Instance: sits on one exact License version, optionally in a Deployment Zone, with a license term
+  (start/end), an operational status and a commercial lifecycle stage.
+- Plan = license family (e.g. 'premium'). Its versions are Licenses (e.g. 'premium-v3'), each DRAFT,
+  PUBLISHED or ARCHIVED. A plan serves its default version, else its highest published one.
+- A License grants Entitlements: BOOLEAN features, NUMBER quotas (and AI credits) metered by usage
+  reports, and CONFIG values. A NUMBER grant is unlimited (-1), a hard limit, or soft with an overage %.
+- Feature flags are evaluated through OpenFeature, with CEL targeting rules reading the customer's
+  license and entitlements, and the instance, customer and zone (under __kaiten).
+- Deployment zones run immutable Releases, each a set of versioned Components.
+
+How to work:
+- Start with kaiten_overview, find things with kaiten_search, and read with the kaiten_get_* tools.
+- Writes merge: only what you pass changes. Every write answers with status created / updated /
+  unchanged / rejected / deleted and exactly what changed; 'unchanged' means nothing was written.
+- Look before you change something shared: kaiten_get_catalog(plan=...) shows the instances on each
+  license version, and kaiten_delete without confirm previews what a deletion touches.
+- Prefer a new license version (kaiten_save_license new_version_of=...) to editing a published version
+  in place: editing changes every instance on it immediately.
+- Usage reports are not idempotent; never repeat one that answered.
+"""
+
+
+def build(*, writes: bool | None = None) -> FastMCP:
+    mcp = FastMCP(
+        "Kaiten",
+        instructions=INSTRUCTIONS,
+        version=VERSION,
+        website_url="https://kaiten.sh",
+        middleware=[KaitenErrors()],
+    )
+    register_all(mcp, writes=not settings.read_only if writes is None else writes)
+
+    @mcp.custom_route("/health", methods=["GET"], include_in_schema=False)
+    async def health(_: Request) -> JSONResponse:
+        try:
+            async with httpx.AsyncClient(timeout=5.0) as c:
+                r = await c.get(f"{settings.api_base_url}/healthz")
+            # A Community Edition gateway serves /healthz to anyone; Kaiten Cloud's asks for a
+            # token and answers 401. Either way, Kaiten answered at that address.
+            api = {"reachable": r.status_code in (200, 401), "status": r.status_code}
+        except httpx.HTTPError as e:
+            api = {"reachable": False, "error": str(e)}
+        return JSONResponse(
+            {
+                "status": "ok" if api["reachable"] else "degraded",
+                "version": VERSION,
+                "read_only": settings.read_only,
+                "api": {"url": settings.api_base_url, **api},
+            }
+        )
+
+    return mcp
+
+
+def http_app(mcp: FastMCP):
+    """The Streamable HTTP app, stateless so any replica can serve any request."""
+    allowed_hosts = [h for h in os.getenv("MCP_ALLOWED_HOSTS", "").split(",") if h.strip()]
+    allowed_origins = [o for o in os.getenv("MCP_ALLOWED_ORIGINS", "").split(",") if o.strip()]
+    return mcp.http_app(
+        path="/mcp",
+        stateless_http=True,
+        host_origin_protection="auto",
+        allowed_hosts=allowed_hosts or None,
+        allowed_origins=allowed_origins or None,
+    )

kaiten_mcp/shapes.py

@@ -0,0 +1,301 @@
+# Copyright 2026 KAITEN INC
+# SPDX-License-Identifier: Apache-2.0
+
+"""How Kaiten resources are shown to an agent, and how its inputs are read.
+
+The SDK's models carry everything a console needs: ids, audit users,
+timestamps. An agent reasons better over less, so every tool projects a model
+onto the fields that carry meaning and names it by slug -- the identifier
+every tool accepts back. The enforcement arithmetic is the SDK's own
+(``kaitencloud.usage``), so a limit reads here exactly as the server applies it.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, date, datetime, timedelta
+from typing import Any
+
+from fastmcp.exceptions import ToolError
+from kaitencloud import usage as enforcement
+
+SLUG = re.compile(r"^[a-z0-9][a-z0-9-]*[a-z0-9]$")
+UNLIMITED = enforcement.UNLIMITED
+METERED = ("NUMBER", "NUMBER_AI_CREDIT")
+
+
+def slug(value: str, what: str = "slug") -> str:
+    value = (value or "").strip()
+    if not SLUG.match(value) or len(value) > 100:
+        raise ToolError(
+            f"{what} {value!r} is not a Kaiten slug: lowercase letters, digits and dashes, "
+            "2-100 characters, starting and ending with a letter or digit."
+        )
+    return value
+
+
+def drop_none(d: dict[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in d.items() if v is not None}
+
+
+# --- time -------------------------------------------------------------------
+
+
+def now() -> datetime:
+    return datetime.now(UTC)
+
+
+def rfc3339(t: datetime) -> str:
+    return t.astimezone(UTC).isoformat(timespec="seconds").replace("+00:00", "Z")
+
+
+def parse_time(value: str, what: str = "date") -> datetime:
+    """Accept '2027-01-31', '2027-01-31T12:00:00Z' or any ISO 8601 timestamp."""
+    raw = value.strip()
+    try:
+        if len(raw) == 10:
+            d = date.fromisoformat(raw)
+            return datetime(d.year, d.month, d.day, tzinfo=UTC)
+        t = datetime.fromisoformat(raw.replace("Z", "+00:00"))
+        return t if t.tzinfo else t.replace(tzinfo=UTC)
+    except ValueError as e:
+        raise ToolError(f"{what} {value!r} is not an ISO 8601 date or timestamp") from e
+
+
+def as_time(value: datetime | str | None) -> datetime | None:
+    if value is None or isinstance(value, datetime):
+        return value
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def iso(value: datetime | str | None) -> str | None:
+    t = as_time(value)
+    return rfc3339(t) if t else None
+
+
+def days_until(value: datetime | str | None) -> int | None:
+    t = as_time(value)
+    return None if t is None else (t - now()).days
+
+
+def plus_days(t: datetime, days: int) -> datetime:
+    return t + timedelta(days=days)
+
+
+# --- values and limits ------------------------------------------------------
+
+
+def plain(value: Any) -> Any:
+    """Unwrap a typed entitlement value ({type, value[, event_count]}) to the value itself."""
+    if value is None:
+        return None
+    if isinstance(value, dict):
+        return value.get("value", value)
+    return getattr(value, "value", value)
+
+
+def grant_value(raw: Any) -> Any:
+    """Read a grant value an agent wrote: 'unlimited' is the SDK's UNLIMITED sentinel."""
+    return UNLIMITED if raw == "unlimited" else raw
+
+
+def usage_state(
+    used: float | None,
+    limit: float | None,
+    overage_percent: int | None = None,
+    warning_percent: int | None = None,
+) -> dict[str, Any]:
+    """Where a metered usage stands against its grant.
+
+    States: ok; warning (at or past the entitlement's warning threshold);
+    at_limit (exactly the included value); overage (past the value, within the
+    grant's allowance); over (past what the server accepts); unlimited.
+    """
+    used = used or 0
+    if limit is None:
+        return {"used": used, "limit": None, "state": "not_granted"}
+    if enforcement.is_unlimited(limit) or overage_percent == UNLIMITED:
+        return {"used": used, "limit": "unlimited", "state": "unlimited"}
+    out: dict[str, Any] = {"used": used, "limit": limit}
+    pct = enforcement.percentage_used(limit, used)
+    out["percent"] = round(pct, 1) if pct is not None else None
+    if enforcement.is_soft_limit(limit, overage_percent):
+        out["hard_ceiling"] = enforcement.maximum_allowed_usage(limit, overage_percent)
+    if not enforcement.accepts(limit, used, overage_percent):
+        state = "over"
+    elif used > limit:
+        state = "overage"
+    elif used == limit:
+        state = "at_limit"
+    elif warning_percent and pct is not None and pct >= warning_percent:
+        state = "warning"
+    else:
+        state = "ok"
+    out["state"] = state
+    return out
+
+
+ATTENTION_STATES = {"warning", "at_limit", "overage", "over"}
+
+
+# --- projections ------------------------------------------------------------
+
+
+def customer(c: Any) -> dict:
+    return drop_none(
+        {
+            "slug": c.slug,
+            "name": c.name,
+            "domain": c.domain,
+            "external_customer_id": c.external_customer_id,
+            "integrations": {
+                k: getattr(v, "external_id", v) for k, v in (c.integrations or {}).items()
+            }
+            or None,
+        }
+    )
+
+
+def instance(i: Any) -> dict:
+    return drop_none(
+        {
+            "slug": i.slug,
+            "name": i.name,
+            "description": i.description or None,
+            "customer": i.customer_slug,
+            "license": i.license_slug,
+            "deployment_zone": i.deployment_zone_slug,
+            "status": i.status,
+            "lifecycle_stage": i.lifecycle_stage,
+            "license_start": iso(i.start_license_date),
+            "license_end": iso(i.end_license_date),
+            "license_days_left": days_until(i.end_license_date),
+            "metadata": i.metadata or None,
+        }
+    )
+
+
+def license_(lic: Any, plan: str | None = None) -> dict:
+    return drop_none(
+        {
+            "slug": lic.slug,
+            "name": lic.name,
+            "plan": plan or lic.family_slug,
+            "version": lic.version,
+            "version_name": lic.version_name,
+            "type": lic.type,
+            "state": lic.lifecycle_state,
+            "is_default": lic.is_default,
+            "description": lic.description or None,
+        }
+    )
+
+
+def entitlement(e: Any) -> dict:
+    return drop_none(
+        {
+            "slug": e.slug,
+            "name": e.name,
+            "type": e.type,
+            "description": e.description or None,
+            "aggregation": e.aggregation_method,
+            "reset_period": e.reset_period,
+            "reset_anchor": e.reset_anchor,
+            "unit": e.unit_plural or e.unit_singular,
+            "warning_threshold_percent": e.warning_threshold_percent or None,
+            "user_facing": e.user_facing,
+            "groups": [g.slug for g in e.entitlement_groups or []] or None,
+        }
+    )
+
+
+def grant(g: Any) -> dict:
+    value = plain(g.value)
+    out: dict[str, Any] = {
+        "entitlement": g.entitlement_slug,
+        "type": g.entitlement_type,
+        "value": value,
+    }
+    pct = g.limit_cap_exceeded_overage_percent
+    if g.entitlement_type in METERED:
+        if enforcement.is_unlimited(value):
+            out["value"] = "unlimited"
+        elif enforcement.is_soft_limit(value, pct):
+            out["overage_percent"] = pct
+        else:
+            out["limit"] = "hard"
+    return out
+
+
+def zone(z: Any) -> dict:
+    return drop_none(
+        {
+            "slug": z.slug,
+            "name": z.name,
+            "type": z.type,
+            "description": z.description or None,
+            "metadata": z.metadata or None,
+        }
+    )
+
+
+def release(r: Any) -> dict:
+    return drop_none(
+        {
+            "slug": r.slug,
+            "version": r.version,
+            "description": r.description or None,
+            "created_at": iso(r.created_at),
+            "components": [f"{c.name}@{c.version}" for c in r.components or []] or None,
+        }
+    )
+
+
+# --- write reports ----------------------------------------------------------
+
+
+def changes(before: dict, after: dict) -> dict[str, dict[str, Any]]:
+    """Field-by-field difference between two flat projections."""
+    return {
+        key: {"from": before.get(key), "to": after.get(key)}
+        for key in sorted(set(before) | set(after))
+        if before.get(key) != after.get(key)
+    }
+
+
+def merge_map(current: dict | None, patch: dict | None) -> dict:
+    """Merge patch into current; a key set to null is removed."""
+    merged = dict(current or {})
+    for key, value in (patch or {}).items():
+        if value is None:
+            merged.pop(key, None)
+        else:
+            merged[key] = value
+    return merged
+
+
+def report(
+    status: str,
+    kind: str,
+    resource: dict | None,
+    *,
+    changes: dict | None = None,
+    notes: list[str] | None = None,
+    **extra: Any,
+) -> dict:
+    """The answer every write gives: what happened, to what, and what changed.
+
+    status is created, updated, unchanged, recorded, deleted, rejected or
+    preview. 'unchanged' is a real outcome, not a failure: the resource was
+    already in the requested state and nothing was written. 'rejected' means
+    Kaiten (or a pre-flight check) refused, and nothing was written either.
+    """
+    out: dict[str, Any] = {"status": status, "kind": kind}
+    if resource is not None:
+        out[kind] = resource
+    if changes:
+        out["changes"] = changes
+    out.update(drop_none(extra))
+    if notes:
+        out["notes"] = notes
+    return out

kaiten_mcp/tools/__init__.py

@@ -0,0 +1,41 @@
+# Copyright 2026 KAITEN INC
+# SPDX-License-Identifier: Apache-2.0
+
+"""The tool catalogue, one module per area of Kaiten.
+
+Every module registers its read tools always, and its write tools only when
+the server is not read-only. Annotations tell the client which is which.
+"""
+
+from __future__ import annotations
+
+from fastmcp import FastMCP
+
+# Kaiten is the only world these tools touch, so none is open-world.
+READ = {"readOnlyHint": True, "openWorldHint": False}
+WRITE = {
+    "readOnlyHint": False,
+    "destructiveHint": False,
+    "idempotentHint": True,
+    "openWorldHint": False,
+}
+# A write whose repetition is not a no-op: a usage report counts every time.
+APPEND = {
+    "readOnlyHint": False,
+    "destructiveHint": False,
+    "idempotentHint": False,
+    "openWorldHint": False,
+}
+DESTRUCTIVE = {
+    "readOnlyHint": False,
+    "destructiveHint": True,
+    "idempotentHint": True,
+    "openWorldHint": False,
+}
+
+
+def register_all(mcp: FastMCP, *, writes: bool) -> None:
+    from . import access, accounts, catalog, delete, flags, overview, releases, settings, usage
+
+    for module in (overview, accounts, usage, catalog, flags, releases, access, settings, delete):
+        module.register(mcp, writes=writes)