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

sg_mcp_server/__init__.py

@@ -0,0 +1,19 @@
+"""Provide the read-only MCP server for Flow Production Tracking.
+
+Run `sg-mcp-server`, run `python -m sg_mcp_server`, or call `main()` to serve
+the solo-mode tool surface over stdio in the foreground. `main()` parses
+`sys.argv` unless given an argument list, accepts no arguments other than
+`--help` and `--version`, and returns the process exit status. `--help` and
+invalid arguments end in `SystemExit` from argument parsing; `--version`
+returns 0 after printing the version.
+
+Set `SG_MCP_SITE_URL`, `SG_MCP_SCRIPT_NAME`, and `SG_MCP_API_KEY` for the site
+connection. Optional `SG_MCP_TIMEZONE`, `SG_MCP_AUDIT_PATH`,
+`SG_MCP_DEFAULT_LIMIT`, `SG_MCP_HARD_LIMIT`, `SG_MCP_SCHEMA_TTL_SECONDS`,
+`SG_MCP_TIMEOUT_SECONDS`, and `SG_MCP_DIAGNOSTICS_PATH` settings control
+rendering, logging, query limits, the SG request timeout, and schema caching.
+"""
+
+from sg_mcp_server._cli import main
+
+__all__ = ['main']

sg_mcp_server/__main__.py

@@ -0,0 +1,13 @@
+"""Serve the read-only solo-mode MCP tools over stdio.
+
+Run `python -m sg_mcp_server` with `SG_MCP_SITE_URL`, `SG_MCP_SCRIPT_NAME`, and
+`SG_MCP_API_KEY` set. The command uses the same optional environment settings
+as `sg-mcp-server` and runs the server in the foreground.
+"""
+
+import sys
+
+from sg_mcp_server._cli import main
+
+if __name__ == '__main__':
+    sys.exit(main())

sg_mcp_server/_audit.py

@@ -0,0 +1,66 @@
+"""Append-only JSONL security audit log."""
+
+import datetime
+import hashlib
+import json
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+
+from sg_mcp_server._diagnostics import DiagnosticOutcome
+
+
+class AuditLog:
+    """Records every tool invocation; payloads are hashed, never stored.
+
+    A failed audit write warns on standard error, and the read proceeds.
+    """
+
+    def __init__(self, path: Path, caller: str) -> None:
+        """Store the target path and caller identity.
+
+        No filesystem access happens here: directory creation lives in the
+        guarded write path, so an unwritable location degrades to the
+        documented warn-and-proceed behavior instead of aborting server
+        startup.
+        """
+        self._path = path
+        self._caller = caller
+
+    def record_tool_call(
+        self,
+        tool: str,
+        input_payload: Mapping[str, object],
+        outcome: DiagnosticOutcome,
+        duration_ms: float,
+        entity_ids: list[int] | None = None,
+    ) -> None:
+        """Append one audit entry.
+
+        Args:
+            tool: Tool name as listed to clients.
+            input_payload: Tool arguments to fingerprint: the default-filled
+                arguments of a dispatched call, or the raw arguments of a
+                rejected one. Only their SHA-256 is written.
+            outcome: One of `ok`, `validation_error`, `query_error`,
+                `unexpected_error`, `invalid_arguments`, or `unknown_tool`.
+            duration_ms: Wall time of the call.
+            entity_ids: Ids of entities the response touched, if known.
+        """
+        entry = {
+            'ts': datetime.datetime.now(datetime.UTC).isoformat(),
+            'caller': self._caller,
+            'tool': tool,
+            'input_sha256': hashlib.sha256(
+                json.dumps(input_payload, sort_keys=True, default=str).encode()
+            ).hexdigest(),
+            'outcome': outcome,
+            'duration_ms': round(duration_ms, 3),
+            'entity_ids': entity_ids or [],
+        }
+        try:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            with self._path.open('a', encoding='utf-8') as handle:
+                handle.write(json.dumps(entry) + '\n')
+        except OSError as error:
+            print(f'warning: audit write failed: {error}', file=sys.stderr)

sg_mcp_server/_cli.py

@@ -0,0 +1,276 @@
+"""Parse the sg-mcp-server command line and serve MCP over standard streams."""
+
+import argparse
+import asyncio
+import importlib.metadata
+import io
+import os
+import re
+import sys
+import threading
+from collections.abc import AsyncIterator, Generator, Sequence
+from contextlib import ExitStack, contextmanager, suppress
+from typing import cast
+
+import anyio
+from mcp import stdio_server
+from mcp.os.win32.utilities import rebind_std_handle_to_fd
+from mcp.server import Server
+
+from sg_mcp_server import _tools
+from sg_mcp_server._config import Config, ConfigError
+from sg_mcp_server._downstream import is_downstream_closure, silence_descriptor, write_stdout
+from sg_mcp_server._providers import connect
+from sg_mcp_server._server import build_server
+
+_CONTROL_CHARACTERS = re.compile(r'[\x00-\x1f\x7f-\x9f]')
+_DESCRIPTION = 'Serve read-only SG tools to an MCP client over standard input and output.'
+_EPILOG = """\
+An MCP client normally starts this command, which serves until the client
+disconnects. Set these environment variables in the client's configuration:
+
+  SG_MCP_SITE_URL            HTTPS site address (required)
+  SG_MCP_SCRIPT_NAME         script name used for all requests (required)
+  SG_MCP_API_KEY             API key for that script (required)
+  SG_MCP_TIMEZONE            IANA time zone for dates (default: UTC)
+  SG_MCP_AUDIT_PATH          security audit file
+                             (default: ~/.sg-mcp-server/audit.jsonl)
+  SG_MCP_DIAGNOSTICS_PATH    latency diagnostics file (default: off)
+  SG_MCP_DEFAULT_LIMIT       row limit when a query omits one (default: 50)
+  SG_MCP_HARD_LIMIT          maximum row limit (default: 200)
+  SG_MCP_SCHEMA_TTL_SECONDS  seconds to reuse the cached schema (default: 900)
+  SG_MCP_TIMEOUT_SECONDS     seconds to wait on the SG site (default: 60)
+
+See "Settings" in the usage guide, docs/usage.md, for details."""
+_METADATA_MISSING = 'installed distribution metadata for sg-mcp-server is unavailable'
+_SG_CLIENT_MODULE = 'shotgun_api3'
+
+
+class _ProtocolInputError(Exception):
+    """A protocol input failure that must not be mistaken for output closure."""
+
+
+class _ProtocolInput(anyio.AsyncFile[str]):
+    """Client messages read on daemon threads, so a stop never waits for more input."""
+
+    def __init__(self) -> None:
+        """Read standard input through a private UTF-8 reader on its descriptor."""
+        try:
+            descriptor = sys.stdin.fileno()
+        except (OSError, ValueError):
+            # A replaced stream without a descriptor, such as an in-memory one, is read as it is.
+            stream = sys.stdin
+        else:
+            # closefd=False leaves sys.stdin open when this reader closes, and without a buffer
+            # the read that a stop abandons holds no lock.
+            raw = io.FileIO(descriptor, closefd=False)
+            stream = io.TextIOWrapper(raw, encoding='utf-8', errors='replace')
+        super().__init__(stream)
+
+    async def __aiter__(self) -> AsyncIterator[str]:
+        """Yield each line until the client ends its input."""
+        while line := await self.readline():
+            yield line
+
+    async def readline(self) -> str:
+        """Return the next line, or an empty string once the client ends its input."""
+        loop = asyncio.get_running_loop()
+        line: asyncio.Future[str] = loop.create_future()
+
+        def settle(result: str | OSError | ValueError) -> None:
+            if line.done():  # the session stopped while this read was waiting
+                return
+            if isinstance(result, str):
+                line.set_result(result)
+            else:
+                line.set_exception(result)
+
+        def read() -> None:
+            result: str | OSError | ValueError
+            try:
+                result = self.wrapped.readline()
+            except (OSError, ValueError) as error:
+                result = error
+            with suppress(RuntimeError):  # the event loop closed after the session stopped
+                loop.call_soon_threadsafe(settle, result)
+
+        threading.Thread(target=read, name='MCP input', daemon=True).start()
+        try:
+            return await line
+        except OSError as error:
+            raise _ProtocolInputError('standard input read failed') from error
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build the parser for the help and version options."""
+    parser = argparse.ArgumentParser(
+        prog='sg-mcp-server',
+        description=_DESCRIPTION,
+        epilog=_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        allow_abbrev=False,
+    )
+    parser.add_argument('--version', action='store_true', help='show the version and exit')
+    return parser
+
+
+def _client_disconnected(error: BaseException) -> bool:
+    """Report whether serving stopped only because the client closed standard output."""
+    if isinstance(error, BaseExceptionGroup):
+        group = cast('BaseExceptionGroup[BaseException]', error)
+        return all(_client_disconnected(item) for item in group.exceptions)
+    return isinstance(error, OSError) and is_downstream_closure(error)
+
+
+@contextmanager
+def _divert_stdout(protocol_descriptor: int) -> Generator[None, None, None]:
+    """Keep ordinary writes and child output off the protocol until serving stops."""
+    try:
+        diversion = os.dup(2)
+    except OSError:
+        diversion = os.open(os.devnull, os.O_WRONLY)
+    try:
+        try:
+            os.dup2(diversion, 1)
+            with suppress(OSError):
+                rebind_std_handle_to_fd(1)
+            yield
+        finally:
+            os.dup2(protocol_descriptor, 1)
+            with suppress(OSError):
+                rebind_std_handle_to_fd(1)
+    finally:
+        os.close(diversion)
+
+
+@contextmanager
+def _protocol_output() -> Generator[anyio.AsyncFile[str], None, None]:
+    """Own the UTF-8 protocol writer without closing the caller's output stream."""
+    try:
+        descriptor = sys.stdout.fileno()
+    except (OSError, ValueError):
+        # Replaced streams retain their buffer and do not need descriptor diversion.
+        output = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+        try:
+            yield anyio.wrap_file(output)
+        finally:
+            output.detach()
+        return
+
+    # A missing standard stream must not become our protocol descriptor or diversion.
+    with ExitStack() as reserved:
+        while (duplicate := os.dup(descriptor)) in (0, 1, 2):
+            reserved.callback(os.close, duplicate)
+    with io.FileIO(duplicate, 'w') as raw:
+        output = io.TextIOWrapper(io.BufferedWriter(raw), encoding='utf-8')
+        try:
+            if descriptor == 1:
+                with _divert_stdout(duplicate):
+                    yield anyio.wrap_file(output)
+            else:
+                yield anyio.wrap_file(output)
+        finally:
+            try:
+                # Closing the owned buffer also discards bytes from a failed flush. Leaving
+                # it for garbage collection retries that flush outside our error handler.
+                output.close()
+            except OSError as error:
+                if not is_downstream_closure(error):
+                    raise
+
+
+def _report_error(message: str) -> None:
+    """Print one terminal-safe error line to standard error."""
+    visible = _CONTROL_CHARACTERS.sub(lambda match: f'\\x{ord(match.group()):02x}', message)
+    print(f'error: {visible}', file=sys.stderr)
+
+
+def _render_version() -> tuple[int, str]:
+    """Render the installed distribution version without other work."""
+    try:
+        version = importlib.metadata.version('sg-mcp-server')
+    except importlib.metadata.PackageNotFoundError:
+        _report_error(_METADATA_MISSING)
+        return 2, ''
+    return 0, f'sg-mcp-server {version}\n'
+
+
+async def _serve_stdio(server: Server) -> None:
+    """Serve one MCP session over the process's standard input and output."""
+    with _protocol_output() as stdout:
+        async with stdio_server(stdin=_ProtocolInput(), stdout=stdout) as (
+            read_stream,
+            write_stream,
+        ):
+            await server.run(read_stream, write_stream, server.create_initialization_options())
+
+
+def _serve(server: Server) -> int:
+    """Serve one client, treating a disconnect or an interrupt as a normal stop."""
+    try:
+        asyncio.run(_serve_stdio(server))
+    except KeyboardInterrupt:
+        return 0
+    except (OSError, BaseExceptionGroup) as error:
+        if not _client_disconnected(error):
+            raise
+        # The transport restored the closed pipe; keep the final flush off it.
+        silence_descriptor(sys.stdout)
+    return 0
+
+
+def _run(arguments: list[str]) -> tuple[int, str]:
+    """Parse arguments, then render the version or serve the tools."""
+    args = _build_parser().parse_args(arguments)
+    if args.version:
+        return _render_version()
+    try:
+        config = Config.from_env(os.environ)
+        server = build_server(config, connect(config), _tools.surface())
+    except ConfigError as error:
+        _report_error(str(error))
+        return 2, ''
+    except importlib.metadata.PackageNotFoundError:
+        # A subclass of ModuleNotFoundError, so it is matched first.
+        _report_error(_METADATA_MISSING)
+        return 2, ''
+    except ModuleNotFoundError as error:
+        if error.name != _SG_CLIENT_MODULE:
+            raise
+        _report_error(
+            'the SG client is not installed; reinstall sg-mcp-server with the official extra'
+        )
+        return 2, ''
+    return _serve(server), ''
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the sg-mcp-server command-line interface.
+
+    With no arguments, serve the read-only tools to one MCP client over
+    standard input and output. `--version` writes the installed version and
+    returns 0. `--help` and invalid arguments end in `SystemExit` from argument
+    parsing. A client disconnect, the end of input, and an interrupt while
+    serving each stop the server with status 0, once calls in progress finish.
+    If the reader closes standard output, unwritten output is discarded while
+    the status still reports the result.
+
+    Args:
+        argv: Arguments to parse, or `None` to use `sys.argv`.
+
+    Returns:
+        The process exit status.
+    """
+    if sys.stdout is None:
+        # Started with standard output closed: nothing can be delivered.
+        _report_error('standard output is unavailable')
+        return 2
+    output = ''
+    try:
+        status, output = _run(sys.argv[1:] if argv is None else list(argv))
+    except KeyboardInterrupt:
+        status = 130
+    finally:
+        # Also flushes help or usage text that argparse wrote before raising SystemExit.
+        write_stdout(output)
+    return status

sg_mcp_server/_config.py

@@ -0,0 +1,185 @@
+"""Environment-driven configuration for the solo-mode server."""
+
+import dataclasses
+import urllib.parse
+from collections.abc import Mapping
+from pathlib import Path
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+_DEFAULT_AUDIT_PATH = Path.home() / '.sg-mcp-server' / 'audit.jsonl'
+DEFAULT_LIMIT = 50
+HARD_LIMIT = 200
+_SCHEMA_TTL_SECONDS = 900
+_TIMEOUT_SECONDS = 60
+
+
+class ConfigError(Exception):
+    """Raised when required configuration is missing or malformed.
+
+    The message is one lowercase clause that names the setting, suitable for an
+    `error:` line, and never repeats credentials from the site URL.
+    """
+
+
+@dataclasses.dataclass(frozen=True)
+class Config:
+    """Resolved connection, rendering, logging, and query-limit settings.
+
+    Instances have fixed attributes. The site URL is normalized to an HTTPS
+    origin, query limits satisfy `1 <= default_limit <= hard_limit`, and the SG
+    request timeout is positive.
+
+    Attributes:
+        site_url: HTTPS site origin without a trailing slash.
+        script_name: Flow Production Tracking script identity.
+        api_key: API key belonging to the script identity.
+        timezone: IANA timezone used for date rendering and relative dates.
+        audit_path: Destination for the security audit JSONL log.
+        default_limit: Row limit used when a query omits one.
+        hard_limit: Maximum permitted query row limit.
+        schema_ttl_seconds: Schema-cache lifetime in seconds.
+        diagnostics_path: Optional request-diagnostics JSONL destination;
+            `None` disables request diagnostics.
+        timeout_seconds: Positive timeout for each SG connection attempt and
+            data wait.
+    """
+
+    site_url: str
+    script_name: str
+    api_key: str
+    timezone: str = 'UTC'
+    audit_path: Path = _DEFAULT_AUDIT_PATH
+    default_limit: int = DEFAULT_LIMIT
+    hard_limit: int = HARD_LIMIT
+    schema_ttl_seconds: int = _SCHEMA_TTL_SECONDS
+    diagnostics_path: Path | None = None
+    timeout_seconds: int = _TIMEOUT_SECONDS
+
+    def __post_init__(self) -> None:
+        """Validate the site origin, timezone, and bounded query limits.
+
+        Raises:
+            ConfigError: If the site URL is not a valid bare HTTPS origin, the
+                timezone is unavailable or invalid, or limits do not satisfy `1
+                <= default_limit <= hard_limit`, or the timeout is below 1.
+        """
+        site_url_message = (
+            'the SG_MCP_SITE_URL setting must be an HTTPS origin with a valid host and port, '
+            'without userinfo, a non-root path, a query, or a fragment'
+        )
+        try:
+            parsed_site_url = urllib.parse.urlsplit(self.site_url)
+            _ = parsed_site_url.port
+        except ValueError:
+            raise ConfigError(site_url_message) from None
+        if (
+            parsed_site_url.scheme != 'https'
+            or parsed_site_url.hostname is None
+            or parsed_site_url.username is not None
+            or parsed_site_url.password is not None
+            or parsed_site_url.path not in {'', '/'}
+            or parsed_site_url.query
+            or parsed_site_url.fragment
+            or '?' in self.site_url
+            or '#' in self.site_url
+            or parsed_site_url.netloc.endswith(':')
+        ):
+            raise ConfigError(site_url_message)
+        normalized_site_url = urllib.parse.urlunsplit(
+            (parsed_site_url.scheme, parsed_site_url.netloc, '', '', '')
+        )
+        object.__setattr__(self, 'site_url', normalized_site_url)
+
+        try:
+            ZoneInfo(self.timezone)
+        except (ValueError, ZoneInfoNotFoundError):
+            message = 'the SG_MCP_TIMEZONE setting must name an available IANA timezone'
+            raise ConfigError(message) from None
+
+        if self.default_limit < 1 or self.hard_limit < self.default_limit:
+            message = (
+                'limits must satisfy 1 <= SG_MCP_DEFAULT_LIMIT <= SG_MCP_HARD_LIMIT '
+                f'(SG treats limit 0 as unlimited); got {self.default_limit} '
+                f'and {self.hard_limit}'
+            )
+            raise ConfigError(message)
+
+        if self.timeout_seconds < 1:
+            raise ConfigError(
+                'the SG_MCP_TIMEOUT_SECONDS setting must be a positive integer, '
+                f'got {self.timeout_seconds}'
+            )
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str]) -> 'Config':
+        """Resolve server settings from the supported environment variables.
+
+        Args:
+            env: Environment mapping, normally `os.environ`. Requires nonblank
+                `SG_MCP_SITE_URL`, `SG_MCP_SCRIPT_NAME`, and `SG_MCP_API_KEY`;
+                these values are stripped. Optional `SG_MCP_TIMEZONE` and
+                `SG_MCP_AUDIT_PATH` override rendering and audit settings;
+                the audit path is stripped and must not be blank.
+                Optional `SG_MCP_DEFAULT_LIMIT`, `SG_MCP_HARD_LIMIT`,
+                `SG_MCP_SCHEMA_TTL_SECONDS`, and `SG_MCP_TIMEOUT_SECONDS` are
+                parsed as integers; the timeout must be at least 1. Unset
+                optional settings use `Config` defaults. An absent or blank
+                `SG_MCP_DIAGNOSTICS_PATH` disables request diagnostics.
+
+        Returns:
+            The resolved configuration with a normalized HTTPS site origin.
+
+        Raises:
+            ConfigError: If a required variable is absent, a numeric override
+                does not parse, the audit path is blank, the site URL violates
+                the HTTPS-origin rules, the timezone is unavailable or invalid,
+                the resolved limit combination is invalid, or the timeout is
+                below 1.
+        """
+
+        def require(name: str) -> str:
+            value = env.get(name, '').strip()
+            if not value:
+                message = f'the {name} setting is required'
+                raise ConfigError(message)
+            return value
+
+        def integer(name: str, fallback: int) -> int:
+            raw = env.get(name)
+            if raw is None:
+                return fallback
+            try:
+                return int(raw)
+            except ValueError as error:
+                message = f'the {name} setting must be an integer, got {raw!r}'
+                raise ConfigError(message) from error
+
+        def optional_path(name: str) -> Path | None:
+            raw = env.get(name, '').strip()
+            return Path(raw) if raw else None
+
+        def audit_path() -> Path:
+            raw = env.get('SG_MCP_AUDIT_PATH')
+            if raw is None:
+                return _DEFAULT_AUDIT_PATH
+            value = raw.strip()
+            if not value:
+                # Path('') is the working directory, where every audit write would fail.
+                message = (
+                    'the SG_MCP_AUDIT_PATH setting must not be blank; unset it to use the default'
+                )
+                raise ConfigError(message)
+            return Path(value)
+
+        return cls(
+            site_url=require('SG_MCP_SITE_URL'),
+            script_name=require('SG_MCP_SCRIPT_NAME'),
+            api_key=require('SG_MCP_API_KEY'),
+            timezone=env.get('SG_MCP_TIMEZONE', 'UTC'),
+            audit_path=audit_path(),
+            default_limit=integer('SG_MCP_DEFAULT_LIMIT', DEFAULT_LIMIT),
+            hard_limit=integer('SG_MCP_HARD_LIMIT', HARD_LIMIT),
+            schema_ttl_seconds=integer('SG_MCP_SCHEMA_TTL_SECONDS', _SCHEMA_TTL_SECONDS),
+            diagnostics_path=optional_path('SG_MCP_DIAGNOSTICS_PATH'),
+            timeout_seconds=integer('SG_MCP_TIMEOUT_SECONDS', _TIMEOUT_SECONDS),
+        )