docket-client 0.3.2__py3-none-any.whl

docket_mcp/config.py

@@ -0,0 +1,57 @@
+"""Configuration, read from environment variables (documented in client/README.md)."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+from .times import get_zone, system_zone_name
+
+__all__ = ["DEFAULT_API_URL", "Settings", "normalise_api_url"]
+
+DEFAULT_API_URL = "http://localhost:8001"
+
+
+def normalise_api_url(url: str) -> str:
+    """The server origin: accepts the API origin or a frontend origin + ``/api``."""
+    url = url.strip().rstrip("/")
+    if url.endswith("/api"):
+        url = url[: -len("/api")]
+    return url
+
+
+@dataclass(frozen=True)
+class Settings:
+    api_url: str = DEFAULT_API_URL
+    time_zone: str = "UTC"
+    # Entra sign-in (the docket_auth providers). DOCKET_API_TOKEN is read by the token provider
+    # itself, on every request, and is deliberately not held here.
+    client_id: str | None = None
+    client_secret: str | None = None
+    scope: str | None = None
+    tenant_id: str | None = None
+    authority: str | None = None
+    cache_path: Path | None = None
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str] | None = None) -> Settings:
+        env = os.environ if env is None else env
+
+        def get(name: str) -> str | None:
+            return (env.get(name) or "").strip() or None
+
+        zone = get("DOCKET_TIME_ZONE") or system_zone_name()
+        get_zone(zone)  # fail at startup, not on the first tool call
+        cache = get("DOCKET_AUTH_CACHE_PATH")
+        return cls(
+            api_url=normalise_api_url(get("DOCKET_API_URL") or DEFAULT_API_URL),
+            time_zone=zone,
+            client_id=get("DOCKET_AUTH_CLIENT_ID"),
+            client_secret=get("DOCKET_AUTH_CLIENT_SECRET"),
+            scope=get("DOCKET_AUTH_SCOPE"),
+            tenant_id=get("DOCKET_AUTH_TENANT_ID"),
+            authority=get("DOCKET_AUTH_AUTHORITY"),
+            cache_path=Path(cache) if cache else Path.home() / ".docket" / "mcp-token-cache.json",
+        )

docket_mcp/server.py

@@ -0,0 +1,78 @@
+"""The ``docket-mcp`` entry point: a FastMCP server over stdio.
+
+stdout carries the MCP protocol, so everything else (sign-in instructions, logs) goes to stderr.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import sys
+import typing
+from collections.abc import Callable
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from .api import DocketApi, DocketToolError
+from .config import Settings
+from .times import TimeError
+from .tools import TOOL_NAMES, DocketTools
+
+__all__ = ["build_server", "main"]
+
+INSTRUCTIONS = """\
+Docket schedules acquisitions on AIND rigs. Use the read tools to look things up, then the
+write tools to change the schedule. Every write tool previews by default (dry_run=true): show
+the user what would happen, and only repeat the call with dry_run=false once they agree.
+Times are local wall-clock (no offsets) plus an IANA zone; results give local time and UTC.
+"""
+
+
+def _as_tool(method: Callable[..., Any]) -> Callable[..., Any]:
+    """Wrap a tool method: report expected failures as tool errors, keep the typed signature."""
+
+    @functools.wraps(method)
+    def tool(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return method(*args, **kwargs)
+        except TimeError as error:
+            raise DocketToolError(str(error)) from None
+
+    # The annotations are strings (``from __future__``) that only resolve in tools.py's namespace.
+    hints = typing.get_type_hints(method, include_extras=True)
+    signature = inspect.signature(method)
+    tool.__signature__ = signature.replace(  # type: ignore[attr-defined]
+        parameters=[
+            p.replace(annotation=hints.get(name, p.annotation))
+            for name, p in signature.parameters.items()
+        ],
+        return_annotation=hints.get("return", signature.return_annotation),
+    )
+    tool.__annotations__ = hints
+    return tool
+
+
+def build_server(api: DocketApi) -> FastMCP:
+    server = FastMCP("docket", instructions=INSTRUCTIONS)
+    tools = DocketTools(api)
+    for name in TOOL_NAMES:
+        server.add_tool(_as_tool(getattr(tools, name)), name=name)
+    return server
+
+
+def main() -> None:
+    try:
+        settings = Settings.from_env()
+    except (TimeError, ValueError) as error:
+        print(f"docket-mcp: {error}", file=sys.stderr)
+        raise SystemExit(2) from None
+    print(
+        f"docket-mcp: using {settings.api_url} (time zone {settings.time_zone})",
+        file=sys.stderr,
+    )
+    build_server(DocketApi(settings)).run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

docket_mcp/signin.py

@@ -0,0 +1,155 @@
+"""Credential choice for write calls, and a device-code sign-in that never blocks a tool call.
+
+Order: a Docket API token (``DOCKET_API_TOKEN``) first, then Entra: client credentials when
+``DOCKET_AUTH_CLIENT_SECRET`` is set, otherwise the device-code flow for a person.
+
+``msal``'s device flow blocks until the person has signed in, but an MCP tool call must return.
+`BackgroundSignIn` runs it on a thread, sends the instructions to stderr and raises
+`SignInRequired` carrying the same text, so a client that hides stderr still shows the
+code in the tool error. Once signed in the next call finds a warm cache.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import threading
+from collections.abc import Callable
+
+from docket_auth import (
+    ClientCredentialsTokenProvider,
+    DeviceCodeTokenProvider,
+    TokenProvider,
+    api_token_provider,
+)
+
+from .config import Settings
+
+__all__ = ["BackgroundSignIn", "SignInRequired", "build_provider"]
+
+
+class SignInRequired(Exception):
+    """The person must complete the device-code sign-in; the message says how."""
+
+
+class _Job:
+    def __init__(self) -> None:
+        self.ready = threading.Event()  # instructions available, or finished
+        self.done = threading.Event()
+        self.message: str | None = None
+        self.token: str | None = None
+        self.error: BaseException | None = None
+
+
+class BackgroundSignIn:
+    """Wraps a blocking device-code provider; see the module docstring."""
+
+    def __init__(
+        self,
+        make_provider: Callable[[Callable[[str], None]], TokenProvider],
+        *,
+        wait_seconds: float = 8.0,
+    ) -> None:
+        self._make = make_provider
+        self._provider: TokenProvider | None = None
+        self._wait = wait_seconds
+        self._lock = threading.Lock()
+        self._job: _Job | None = None
+
+    def _on_prompt(self, message: str) -> None:
+        print(message, file=sys.stderr, flush=True)
+        job = self._job
+        if job is not None:
+            job.message = message
+            job.ready.set()
+
+    def _run(self, job: _Job) -> None:
+        try:
+            # Built here, not in __init__: msal fetches the authority's metadata when constructed.
+            if self._provider is None:
+                self._provider = self._make(self._on_prompt)
+            job.token = self._provider()
+        except BaseException as error:  # reported to the caller, never lost on the thread
+            job.error = error
+        finally:
+            job.done.set()
+            job.ready.set()
+
+    def silent(self) -> str | None:
+        """A token from the warm cache, or None; never starts a sign-in."""
+        with self._lock:
+            if self._provider is None:
+                self._provider = self._make(self._on_prompt)
+            peek = getattr(self._provider, "silent_token", None)
+        return peek() if peek else None
+
+    def __call__(self) -> str:
+        with self._lock:
+            if self._job is None:
+                self._job = _Job()
+                threading.Thread(target=self._run, args=(self._job,), daemon=True).start()
+            job = self._job
+        job.ready.wait(self._wait)
+        if job.done.is_set():
+            with self._lock:
+                if self._job is job:
+                    self._job = None
+            if job.error is not None:
+                raise job.error
+            assert job.token is not None
+            return job.token
+        raise SignInRequired(
+            f"Sign in to Docket first. {job.message or 'Starting sign-in; try again in a moment.'} "
+            "Then run this tool again."
+        )
+
+
+def non_interactive_token(provider: TokenProvider) -> str | None:
+    """A token without any user interaction, or None (a missing token, a failed or cold sign-in)."""
+    try:
+        if isinstance(provider, BackgroundSignIn):
+            return provider.silent()
+        return provider()
+    except Exception:  # AuthenticationError and msal/network failures: just no credential
+        return None
+
+
+def build_provider(settings: Settings) -> TokenProvider | None:
+    """The provider for the configured credentials, or None when none are configured."""
+    if os.environ.get("DOCKET_API_TOKEN", "").strip():
+        return api_token_provider()
+    if settings.client_id and settings.scope and (settings.tenant_id or settings.authority):
+        if settings.client_secret:
+            client_id, secret, scope = settings.client_id, settings.client_secret, settings.scope
+            app: list[TokenProvider] = []
+
+            def client_credentials() -> str:
+                if not app:  # msal fetches the authority's metadata when constructed: do it lazily
+                    app.append(
+                        ClientCredentialsTokenProvider(
+                            client_id,
+                            secret,
+                            scope,
+                            tenant_id=settings.tenant_id,
+                            authority=settings.authority,
+                        )
+                    )
+                return app[0]()
+
+            return client_credentials
+        client_id, scope = settings.client_id, settings.scope
+
+        def make(prompt: Callable[[str], None]) -> TokenProvider:
+            if settings.cache_path:
+                settings.cache_path.parent.mkdir(parents=True, exist_ok=True)
+            return DeviceCodeTokenProvider(
+                client_id,
+                scope,
+                tenant_id=settings.tenant_id,
+                authority=settings.authority,
+                cache_path=settings.cache_path,
+                prompt=prompt,
+            )
+
+        return BackgroundSignIn(make)
+    return None

docket_mcp/slots.py

@@ -0,0 +1,80 @@
+"""Free-slot computation over a rig's schedule."""
+
+from __future__ import annotations
+
+from datetime import UTC, date, datetime, time, timedelta
+from typing import Any
+from zoneinfo import ZoneInfo
+
+from .times import local_at, local_to_midnight, parse_instant
+
+__all__ = ["busy_intervals", "free_slots"]
+
+Interval = tuple[datetime, datetime]
+
+
+def busy_intervals(sessions: list[dict[str, Any]], zone: ZoneInfo) -> list[Interval]:
+    """Intervals the sessions occupy; cancelled and archived sessions do not block.
+
+    A session with no end is open-ended: it is assumed to run to the end of its local start day.
+    """
+    out: list[Interval] = []
+    for session in sessions:
+        if session.get("archived_at") or session.get("planning_status") == "cancelled":
+            continue
+        start = parse_instant(session["scheduled_start"])
+        if session.get("scheduled_end"):
+            end = parse_instant(session["scheduled_end"])
+        else:
+            end = local_to_midnight(start.astimezone(zone).date() + timedelta(days=1), zone)
+        if end > start:
+            out.append((start, end))
+    return sorted(out)
+
+
+def _merge(intervals: list[Interval]) -> list[Interval]:
+    merged: list[Interval] = []
+    for start, end in sorted(intervals):
+        if merged and start <= merged[-1][1]:
+            merged[-1] = (merged[-1][0], max(merged[-1][1], end))
+        else:
+            merged.append((start, end))
+    return merged
+
+
+def free_slots(
+    busy: list[Interval],
+    start_date: date,
+    end_date: date,
+    duration_minutes: int,
+    earliest: time,
+    latest: time,
+    zone: ZoneInfo,
+) -> list[tuple[datetime, datetime]]:
+    """Gaps of at least ``duration_minutes`` inside [earliest, latest] on each local day.
+
+    Adjacent sessions leave no gap; a gap exactly as long as the duration counts. Sessions
+    crossing a day bound are clipped to it. Returns UTC instants.
+    """
+    if latest <= earliest:
+        raise ValueError("latest must be after earliest.")
+    need = timedelta(minutes=duration_minutes)
+    merged = _merge(busy)
+    slots: list[tuple[datetime, datetime]] = []
+    day = start_date
+    while day <= end_date:
+        window_start = local_at(day, earliest, zone)
+        window_end = local_at(day, latest, zone)
+        cursor = window_start
+        for b_start, b_end in merged:
+            if b_end <= cursor:
+                continue
+            if b_start >= window_end:
+                break
+            if b_start - cursor >= need:
+                slots.append((cursor, b_start))
+            cursor = max(cursor, b_end)
+        if window_end - cursor >= need:
+            slots.append((cursor, window_end))
+        day += timedelta(days=1)
+    return [(s.astimezone(UTC), e.astimezone(UTC)) for s, e in slots]

docket_mcp/times.py

@@ -0,0 +1,160 @@
+"""Wall-clock times <-> UTC instants.
+
+Tools take local wall-clock times plus an IANA zone and return both the local time and UTC.
+Offsets are never added by hand: every conversion goes through ``zoneinfo``, so a DST day keeps
+its 23 or 25 hours. Durations are elapsed minutes, added to the UTC instant, as the server does.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, date, datetime, time, timedelta
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+__all__ = [
+    "ParsedLocal",
+    "TimeError",
+    "day_bounds",
+    "describe",
+    "format_utc",
+    "get_zone",
+    "local_at",
+    "local_to_midnight",
+    "local_to_utc",
+    "parse_date",
+    "parse_instant",
+    "parse_local_datetime",
+    "parse_time",
+    "system_zone_name",
+]
+
+_OFFSET = re.compile(r"(Z|[+-]\d{2}:?\d{2})$", re.IGNORECASE)
+
+
+class TimeError(ValueError):
+    """A time, date or zone the caller gave that cannot be used; the message is shown to the model."""
+
+
+def system_zone_name() -> str:
+    """The machine's IANA zone (``tzlocal`` also resolves Windows zones), falling back to UTC."""
+    try:
+        import tzlocal
+
+        name = tzlocal.get_localzone_name()
+        if name:
+            ZoneInfo(name)
+            return name
+    except Exception:  # any failure to detect means "unknown": use UTC
+        pass
+    return "UTC"
+
+
+def get_zone(name: str) -> ZoneInfo:
+    try:
+        return ZoneInfo(name)
+    except (ZoneInfoNotFoundError, ValueError, OSError):
+        raise TimeError(
+            f"Unknown time zone {name!r}: use an IANA name such as 'America/Los_Angeles'."
+        ) from None
+
+
+def parse_date(value: str, field: str = "date") -> date:
+    try:
+        return date.fromisoformat(value.strip())
+    except ValueError:
+        raise TimeError(f"{field} must be a date like 2026-03-08, got {value!r}.") from None
+
+
+def parse_time(value: str, field: str = "time") -> time:
+    try:
+        parsed = time.fromisoformat(value.strip())
+    except ValueError:
+        raise TimeError(f"{field} must be a 24-hour time like 09:30, got {value!r}.") from None
+    if parsed.tzinfo is not None:
+        raise TimeError(f"{field} is a local wall-clock time: no offset; use time_zone instead.")
+    return parsed.replace(microsecond=0)
+
+
+class ParsedLocal:
+    """A local wall-clock time resolved to an instant."""
+
+    def __init__(self, utc: datetime, ambiguous: bool) -> None:
+        self.utc = utc
+        self.ambiguous = ambiguous
+
+
+def local_to_utc(local: datetime, zone: ZoneInfo) -> ParsedLocal:
+    """Resolve naive ``local`` in ``zone``.
+
+    A time inside a spring-forward gap does not exist and is rejected. A time repeated by a
+    fall-back picks the first occurrence and is flagged ``ambiguous`` so the caller can say so.
+    """
+    if local.tzinfo is not None:
+        raise TimeError(
+            "Give a local wall-clock time without an offset; use time_zone for the zone."
+        )
+    first = local.replace(tzinfo=zone, fold=0)
+    second = local.replace(tzinfo=zone, fold=1)
+    utc = first.astimezone(UTC)
+    if utc.astimezone(zone).replace(tzinfo=None) != local:
+        raise TimeError(
+            f"{local:%Y-%m-%d %H:%M} does not exist in {zone.key} (clocks skip forward "
+            "that day); pick a time after the change."
+        )
+    return ParsedLocal(utc, first.utcoffset() != second.utcoffset())
+
+
+def parse_local_datetime(value: str, zone: ZoneInfo, field: str = "start") -> ParsedLocal:
+    """Parse ``2026-03-08T09:30`` (or with a space) as local time in ``zone``."""
+    text = value.strip().replace(" ", "T")
+    if "T" in text and _OFFSET.search(text.split("T", 1)[1]):
+        raise TimeError(
+            f"{field} is a local wall-clock time like 2026-03-08T09:30: no offset or 'Z'. "
+            "Pass time_zone if it is not the default zone."
+        )
+    try:
+        local = datetime.fromisoformat(text)
+    except ValueError:
+        raise TimeError(f"{field} must look like 2026-03-08T09:30, got {value!r}.") from None
+    return local_to_utc(local.replace(microsecond=0), zone)
+
+
+def parse_instant(value: str) -> datetime:
+    """An API instant (``...Z`` or with an offset) as an aware UTC datetime."""
+    parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=UTC)
+    return parsed.astimezone(UTC)
+
+
+def format_utc(instant: datetime) -> str:
+    return instant.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def describe(instant: str | datetime | None, zone: ZoneInfo) -> dict[str, str] | None:
+    """``{"local": "2026-03-08T09:30:00-07:00", "utc": "2026-03-08T16:30:00Z"}``."""
+    if instant is None:
+        return None
+    moment = parse_instant(instant) if isinstance(instant, str) else instant
+    return {
+        "local": moment.astimezone(zone).isoformat(timespec="seconds"),
+        "utc": format_utc(moment),
+    }
+
+
+def local_to_midnight(day: date, zone: ZoneInfo) -> datetime:
+    """UTC instant of the start of local ``day`` (zoneinfo resolves a midnight lost to DST)."""
+    return datetime.combine(day, time(0), tzinfo=zone).astimezone(UTC)
+
+
+def day_bounds(start: date, end: date, zone: ZoneInfo) -> tuple[datetime, datetime]:
+    """UTC instants of local midnight on ``start`` and of local midnight after ``end``."""
+    if end < start:
+        raise TimeError("end_date is before start_date.")
+    return local_to_midnight(start, zone), local_to_midnight(end + timedelta(days=1), zone)
+
+
+def local_at(day: date, at: time, zone: ZoneInfo) -> datetime:
+    """UTC instant of ``at`` on local ``day``; a time in a DST gap resolves to the instant after it."""
+    # In a gap fold=0 applies the old offset, which lands after the gap: 02:30 becomes 03:30.
+    return datetime.combine(day, at).replace(tzinfo=zone, fold=0).astimezone(UTC)