openproject-mcp-server 0.1.0__py3-none-any.whl

openproject_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""OpenProject MCP server."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

openproject_mcp/__main__.py

@@ -0,0 +1,127 @@
+"""Console entry point: ``openproject-mcp-server`` / ``openproject-mcp`` (SPEC §3.3, §14).
+
+Selects the transport, checks configuration, and starts the server. A missing
+or broken configuration produces a short actionable message on stderr and a
+non-zero exit code — never a traceback.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os.path
+import sys
+from collections.abc import Sequence
+
+from pydantic import ValidationError
+
+from openproject_mcp import __version__
+from openproject_mcp.config import Settings, check_runtime_config
+
+__all__ = ["main"]
+
+EXIT_OK = 0
+EXIT_CONFIG_ERROR = 2
+EXIT_INTERRUPTED = 130
+
+
+def _prog() -> str:
+    """The name this process was invoked as, when it is one of our scripts.
+
+    Both console scripts run this ``main``; ``--version`` and usage text
+    should echo whichever the user typed. Anything else (``python -m ...``,
+    test harnesses) reports the canonical distribution name.
+    """
+    invoked = os.path.basename(sys.argv[0]) if sys.argv and sys.argv[0] else ""
+    if invoked in ("openproject-mcp", "openproject-mcp-server"):
+        return invoked
+    return "openproject-mcp-server"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog=_prog(),
+        description=(
+            "MCP server for OpenProject. Configuration comes from the environment: "
+            "OPENPROJECT_URL and OPENPROJECT_API_KEY are required."
+        ),
+    )
+    parser.add_argument(
+        "--transport",
+        choices=("stdio", "http"),
+        default="stdio",
+        help="Transport to serve on (default: stdio).",
+    )
+    parser.add_argument(
+        "--host",
+        default=None,
+        help="Bind address for --transport http (default: 127.0.0.1).",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=None,
+        help="Port for --transport http (default: 8000).",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Validate configuration and exit without starting the server.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return parser
+
+
+def _fail(message: str, problems: Sequence[str] = ()) -> int:
+    print(f"openproject-mcp: {message}", file=sys.stderr)
+    for problem in problems:
+        print(f"  - {problem}", file=sys.stderr)
+    print(
+        "  See https://github.com/kar-thik/openproject-mcp#configuration "
+        "for the full variable list.",
+        file=sys.stderr,
+    )
+    return EXIT_CONFIG_ERROR
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """CLI entry point. Returns a process exit code; raises nothing."""
+    args = build_parser().parse_args(argv)
+
+    try:
+        settings = Settings()
+    except ValidationError as exc:
+        problems = [
+            f"{'.'.join(str(part) for part in error['loc']) or 'config'}: {error['msg']}"
+            for error in exc.errors()
+        ]
+        return _fail("invalid configuration", problems)
+
+    problems = check_runtime_config(settings, args.transport)
+    if problems:
+        return _fail("cannot start, configuration is incomplete", problems)
+
+    if args.check:
+        print(f"openproject-mcp: configuration OK ({settings.url})", file=sys.stderr)
+        return EXIT_OK
+
+    # Imported here so `--help` and `--check` stay fast and dependency-light.
+    from openproject_mcp.server import build_server
+
+    server = build_server(settings)
+    try:
+        if args.transport == "http":
+            server.run(
+                transport="http",
+                host=args.host or settings.http_host,
+                port=args.port or settings.http_port,
+                show_banner=False,
+            )
+        else:
+            server.run(transport="stdio", show_banner=False)
+    except KeyboardInterrupt:
+        return EXIT_INTERRUPTED
+    return EXIT_OK
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

openproject_mcp/auth.py

@@ -0,0 +1,54 @@
+"""Bearer-token verification for the HTTP transport (SPEC §11).
+
+``OPENPROJECT_MCP_AUTH_TOKENS`` holds a static, comma-separated set of bearer
+tokens. When it is configured, :class:`StaticBearerVerifier` is attached to the
+server as its auth provider; FastMCP's HTTP app then rejects every request to
+the MCP endpoint that does not carry ``Authorization: Bearer <token>`` with a
+configured token (401 + ``WWW-Authenticate``). Only the HTTP app consults the
+auth provider — the stdio transport and the in-memory client are untouched.
+
+Token comparison is constant-time (:func:`secrets.compare_digest`) and checks
+every configured token so timing reveals nothing about which, if any, matched.
+Token material is never logged, and an empty token set rejects all requests
+rather than leaving the endpoint open.
+"""
+
+from __future__ import annotations
+
+import secrets
+from collections.abc import Sequence
+
+from fastmcp.server.auth.auth import AccessToken, TokenVerifier
+
+__all__ = ["StaticBearerVerifier"]
+
+
+class StaticBearerVerifier(TokenVerifier):
+    """Verifies presented bearer tokens against a fixed set of secrets.
+
+    The presented token is compared against **every** configured token with
+    :func:`secrets.compare_digest` — no early exit — so response timing does
+    not leak which token (if any) matched. With an empty token set every
+    request is rejected: a misconfigured server fails closed.
+
+    A match is attributed to a non-secret client id derived from the token's
+    1-based position in ``OPENPROJECT_MCP_AUTH_TOKENS`` (for example
+    ``openproject-mcp/token-2``), so with one token per client, access logs can
+    say which client authenticated without exposing token material.
+    """
+
+    def __init__(self, tokens: Sequence[str]) -> None:
+        super().__init__()
+        self._tokens = tuple(token.encode("utf-8") for token in tokens)
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        presented = token.encode("utf-8")
+        matched_index = -1
+        for index, candidate in enumerate(self._tokens):
+            if secrets.compare_digest(presented, candidate) and matched_index < 0:
+                matched_index = index
+        if matched_index < 0:
+            return None
+        return AccessToken(
+            token=token, client_id=f"openproject-mcp/token-{matched_index + 1}", scopes=[]
+        )

openproject_mcp/client/__init__.py

@@ -0,0 +1,17 @@
+"""OpenProject API client layer (SPEC §4).
+
+Import surface for tool modules::
+
+    from openproject_mcp.client import OpenProjectClient, TTLCache
+    from openproject_mcp.client.errors import NotFoundError, ValidationFailedError
+    from openproject_mcp.client.filters import make_filter, query_params, status_filter
+    from openproject_mcp.client.hal import collection, formattable, ref, self_id
+    from openproject_mcp.client.locking import patch_with_lock
+    from openproject_mcp.client.payloads import build_write_payload, links_payload
+"""
+
+from openproject_mcp.client.cache import TTLCache, credential_scope
+from openproject_mcp.client.errors import OpenProjectError
+from openproject_mcp.client.http import OpenProjectClient
+
+__all__ = ["OpenProjectClient", "OpenProjectError", "TTLCache", "credential_scope"]

openproject_mcp/client/cache.py

@@ -0,0 +1,147 @@
+"""TTL cache for near-static metadata (SPEC §4.6).
+
+Cached: API root, ``/configuration``, types, statuses, priorities, roles,
+per-project types/versions/categories, WP schemas, time-entry activities,
+``users/me``, and version-probe results (1 h). **Never cached:** lockVersions,
+work packages, or anything else a write can invalidate.
+
+Entries are scoped per credential so a multi-user HTTP deployment cannot serve
+one principal's metadata to another. The scope key is a hash of the credential,
+never the credential itself.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import time
+from collections.abc import Awaitable, Callable, Hashable
+from dataclasses import dataclass
+from typing import Any, TypeVar
+
+__all__ = ["TTLCache", "credential_scope"]
+
+T = TypeVar("T")
+
+DEFAULT_SCOPE = "default"
+
+
+def credential_scope(credential: str | None) -> str:
+    """Return a stable, non-reversible cache scope for a credential."""
+    if not credential:
+        return DEFAULT_SCOPE
+    return hashlib.sha256(credential.encode("utf-8")).hexdigest()[:16]
+
+
+@dataclass(slots=True)
+class _Entry:
+    value: Any
+    expires_at: float
+
+
+class TTLCache:
+    """A small async-safe TTL cache with per-credential key scoping.
+
+    Concurrent misses on the same key are collapsed: the first caller computes,
+    the rest await the same result, so a burst of tool calls does not stampede
+    the metadata endpoints.
+    """
+
+    def __init__(
+        self,
+        *,
+        ttl: float = 300.0,
+        max_entries: int = 1024,
+        time_fn: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self.default_ttl = ttl
+        self.max_entries = max_entries
+        self._time = time_fn
+        self._entries: dict[tuple[str, Hashable], _Entry] = {}
+        self._locks: dict[tuple[str, Hashable], asyncio.Lock] = {}
+
+    # --- basic operations ------------------------------------------------
+
+    def get(self, key: Hashable, *, scope: str = DEFAULT_SCOPE) -> Any | None:
+        """Return the live value for ``key``, or ``None`` when missing/expired."""
+        full_key = (scope, key)
+        entry = self._entries.get(full_key)
+        if entry is None:
+            return None
+        if entry.expires_at <= self._time():
+            self._entries.pop(full_key, None)
+            return None
+        return entry.value
+
+    def set(
+        self,
+        key: Hashable,
+        value: Any,
+        *,
+        scope: str = DEFAULT_SCOPE,
+        ttl: float | None = None,
+    ) -> None:
+        """Store a value; ``ttl=0`` stores nothing."""
+        effective_ttl = self.default_ttl if ttl is None else ttl
+        if effective_ttl <= 0:
+            return
+        self._evict_if_needed()
+        self._entries[(scope, key)] = _Entry(value, self._time() + effective_ttl)
+
+    def invalidate(self, key: Hashable, *, scope: str = DEFAULT_SCOPE) -> None:
+        self._entries.pop((scope, key), None)
+
+    def invalidate_scope(self, scope: str) -> None:
+        for full_key in [k for k in self._entries if k[0] == scope]:
+            self._entries.pop(full_key, None)
+
+    def clear(self) -> None:
+        self._entries.clear()
+        self._locks.clear()
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    # --- memoization -----------------------------------------------------
+
+    async def get_or_set(
+        self,
+        key: Hashable,
+        factory: Callable[[], Awaitable[T]],
+        *,
+        scope: str = DEFAULT_SCOPE,
+        ttl: float | None = None,
+        refresh: bool = False,
+    ) -> T:
+        """Return the cached value or compute, store and return it.
+
+        ``refresh=True`` bypasses the cached value and recomputes — this is the
+        ``refresh=true`` parameter the metadata tools expose. A factory that
+        raises does not poison the cache.
+        """
+        full_key = (scope, key)
+        if not refresh:
+            cached = self.get(key, scope=scope)
+            if cached is not None:
+                return cached  # type: ignore[return-value]
+
+        lock = self._locks.setdefault(full_key, asyncio.Lock())
+        async with lock:
+            if not refresh:
+                cached = self.get(key, scope=scope)
+                if cached is not None:
+                    return cached  # type: ignore[return-value]
+            value = await factory()
+            self.set(key, value, scope=scope, ttl=ttl)
+            return value
+
+    # --- internals -------------------------------------------------------
+
+    def _evict_if_needed(self) -> None:
+        if len(self._entries) < self.max_entries:
+            return
+        now = self._time()
+        for full_key in [k for k, entry in self._entries.items() if entry.expires_at <= now]:
+            self._entries.pop(full_key, None)
+        while len(self._entries) >= self.max_entries:
+            self._entries.pop(next(iter(self._entries)))