kitsu-mcp 0.3.0__py3-none-any.whl

kitsu_mcp/__init__.py

@@ -0,0 +1,33 @@
+"""MCP server for the Kitsu (CGWire) production tracker."""
+
+import argparse
+import os
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="kitsu-mcp", description=__doc__)
+    parser.add_argument("--http", action="store_true", help="serve over HTTP (hosted connector) instead of stdio")
+    parser.add_argument("--host", default=os.environ.get("KITSU_HTTP_HOST", "127.0.0.1"))
+    parser.add_argument("--port", type=int, default=int(os.environ.get("PORT", "8000")))
+    parser.add_argument(
+        "--behind-tls",
+        action="store_true",
+        default=os.environ.get("KITSU_BEHIND_TLS", "").lower() in ("1", "true", "yes"),
+        help="confirm HTTPS terminates in front of the server (required to bind a non-loopback host)",
+    )
+    args = parser.parse_args()
+
+    from kitsu_mcp.config import get_settings, require_login
+    from kitsu_mcp.server import mcp
+
+    settings = get_settings()
+    if not args.http:
+        require_login(settings)
+    if settings.allow_write:
+        mcp.enable(tags={"write"})
+    if args.http:
+        from kitsu_mcp import http
+
+        http.run(args.host, args.port, args.behind_tls)
+    else:
+        mcp.run()

kitsu_mcp/__main__.py

@@ -0,0 +1,3 @@
+from kitsu_mcp import main
+
+main()

kitsu_mcp/app.py

@@ -0,0 +1,45 @@
+"""The shared FastMCP instance. Tool modules register on it when imported."""
+
+import inspect
+
+from fastmcp import FastMCP
+
+mcp = FastMCP(
+    "kitsu",
+    instructions=(
+        "Access to a Kitsu production tracker. Tools accept project, task type, status and "
+        "person names as well as IDs (case-insensitive). Status filters use task status short "
+        "names (e.g. wip, wfa, done); list_task_statuses shows them and the role each one plays here "
+        "(done, omitted, on hold, waiting review, ...), which every count and filter follows. Durations "
+        'and estimates are in minutes. List tools return compact rows by default (detail="full" for '
+        "more). Use kitsu_get for any read the other tools don't cover. Write tools "
+        "(comments, status changes, assignments, schedule, time logs, playlists) only exist when the server "
+        "runs with KITSU_ALLOW_WRITE=true. For write tools, call with dry_run=True first and show the user the "
+        "plan before writing; then confirm with the user before calling them for real."
+    ),
+)
+
+READ_ONLY = {"readOnlyHint": True, "openWorldHint": True}
+
+
+# One small schema for every data tool instead of a detailed one per tool: clients still get structured
+# results (fastmcp's `.data`, `structured_content`), while the tool list stays about half the size.
+_GENERIC_OUTPUT = {"type": "object", "properties": {"result": {}}, "x-fastmcp-wrap-result": True}
+
+
+def tool(**kwargs):
+    """Register a tool on `mcp` with a generic output schema instead of a detailed one.
+
+    Detailed output schemas were half of what every session paid in context before any call; the field
+    notes that matter are in the docstrings. Tools that can return images keep no schema at all, since
+    images cannot be structured content. The decorated function itself is returned unchanged, so other
+    modules (resources) can still call it directly.
+    """
+
+    def register(fn):
+        returns = str(inspect.signature(fn).return_annotation)
+        schema = None if "Image" in returns else _GENERIC_OUTPUT
+        mcp.tool(output_schema=schema, **kwargs)(fn)
+        return fn
+
+    return register

kitsu_mcp/auth.py

@@ -0,0 +1,177 @@
+"""Per-caller Kitsu credentials for the HTTP transport.
+
+Over stdio the server logs in with KITSU_USER / KITSU_PASSWORD. Over HTTP (a hosted server used as a Le Chat or
+AI Studio connector) each caller sends their own Kitsu login in the `Authorization` header, and every tool call
+runs as that person. The server's own login is never used for HTTP calls.
+"""
+
+import base64
+import binascii
+import hashlib
+import hmac
+import secrets
+import threading
+import time
+from collections import OrderedDict
+from dataclasses import dataclass
+
+from fastmcp.exceptions import ToolError
+from fastmcp.server.dependencies import get_http_request
+
+AUTH_HELP = (
+    "Kitsu login missing: set the connector's authentication to Basic with your Kitsu email and password "
+    "(or a Bearer token of the form email:password)."
+)
+
+
+# Keys derived from credentials are HMACs under a secret that only lives in this process, so a key seen
+# elsewhere (a cache folder name, a dump) cannot be checked against password guesses offline.
+_SECRET = secrets.token_bytes(32)
+
+
+def keyed_hash(value: str) -> str:
+    return hmac.new(_SECRET, value.encode(), hashlib.sha256).hexdigest()
+
+
+@dataclass(frozen=True)
+class Credentials:
+    user: str
+    password: str
+
+    @property
+    def key(self) -> str:
+        """Cache key for this login (user and password), so passwords never sit in the cache as dict keys."""
+        return keyed_hash(f"{self.user}\0{self.password}")
+
+    @property
+    def user_key(self) -> str:
+        """Key of the user alone, e.g. for their video cache folder (Kitsu authorizes every cache hit)."""
+        return keyed_hash(self.user.lower())
+
+    def __repr__(self) -> str:
+        return f"Credentials(user={self.user!r}, password='***')"
+
+
+def parse_authorization(header: str) -> Credentials | None:
+    """Kitsu email and password from `Basic base64(email:password)` or `Bearer email:password`."""
+    scheme, _, value = header.strip().partition(" ")
+    value = value.strip()
+    if scheme.lower() == "basic":
+        try:
+            value = base64.b64decode(value, validate=True).decode("utf-8")
+        except (binascii.Error, UnicodeDecodeError):
+            return None
+    elif scheme.lower() != "bearer":
+        return None
+    user, sep, password = value.partition(":")
+    if not sep or not user or not password:
+        return None
+    return Credentials(user.strip(), password)
+
+
+def request_credentials() -> Credentials | None:
+    """The caller's credentials when the current call came over HTTP; None over stdio (no HTTP request).
+
+    Raises when the call came over HTTP without usable credentials, so it can never fall back to the
+    server's own login.
+    """
+    try:
+        request = get_http_request()
+    except RuntimeError:
+        return None
+    credentials = parse_authorization(request.headers.get("authorization", ""))
+    if credentials is None:
+        raise ToolError(AUTH_HELP)
+    return credentials
+
+
+class TTLCache[T]:
+    """A small thread-safe LRU cache whose entries expire `ttl` seconds after they were last used."""
+
+    def __init__(self, ttl: float, max_size: int) -> None:
+        self.ttl = ttl
+        self.max_size = max_size
+        self._items: OrderedDict[str, tuple[float, T]] = OrderedDict()
+        self._lock = threading.Lock()
+
+    def get_or_create(self, key: str, create) -> T:
+        found = self.get(key)
+        if found is not None:
+            return found
+        value = create()
+        self.put(key, value)
+        return value
+
+    def get(self, key: str) -> T | None:
+        now = time.monotonic()
+        with self._lock:
+            self._expire(now)
+            if key not in self._items:
+                return None
+            value = self._items.pop(key)[1]
+            self._items[key] = (now, value)
+            return value
+
+    def put(self, key: str, value: T) -> None:
+        now = time.monotonic()
+        with self._lock:
+            self._expire(now)
+            self._items.pop(key, None)
+            self._items[key] = (now, value)
+            while len(self._items) > self.max_size:
+                self._items.popitem(last=False)
+
+    def _expire(self, now: float) -> None:
+        for stale in [k for k, (used, _) in self._items.items() if now - used > self.ttl]:
+            del self._items[stale]
+
+    def clear(self) -> None:
+        with self._lock:
+            self._items.clear()
+
+    def __len__(self) -> int:
+        return len(self._items)
+
+
+class LoginThrottle:
+    """Slows down repeated failed logins per user, so the server is not an unthrottled password relay to Kitsu.
+
+    Only rejected credentials count (an unreachable Kitsu does not). A login Kitsu accepted in the last
+    `remember` seconds skips the check, so guessing at someone's email cannot lock them out. Spraying many
+    emails from one address is not throttled here. The first `free` failures in a row cost nothing; after
+    that, the next attempt must wait 2**(failures - free) seconds (capped) since the last failure. A success
+    resets the count. Bounded: the oldest users are forgotten past `max_users`.
+    """
+
+    def __init__(self, free: int = 5, cap: float = 60, max_users: int = 4096, remember: float = 24 * 3600) -> None:
+        self.free = free
+        self.cap = cap
+        self.max_users = max_users
+        self._failures: OrderedDict[str, tuple[int, float]] = OrderedDict()
+        # Keys (HMACs) of logins Kitsu accepted in the last `remember` seconds: they bypass the throttle.
+        self._good: TTLCache[bool] = TTLCache(ttl=remember, max_size=max_users)
+        self._lock = threading.Lock()
+
+    def known_good(self, login_key: str) -> bool:
+        return self._good.get(login_key) is not None
+
+    def check(self, user_key: str) -> None:
+        with self._lock:
+            count, last = self._failures.get(user_key, (0, 0.0))
+        if count <= self.free:
+            return
+        wait = min(self.cap, 2 ** (count - self.free)) - (time.monotonic() - last)
+        if wait > 0:
+            raise ToolError(f"Too many failed Kitsu logins for this account; try again in {wait:.0f} s")
+
+    def failed(self, user_key: str) -> None:
+        with self._lock:
+            count, _ = self._failures.pop(user_key, (0, 0.0))
+            self._failures[user_key] = (count + 1, time.monotonic())
+            while len(self._failures) > self.max_users:
+                self._failures.popitem(last=False)
+
+    def succeeded(self, user_key: str, login_key: str) -> None:
+        with self._lock:
+            self._failures.pop(user_key, None)
+        self._good.put(login_key, True)

kitsu_mcp/client.py

@@ -0,0 +1,244 @@
+"""Thin wrapper over gazu's raw HTTP client: lazy login, re-login on expiry, retries."""
+
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+import gazu
+import requests
+from fastmcp.exceptions import ToolError
+from gazu import client as raw
+from gazu.exception import (
+    AuthFailedException,
+    GazuException,
+    NotAllowedException,
+    NotAuthenticatedException,
+    ParameterException,
+    PreviewFileProcessingException,
+    RouteNotFoundException,
+    ServerErrorException,
+    ValidationException,
+)
+
+from kitsu_mcp.auth import Credentials, LoginThrottle, TTLCache, request_credentials
+from kitsu_mcp.config import Settings, get_settings
+
+# requests.JSONDecodeError: a proxy answered 503/504 with an HTML page (gazu only raises on 500/502).
+_TRANSIENT = (ServerErrorException, requests.ConnectionError, requests.Timeout, requests.JSONDecodeError)
+
+
+class NotFoundError(ToolError):
+    """Kitsu answered 404: wrong ID, or a route this instance does not have."""
+
+
+class LoginRejected(ToolError):
+    """Kitsu refused the email/password (not an outage): the only failure the login throttle counts."""
+
+
+class FileTooLargeError(ToolError):
+    """A download went past its size cap and was stopped."""
+
+
+def size_guard(path: str, max_bytes: int | None):
+    """Progress callback for downloads that stops them once they exceed `max_bytes`."""
+
+    def check(bytes_read: int, total: int) -> None:
+        if max_bytes is not None and max(bytes_read, total) > max_bytes:
+            raise FileTooLargeError(f"{path} is larger than the {max_bytes / 2**20:.0f} MB download cap")
+
+    return check
+
+
+class KitsuClient:
+    def __init__(self, settings: Settings, credentials: Credentials | None = None) -> None:
+        """`credentials`: log in as this person instead of KITSU_USER / KITSU_PASSWORD (HTTP callers)."""
+        self.settings = settings
+        self.credentials = credentials
+        self._raw: raw.KitsuClient | None = None
+        self._lock = threading.Lock()
+        self._relogging = threading.local()
+
+    def _connect(self) -> raw.KitsuClient:
+        with self._lock:
+            if self._raw is None:
+                client = raw.create_client(
+                    self.settings.host,
+                    use_refresh_token=True,
+                    callback_not_authenticated=self._relogin,
+                )
+                _apply_timeout(client.session, self.settings.timeout)
+                # Mark the first login as in progress too, so a 401 on it does not trigger a second attempt.
+                self._relogging.active = True
+                try:
+                    self._log_in(client)
+                finally:
+                    self._relogging.active = False
+                self._raw = client
+            return self._raw
+
+    def connect(self) -> None:
+        """Log in now (instead of on the first request), reporting a rejected login as a ToolError."""
+        try:
+            self._connect()
+        except (NotAuthenticatedException, AuthFailedException) as error:
+            raise LoginRejected(str(_tool_error(error, "POST", "auth/login"))) from error
+        except (requests.ConnectionError, requests.Timeout, requests.JSONDecodeError, ServerErrorException) as error:
+            raise ToolError(
+                f"Could not log in: Kitsu is unreachable or unavailable ({error.__class__.__name__})"
+            ) from error
+        except (GazuException, requests.RequestException) as error:
+            raise _tool_error(error, "POST", "auth/login") from error
+
+    def _log_in(self, client: raw.KitsuClient) -> None:
+        if self.credentials is not None:
+            gazu.log_in(self.credentials.user, self.credentials.password, client=client)
+            return
+        if not self.settings.user or self.settings.password is None:
+            raise RuntimeError("Missing configuration: KITSU_USER, KITSU_PASSWORD")
+        gazu.log_in(self.settings.user, self.settings.password.get_secret_value(), client=client)
+
+    def _relogin(self, client: raw.KitsuClient, _path: str) -> bool:
+        """gazu callback when the access and refresh tokens are both rejected.
+
+        The login request goes through the same client, so a 401 on `auth/login` would call back
+        here again; the guard makes that nested call give up instead of recursing.
+        """
+        if getattr(self._relogging, "active", False):
+            return False
+        self._relogging.active = True
+        try:
+            self._log_in(client)
+        except GazuException:
+            return False
+        finally:
+            self._relogging.active = False
+        return True
+
+    def _call(self, method: str, path: str, fn, *args, retry: bool = True, **kwargs) -> Any:
+        """Run a gazu request; reads retry transient failures, writes never do (they may have landed)."""
+        attempts = self.settings.max_retries if retry else 1
+        for attempt in range(attempts):
+            try:
+                return fn(*args, client=self._connect(), **kwargs)
+            except _TRANSIENT as error:
+                if attempt == attempts - 1:
+                    raise _tool_error(error, method, path) from error
+                time.sleep(0.5 * 2**attempt)
+            except (GazuException, requests.RequestException) as error:
+                raise _tool_error(error, method, path) from error
+        raise AssertionError("unreachable: max_retries >= 1")
+
+    def get(self, path: str, params: dict | None = None) -> Any:
+        return self._call("GET", path, raw.get, path, params=params)
+
+    def get_bytes(self, path: str) -> bytes:
+        return self._call("GET", path, raw.get_file_data_from_url, path)
+
+    def download(self, path: str, dest: Path, max_bytes: int | None = None) -> int:
+        """Stream a file to `dest` (waiting for previews Kitsu is still processing); returns its size."""
+        self._call("GET", path, raw.download, path, str(dest), progress_callback=size_guard(path, max_bytes))
+        return dest.stat().st_size
+
+    def post(self, path: str, data: Any) -> Any:
+        return self._call("POST", path, raw.post, path, data, retry=False)
+
+    def put(self, path: str, data: dict) -> Any:
+        return self._call("PUT", path, raw.put, path, data, retry=False)
+
+    def user_id(self) -> str:
+        return self.get("auth/authenticated")["user"]["id"]
+
+
+def _apply_timeout(session: requests.Session, timeout: float) -> None:
+    request = session.request
+
+    def request_with_timeout(method, url, **kwargs):
+        kwargs.setdefault("timeout", timeout)
+        return request(method, url, **kwargs)
+
+    session.request = request_with_timeout  # type: ignore[method-assign]
+
+
+def _tool_error(error: Exception, method: str, path: str) -> ToolError:
+    if isinstance(error, RouteNotFoundException):
+        return NotFoundError(f"Not found: {path} (wrong ID, or the route does not exist)")
+    if isinstance(error, PreviewFileProcessingException):
+        return ToolError(f"Kitsu is still processing {path}; try again in a minute")
+    if isinstance(error, NotAllowedException):
+        return ToolError(f"Permission denied for {method} {path}")
+    if isinstance(error, (NotAuthenticatedException, AuthFailedException)):
+        return ToolError("Kitsu rejected the credentials; check the Kitsu email and password")
+    if isinstance(error, (ParameterException, ValidationException)):
+        return ToolError(f"Kitsu rejected {method} {path}: {error}")
+    if isinstance(error, requests.JSONDecodeError | requests.ConnectionError | requests.Timeout) and method != "GET":
+        # The request may have reached Zou before the proxy or connection gave up.
+        return ToolError(
+            f"No usable answer from Kitsu on {method} {path} ({error.__class__.__name__}); the change MAY have "
+            "been applied. Check the current state (e.g. get_task) before retrying."
+        )
+    if isinstance(error, requests.JSONDecodeError):
+        return ToolError(f"Kitsu returned a non-JSON response on {method} {path} (server or proxy unavailable?)")
+    if isinstance(error, (requests.ConnectionError, requests.Timeout)):
+        return ToolError(f"Could not reach Kitsu on {method} {path}: {error.__class__.__name__}")
+    return ToolError(f"Kitsu error on {method} {path}: {error.__class__.__name__} {error}")
+
+
+_override: KitsuClient | None = None
+_server_client: KitsuClient | None = None
+_server_lock = threading.Lock()
+_user_clients: TTLCache[KitsuClient] = TTLCache(ttl=3600, max_size=256)
+_logins = LoginThrottle()
+_login_locks: TTLCache[threading.Lock] = TTLCache(ttl=3600, max_size=4096)
+_login_locks_guard = threading.Lock()
+
+
+def get_client() -> KitsuClient:
+    """The Kitsu client for the current call.
+
+    Over HTTP: the caller's own, from their `Authorization` header (never the server's login). Over stdio:
+    the server's, logged in as KITSU_USER.
+    """
+    global _server_client
+    if _override is not None:
+        return _override
+    credentials = request_credentials()
+    if credentials is not None:
+        return _user_client(credentials)
+    with _server_lock:
+        if _server_client is None:
+            _server_client = KitsuClient(get_settings())
+        return _server_client
+
+
+def _user_client(credentials: Credentials) -> KitsuClient:
+    """A caller's logged-in client. Only successful logins are cached, so wrong passwords cannot push real
+    users out of the cache; repeated failures for one account are slowed down (LoginThrottle)."""
+    cached = _user_clients.get(credentials.key)
+    if cached is not None:
+        return cached
+    with _login_locks_guard:
+        lock = _login_locks.get_or_create(credentials.user_key, threading.Lock)
+    with lock:  # one login at a time per account; concurrent first calls reuse the winner's client
+        cached = _user_clients.get(credentials.key)
+        if cached is not None:
+            return cached
+        # A login Kitsu accepted recently skips the throttle: someone who only knows the email cannot lock
+        # out the person who knows the password.
+        if not _logins.known_good(credentials.key):
+            _logins.check(credentials.user_key)
+        client = KitsuClient(get_settings(), credentials)
+        try:
+            client.connect()
+        except LoginRejected:
+            _logins.failed(credentials.user_key)
+            raise
+        _logins.succeeded(credentials.user_key, credentials.key)
+        _user_clients.put(credentials.key, client)
+        return client
+
+
+def set_client(client: KitsuClient | None) -> None:
+    """Swap the shared client (used by tests); None goes back to the normal per-call choice."""
+    global _override
+    _override = client

kitsu_mcp/config.py

@@ -0,0 +1,77 @@
+"""Server settings, read from environment variables or a `.env` in the working directory."""
+
+from functools import lru_cache
+from pathlib import Path
+from urllib.parse import urlsplit, urlunsplit
+
+from pydantic import Field, SecretStr
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="KITSU_", env_file=".env", extra="ignore")
+
+    host: str
+    """Zou API URL, e.g. https://example.cg-wire.com/api."""
+    user: str | None = None
+    """Kitsu login for stdio. Over HTTP each caller sends their own, and these are not used."""
+    password: SecretStr | None = None
+    allow_write: bool = False
+    """Register tools that modify Kitsu (comments, status changes, assignments, ...)."""
+    cache_ttl: float = Field(300, ge=0)
+    """Seconds to keep reference data (task types, statuses, people, ...) before refetching."""
+    timeout: float = Field(30, gt=0)
+    """Per-request timeout in seconds."""
+    max_retries: int = Field(3, ge=1)
+    """Attempts for idempotent requests that fail with a server or network error."""
+    video_cache_dir: Path | None = None
+    """Where downloaded movies are cached (default: a kitsu-mcp-videos folder in the system temp dir)."""
+    video_cache_mb: int = Field(1024, ge=0)
+    """Size of the movie cache; the least recently used movies are deleted past it."""
+    video_max_mb: int = Field(500, gt=0)
+    """Largest movie the video tools will download."""
+    # Status roles. Each is a comma-separated list of task status short names or names (case-insensitive).
+    # A listed status takes that role; any other status gets its role from Kitsu's flags. Checked in this
+    # order, so a status in two lists takes the first.
+    omitted_statuses: str = "omit,na,n/a,omitted,cancelled,canceled"
+    """Dropped, not finished: left out of progress and open work (Kitsu flags them done)."""
+    done_statuses: str = ""
+    """Finished, even if Kitsu flags them otherwise, e.g. "cbb" for a "could be better" status flagged retake."""
+    on_hold_statuses: str = "stand by,standby,pause,paused,blocked,on hold"
+    """Open but paused: never counted as overdue or in progress."""
+    review_statuses: str = ""
+    """Waiting for review/approval, in addition to statuses Kitsu flags as feedback requests."""
+    retake_statuses: str = ""
+    """Sent back for changes, in addition to statuses Kitsu flags as retakes."""
+    dry_run_log: Path | None = None
+    """JSONL file that every write-tool dry run (dry_run=True) is appended to."""
+
+
+@lru_cache
+def get_settings() -> Settings:
+    try:
+        return Settings()  # type: ignore[call-arg]
+    except Exception as error:
+        missing = [
+            f"KITSU_{e['loc'][0]}".upper() for e in getattr(error, "errors", lambda: [])() if e.get("type") == "missing"
+        ]
+        if missing:
+            raise RuntimeError(f"Missing configuration: {', '.join(missing)}") from error
+        raise
+
+
+def require_login(settings: Settings) -> None:
+    """Over stdio the server logs in as KITSU_USER; fail at startup, not on the first tool call."""
+    missing = [
+        name for name, value in (("KITSU_USER", settings.user), ("KITSU_PASSWORD", settings.password)) if not value
+    ]
+    if missing:
+        raise RuntimeError(f"Missing configuration: {', '.join(missing)}")
+
+
+def without_userinfo(url: str) -> str:
+    """A host URL without any user:password@ part (a proxy login must never reach callers)."""
+    parts = urlsplit(url)
+    if "@" not in parts.netloc:
+        return url
+    return urlunsplit(parts._replace(netloc=parts.netloc.rsplit("@", 1)[1]))