trueppm-mcp 0.4.0__py3-none-any.whl

trueppm_mcp/__init__.py

@@ -0,0 +1,41 @@
+"""trueppm-mcp — read-only Model Context Protocol server for self-hosted TruePPM.
+
+A thin protocol adapter that talks to TruePPM only over HTTP (ADR-0186): it never
+imports Django, never touches the ORM or database, and never imports from the
+proprietary enterprise repo. RBAC is enforced once, at the API layer.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+from trueppm_mcp.client import (
+    ApiError,
+    AuthError,
+    NonAgentTokenError,
+    RateLimitError,
+    TruePPMClient,
+)
+from trueppm_mcp.config import ConfigError, Settings
+from trueppm_mcp.server import build_server
+
+try:
+    # Single source of truth: the version is whatever pip installed (set from
+    # pyproject.toml at build time), matching trueppm_scheduler's pattern —
+    # so this can't freeze at a stale literal the way trueppm_api's did.
+    __version__ = _pkg_version("trueppm-mcp")
+except PackageNotFoundError:  # running from an un-installed source tree
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "ApiError",
+    "AuthError",
+    "ConfigError",
+    "NonAgentTokenError",
+    "RateLimitError",
+    "Settings",
+    "TruePPMClient",
+    "__version__",
+    "build_server",
+]

trueppm_mcp/__main__.py

@@ -0,0 +1,8 @@
+"""Enable ``python -m trueppm_mcp``."""
+
+from __future__ import annotations
+
+from trueppm_mcp.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

trueppm_mcp/cli.py

@@ -0,0 +1,107 @@
+"""Command-line entry point for the TruePPM MCP server.
+
+``trueppm-mcp`` (or ``python -m trueppm_mcp``) boots the server. stdio is the
+primary transport — an AI client spawns this process and speaks MCP over the
+pipe. ``--transport http`` (or ``sse``) runs a network transport for web-based
+assistants.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from typing import Literal
+
+from trueppm_mcp.client import TruePPMClient
+from trueppm_mcp.config import ConfigError, Settings
+from trueppm_mcp.server import (
+    ENV_ALLOWED_HOSTS,
+    build_server,
+    normalize_allowed_host,
+    parse_allowed_hosts,
+)
+
+#: Map our CLI transport names onto FastMCP's literal transport identifiers.
+_TRANSPORTS: dict[str, Literal["stdio", "sse", "streamable-http"]] = {
+    "stdio": "stdio",
+    "sse": "sse",
+    "http": "streamable-http",
+}
+
+
+def _allowed_host_arg(value: str) -> str:
+    try:
+        return normalize_allowed_host(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(str(exc)) from exc
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="trueppm-mcp",
+        description="Read-only MCP server for self-hosted TruePPM.",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=sorted(_TRANSPORTS),
+        default="stdio",
+        help="MCP transport to serve (default: stdio).",
+    )
+    parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="Bind host for the http/sse transports (default: 127.0.0.1).",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8000,
+        help="Bind port for the http/sse transports (default: 8000).",
+    )
+    parser.add_argument(
+        "--allowed-host",
+        action="append",
+        type=_allowed_host_arg,
+        default=[],
+        metavar="HOST",
+        help=(
+            "Extra Host name to accept on the http/sse transports, e.g. a "
+            "reverse-proxy hostname (repeatable). Also read, comma-separated, from "
+            f"{ENV_ALLOWED_HOSTS}. Loopback names are always accepted."
+        ),
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Parse arguments, build the server, and run the chosen transport.
+
+    Returns a process exit code: ``0`` on a clean shutdown, ``2`` on a
+    configuration error (so a misconfigured client gets an actionable message on
+    stderr rather than a traceback). Authentication is verified by the server
+    lifespan at startup.
+    """
+    args = _build_parser().parse_args(argv)
+
+    try:
+        settings = Settings.from_env()
+    except ConfigError as exc:
+        print(f"Configuration error: {exc}", file=sys.stderr)
+        return 2
+
+    try:
+        env_hosts = parse_allowed_hosts(os.environ.get(ENV_ALLOWED_HOSTS))
+    except ValueError as exc:
+        print(f"Configuration error: {ENV_ALLOWED_HOSTS}: {exc}", file=sys.stderr)
+        return 2
+    # dict.fromkeys: de-duplicate while keeping env-then-flag order.
+    allowed_hosts = list(dict.fromkeys([*env_hosts, *args.allowed_host]))
+    client = TruePPMClient(settings)
+    server = build_server(client, host=args.host, port=args.port, allowed_hosts=allowed_hosts)
+    server.run(transport=_TRANSPORTS[args.transport])
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

trueppm_mcp/client.py

@@ -0,0 +1,486 @@
+"""Async HTTP client for the TruePPM REST API.
+
+The MCP server is *only* an HTTP client of the public REST API (ADR-0186 §C/§I):
+it never imports Django, never touches the ORM or the database, and never imports
+from the proprietary enterprise repo. Authorization — RBAC role gates,
+member-scoped querysets, the 404-vs-403 existence oracle — is enforced once, at
+the API layer, identically for this client and the web client. This module holds
+no privileged path and is not the security boundary.
+
+The bearer token is set as a request header and is never logged.
+"""
+
+from __future__ import annotations
+
+import email.utils
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from trueppm_mcp.config import Settings
+
+#: Connection-verification endpoint (relative to ``/api/v1/``). Returns the
+#: identity of the token's owner; a 401 means the token does not authenticate.
+AUTH_VERIFY_PATH = "auth/me/"
+
+#: Per-request timeout (seconds). Read tools are simple GETs; a slow API should
+#: surface as a clear error rather than hang the AI client indefinitely.
+DEFAULT_TIMEOUT = 30.0
+
+#: Cap on the number of rows a paginated read tool accumulates before it stops
+#: following ``next`` and reports the result as truncated. The API paginates at
+#: ``PAGE_SIZE`` (50) rows/page, so this follows up to ~20 pages. It bounds the
+#: LLM context a single ``list_*`` tool can spend: a well-behaved list returns in
+#: full, and a pathologically large one is capped with an explicit ``truncated``
+#: signal rather than silently cut at the first page (#1731).
+DEFAULT_MAX_ROWS = 1000
+
+
+@dataclass(frozen=True)
+class Refusal:
+    """Why the API refused a call, as the API itself described it (#2689).
+
+    The API records a two-axis refusal taxonomy on every refused agent call and,
+    since ADR-0809, returns it in the 401/403 body. Before that, an operator saw a
+    bare HTTP status here and had to make a second, separate call to
+    ``GET /agent-actions/?constraint=…`` to learn the reason — for the persona this
+    server exists to serve, a system that fails without saying why is the worst
+    outcome.
+
+    Attributes:
+        verdict: Always ``"refused"`` today; carried so a caller can branch on one
+            field across the whole taxonomy rather than inferring it.
+        reason: The coarse axis — ``"identity"`` (the credential was rejected) or
+            ``"policy"`` (the credential is fine, a guard denied the call).
+        constraint: The finer axis — which specific guard fired, e.g.
+            ``"token_identity"`` or ``"capability_scope"``. Empty when the API
+            withheld it: the constraint vocabulary includes schedule-shaped codes
+            that could name a resource the caller may not read, so the API
+            discloses only from an allow-list. Absence is not an error.
+    """
+
+    verdict: str
+    reason: str
+    constraint: str = ""
+
+    def describe(self) -> str:
+        """One line an operator can act on, e.g. ``"policy refusal (capability_scope)"``."""
+
+        if self.constraint:
+            return f"{self.reason} refusal ({self.constraint})"
+        return f"{self.reason} refusal"
+
+
+class TruePPMError(RuntimeError):
+    """Base for API-call failures, carrying the structured refusal when present."""
+
+    def __init__(self, message: str, refusal: Refusal | None = None) -> None:
+        super().__init__(message)
+        #: The parsed refusal taxonomy, or ``None`` when the API sent none — an
+        #: older server, or a failure that is not a governed refusal (a 404, a
+        #: 5xx). Callers must treat ``None`` as "no reason given", never as an
+        #: error in itself.
+        self.refusal = refusal
+
+
+class ApiError(TruePPMError):
+    """Raised when the API returns an unexpected (non-401) error status."""
+
+
+class AuthError(TruePPMError):
+    """Raised when the API rejects the configured bearer token (HTTP 401)."""
+
+
+class NonAgentTokenError(TruePPMError):
+    """Raised when the configured token authenticates (HTTP 200) but is not an
+    agent credential (#2938).
+
+    Distinct from :class:`AuthError`: the API did not reject the token — a
+    ``legacy:full`` personal access token authenticates fine and always will,
+    because restraining it would restrain the person who owns it (#2877). What
+    this error catches is the *honest mistake*: someone pasted their own PAT into
+    ``TRUEPPM_API_TOKEN`` instead of minting an ``mcp:read`` token. Left
+    unchecked, the server boots successfully on a credential the operator's
+    instance kill switch and the team's agent opt-out do not govern — a silent
+    bypass by configuration, not by attack. Raised by
+    :meth:`TruePPMClient.verify_auth`, before the server lifespan yields, so it
+    aborts the boot the same way a bad token does rather than letting every tool
+    call succeed unprotected.
+    """
+
+
+class RateLimitError(ApiError):
+    """Raised when the API rate-limits the call (HTTP 429) — #2924.
+
+    A subclass of :class:`ApiError` so existing ``except ApiError`` handlers keep
+    working, but distinguishable for anything that wants to wait and retry.
+
+    This matters because it is not a rare edge: ``MCP_TOKEN_COMPUTE_RATE`` is
+    **12/min** and covers ``whatif``, ``monte-carlo/latest``, ``forecast`` and
+    ``sprint-forecast`` — exactly the tools an agent exercises in a burst while
+    exploring a schedule. Folding that into a generic "Unexpected response …
+    HTTP 429." told the model a sentence it could not act on: it had no way to
+    know the call would succeed shortly, so it reported a nonspecific failure.
+
+    Attributes:
+        retry_after: Seconds to wait, parsed from the ``Retry-After`` header, or
+            ``None`` when the header was absent or unparseable. ``None`` means
+            "no hint given" — never treat it as "do not retry".
+    """
+
+    def __init__(
+        self,
+        message: str,
+        refusal: Refusal | None = None,
+        retry_after: float | None = None,
+    ) -> None:
+        super().__init__(message, refusal)
+        self.retry_after = retry_after
+
+
+def _http_date_delta(raw: str, date_header: str | None) -> float | None:
+    """Seconds between an HTTP-date ``Retry-After`` and "now", or ``None`` if unusable.
+
+    "Now" is the response's own ``Date`` header when it sent a usable one, so client
+    clock skew cannot turn into a wildly wrong wait; local time is the fallback.
+
+    Total by design, and that is the contract callers depend on: every failure path
+    returns ``None`` and nothing escapes. ``parsedate_to_datetime`` *raises* on an
+    unparseable value rather than returning ``None``, so a junk header would
+    otherwise crash the 429 path that is already handling a failure.
+    """
+
+    try:
+        parsed = email.utils.parsedate_to_datetime(raw)
+    except (TypeError, ValueError):
+        return None
+    if parsed is None:  # pragma: no cover — defensive across versions
+        return None
+    now = None
+    if date_header:
+        # Same trap as above — a malformed Date header raises rather than
+        # returning None, and it must not crash the 429 path either.
+        try:
+            now = email.utils.parsedate_to_datetime(date_header)
+        except (TypeError, ValueError):
+            now = None
+    if now is None:
+        now = datetime.now(UTC)
+    try:
+        return (parsed - now).total_seconds()
+    except (TypeError, ValueError):
+        return None
+
+
+def parse_retry_after(response: httpx.Response) -> float | None:
+    """Seconds to wait from a ``Retry-After`` header, or ``None`` if unusable.
+
+    RFC 9110 allows two forms and DRF sends the first, but a reverse proxy or CDN
+    in front of the instance may rewrite it to the second, so both are handled:
+
+    * delta-seconds — a non-negative integer (``Retry-After: 30``)
+    * an HTTP-date — absolute (``Retry-After: Wed, 21 Oct 2026 07:28:00 GMT``),
+      converted to a delta against the response's own ``Date`` header when it has
+      one, and against local time otherwise. Using the server's ``Date`` avoids
+      turning client clock skew into a wildly wrong wait.
+
+    Total by design: anything unparseable, negative, or absurd yields ``None``.
+    A malformed header must degrade to "no hint", never crash the call that is
+    already failing.
+    """
+
+    raw = response.headers.get("Retry-After")
+    if not raw:
+        return None
+    raw = raw.strip()
+    try:
+        seconds = float(int(raw))
+    except ValueError:
+        delta = _http_date_delta(raw, response.headers.get("Date"))
+        if delta is None:
+            return None
+        seconds = delta
+    if seconds < 0:
+        return None
+    return seconds
+
+
+def parse_refusal(response: httpx.Response) -> Refusal | None:
+    """Extract the refusal envelope from an error response, if it carries one.
+
+    Total by design: a body that is not JSON, not an object, or carries no
+    ``refusal`` key yields ``None``. A refusal that cannot be parsed must never
+    turn a clean 403 into a client-side crash — the HTTP status is still the
+    answer, and the envelope is additional explanation.
+    """
+
+    try:
+        body = response.json()
+    except ValueError:
+        return None
+    if not isinstance(body, dict):
+        return None
+    envelope = body.get("refusal")
+    if not isinstance(envelope, dict):
+        return None
+    reason = envelope.get("reason")
+    if not isinstance(reason, str) or not reason:
+        return None
+    verdict = envelope.get("verdict")
+    constraint = envelope.get("constraint")
+    return Refusal(
+        verdict=verdict if isinstance(verdict, str) else "refused",
+        reason=reason,
+        constraint=constraint if isinstance(constraint, str) else "",
+    )
+
+
+def _rate_limit_message(path: str, retry_after: float | None) -> str:
+    """The one sentence the model acts on: that it is rate-limited, and for how long.
+
+    The wait is stated explicitly rather than left for the model to infer, because
+    "HTTP 429" alone reads as a failure and the correct response — wait a moment
+    and repeat the same call — is not derivable from it.
+    """
+
+    if retry_after is None:
+        return (
+            f"Rate limited by the TruePPM API on {path} (HTTP 429). No Retry-After "
+            "header was sent; wait a few seconds and retry the same call."
+        )
+    return (
+        f"Rate limited by the TruePPM API on {path} (HTTP 429). Retry the same call "
+        f"in {retry_after:.0f} second(s)."
+    )
+
+
+def _refusal_suffix(refusal: Refusal | None) -> str:
+    """`" — policy refusal (capability_scope)"`, or empty when nothing was sent."""
+
+    return f" — {refusal.describe()}" if refusal is not None else ""
+
+
+class TruePPMClient:
+    """Thin async wrapper over ``httpx.AsyncClient`` carrying the bearer token.
+
+    Args:
+        settings: Resolved :class:`~trueppm_mcp.config.Settings`.
+        transport: Optional ``httpx`` transport. Injected in tests
+            (``httpx.MockTransport``); ``None`` uses the real network transport.
+        timeout: Per-request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        settings: Settings,
+        *,
+        transport: httpx.AsyncBaseTransport | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        # A trailing slash on the base URL makes httpx's RFC-3986 relative join
+        # append the path segment instead of replacing the last one, so
+        # "auth/me/" resolves to ".../api/v1/auth/me/".
+        self._client = httpx.AsyncClient(
+            base_url=f"{settings.api_base_url}/",
+            headers={
+                "Authorization": f"Bearer {settings.token}",
+                "Accept": "application/json",
+            },
+            timeout=timeout,
+            transport=transport,
+        )
+
+    async def verify_auth(self) -> dict[str, Any]:
+        """Confirm the token authenticates by calling ``GET /auth/me/``.
+
+        Returns:
+            The identity payload (the token owner's user record) on HTTP 200.
+
+        Raises:
+            AuthError: On HTTP 401 — the token is missing, malformed, or revoked.
+            ApiError: On any other non-success status.
+            NonAgentTokenError: The token authenticates but is not an agent
+                credential (#2938) — see that class's docstring.
+        """
+        response = await self._client.get(AUTH_VERIFY_PATH)
+        if response.status_code == httpx.codes.UNAUTHORIZED:
+            # No token material in the message — only the fact of rejection, plus
+            # whatever reason the API chose to disclose.
+            refusal = parse_refusal(response)
+            raise AuthError(
+                "The TruePPM API rejected the configured token (HTTP 401)"
+                f"{_refusal_suffix(refusal)}.",
+                refusal,
+            )
+        if response.status_code == httpx.codes.TOO_MANY_REQUESTS:
+            retry_after = parse_retry_after(response)
+            raise RateLimitError(
+                _rate_limit_message(AUTH_VERIFY_PATH, retry_after),
+                parse_refusal(response),
+                retry_after,
+            )
+        if response.is_error:
+            refusal = parse_refusal(response)
+            raise ApiError(
+                f"Unexpected response from {AUTH_VERIFY_PATH}: "
+                f"HTTP {response.status_code}{_refusal_suffix(refusal)}.",
+                refusal,
+            )
+        result: dict[str, Any] = response.json()
+        posture = result.get("token")
+        is_agent = isinstance(posture, dict) and bool(posture.get("is_agent"))
+        if not is_agent:
+            scopes = posture.get("scopes") if isinstance(posture, dict) else None
+            raise NonAgentTokenError(
+                "This token is a full-access personal credential"
+                f"{f' (scopes: {scopes})' if scopes else ''}, not an agent "
+                "credential — the instance kill switch and your team's agent "
+                "opt-out will not apply to it. Mint an mcp:read token instead: "
+                "Personal Access Tokens → Create token → 'Read-only for AI assistants'."
+            )
+        return result
+
+    async def get(self, path: str, params: Mapping[str, Any] | None = None) -> Any:
+        """Issue an authenticated ``GET`` and return the decoded JSON body.
+
+        Every read tool routes through here (ADR-0186 §D/§I): the request is a
+        plain ``GET`` against ``/api/v1/<path>`` carrying the bearer token, so
+        authorization is enforced once, at the API layer, exactly as for the web
+        client. This method holds no privileged path.
+
+        Args:
+            path: Path relative to the ``/api/v1/`` base (e.g. ``"projects/"`` or
+                ``"projects/{id}/forecast/"``). No leading slash.
+            params: Optional query parameters. Callers omit ``None`` values; a
+                filter left unset is simply not sent.
+
+        Returns:
+            The decoded JSON body — a ``dict`` for object endpoints, a ``list``
+            or paginated ``dict`` for collection endpoints.
+
+        Raises:
+            AuthError: On HTTP 401 — the token is missing, malformed, or revoked.
+                The message never contains token material.
+            ApiError: On any other error status (404 for a resource the caller
+                cannot read, 5xx, etc.).
+        """
+        response = await self._client.get(path, params=dict(params) if params else None)
+        if response.status_code == httpx.codes.UNAUTHORIZED:
+            # No token material in the message — only the fact of rejection, plus
+            # whatever reason the API chose to disclose.
+            refusal = parse_refusal(response)
+            raise AuthError(
+                "The TruePPM API rejected the configured token (HTTP 401)"
+                f"{_refusal_suffix(refusal)}.",
+                refusal,
+            )
+        if response.status_code == httpx.codes.TOO_MANY_REQUESTS:
+            # Not folded into the generic branch below: the compute bucket is
+            # 12/min, so this is the routine outcome of an exploratory burst and
+            # the model needs a wait hint rather than an opaque status (#2924).
+            retry_after = parse_retry_after(response)
+            raise RateLimitError(
+                _rate_limit_message(path, retry_after),
+                parse_refusal(response),
+                retry_after,
+            )
+        if response.is_error:
+            refusal = parse_refusal(response)
+            raise ApiError(
+                f"Unexpected response from {path}: "
+                f"HTTP {response.status_code}{_refusal_suffix(refusal)}.",
+                refusal,
+            )
+        return response.json()
+
+    async def get_paginated(
+        self,
+        path: str,
+        params: Mapping[str, Any] | None = None,
+        *,
+        max_rows: int = DEFAULT_MAX_ROWS,
+    ) -> tuple[list[Any], int, bool]:
+        """Follow DRF pagination, accumulating rows up to ``max_rows`` (#1731).
+
+        The list tools must not silently reason over only the first page: a DRF
+        collection returns ``{count, next, previous, results}`` at ``PAGE_SIZE``
+        (50) rows/page, so a bare ``results`` read truncates at 50 with no signal.
+        This method follows the absolute ``next`` links until it has ``max_rows``
+        rows or runs out of pages, and reports whether more rows exist server-side
+        so the caller can tell the model the set is partial.
+
+        Args:
+            path: Path relative to the ``/api/v1/`` base (e.g. ``"tasks/"``).
+            params: Query parameters for the first page. ``next`` carries its own
+                params, so following pages send none of their own.
+            max_rows: Stop accumulating once this many rows are collected.
+
+        Returns:
+            ``(rows, total_count, truncated)``:
+              * ``rows`` — the accumulated result rows, capped at ``max_rows``.
+              * ``total_count`` — the server's reported ``count`` (the true total),
+                or ``len(rows)`` for an unpaginated (bare-list) body.
+              * ``truncated`` — ``True`` when fewer rows were returned than exist
+                server-side (``next`` remained, or the cap was hit).
+
+        Raises:
+            AuthError: On HTTP 401 (see :meth:`get`).
+            ApiError: On any other error status (see :meth:`get`).
+        """
+        payload = await self.get(path, params=params)
+        # An endpoint that returns a bare JSON list is unpaginated; the whole body
+        # is the row set (still cap it defensively).
+        if isinstance(payload, list):
+            return payload[:max_rows], len(payload), len(payload) > max_rows
+        if not isinstance(payload, Mapping) or "results" not in payload:
+            return [], 0, False
+
+        rows: list[Any] = []
+        results = payload.get("results")
+        if isinstance(results, list):
+            rows.extend(results)
+        total_count = payload.get("count")
+        next_url = payload.get("next")
+        # ``next`` is an absolute URL carrying its own page/query params, so it is
+        # passed to get() as the full path with no additional params.
+        while isinstance(next_url, str) and next_url and len(rows) < max_rows:
+            page = await self.get(next_url)
+            if not isinstance(page, Mapping):
+                break
+            page_results = page.get("results")
+            if not isinstance(page_results, list) or not page_results:
+                # A well-behaved DRF page never advertises ``next`` past the last
+                # populated page. Stop on the first empty/malformed page so a
+                # misbehaving server that keeps returning a non-null ``next`` with
+                # no rows can't spin this loop — it stays provably bounded.
+                break
+            rows.extend(page_results)
+            next_url = page.get("next")
+
+        truncated = (isinstance(next_url, str) and bool(next_url)) or len(rows) > max_rows
+        rows = rows[:max_rows]
+        if not isinstance(total_count, int):
+            total_count = len(rows)
+        # A count larger than what we returned is truncation even if we exhausted
+        # ``next`` (defensive against an inconsistent count/next).
+        truncated = truncated or total_count > len(rows)
+        return rows, total_count, truncated
+
+    async def aclose(self) -> None:
+        """Close the underlying connection pool."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> TruePPMClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()