intercept-mcp 0.2.2__py3-none-any.whl

intercept_mcp/VERSION

@@ -0,0 +1 @@
+0.2.2

intercept_mcp/__init__.py

@@ -0,0 +1,16 @@
+"""intercept-mcp: MCP server for the Intercept platform."""
+
+from pathlib import Path
+
+
+def _read_version() -> str:
+    here = Path(__file__).parent
+    for candidate in (here / "VERSION", here.parent / "VERSION"):
+        if candidate.exists():
+            return candidate.read_text(encoding="utf-8").strip()
+    return "0.0.0+unknown"
+
+
+__version__ = _read_version()
+
+__all__ = ["__version__"]

intercept_mcp/client.py

@@ -0,0 +1,175 @@
+"""HTTP client for the Intercept REST API."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import httpx
+
+from intercept_mcp import __version__
+
+DEFAULT_BASE_URL = "https://intercept.hijacksecurity.com"
+_CONNECT_TIMEOUT = 30.0
+_READ_TIMEOUT = 60.0
+_MAX_429_RETRIES = 3
+
+
+class InterceptApiError(Exception):
+    """Raised when the Intercept API returns a non-2xx response."""
+
+    def __init__(self, status_code: int, message: str) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.message = message
+
+
+def _redact_headers(headers: dict[str, str] | httpx.Headers) -> dict[str, str]:
+    """Return a copy of `headers` with credential-bearing values replaced by `[REDACTED]`."""
+    redacted: dict[str, str] = {}
+    for key, value in dict(headers).items():
+        lk = key.lower()
+        if lk in ("authorization", "x-api-key", "cookie", "set-cookie"):
+            redacted[key] = "[REDACTED]"
+        else:
+            redacted[key] = value
+    return redacted
+
+
+class InterceptApiClient:
+    """Async HTTP client for the Intercept API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key must be a non-empty string")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            timeout=httpx.Timeout(connect=_CONNECT_TIMEOUT, read=_READ_TIMEOUT, write=_READ_TIMEOUT, pool=_READ_TIMEOUT),
+            headers={
+                "X-API-Key": api_key,
+                "User-Agent": f"intercept-mcp/{__version__}",
+                "Accept": "application/json",
+            },
+            transport=transport,
+        )
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "InterceptApiClient":
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+    ) -> Any:
+        """Issue an HTTP request and return the parsed JSON body.
+
+        Raises `InterceptApiError` on non-2xx responses. Retries up to
+        `_MAX_429_RETRIES` times on 429, honoring `Retry-After`.
+        """
+        clean_params = (
+            {k: v for k, v in params.items() if v is not None} if params else None
+        )
+
+        attempts = 0
+        while True:
+            response = await self._client.request(
+                method,
+                path,
+                params=clean_params,
+                json=json,
+            )
+
+            if response.status_code == 429 and attempts < _MAX_429_RETRIES:
+                retry_after = _parse_retry_after(response.headers.get("Retry-After"))
+                attempts += 1
+                await asyncio.sleep(retry_after)
+                continue
+
+            if response.is_success:
+                if response.status_code == 204 or not response.content:
+                    return None
+                try:
+                    return response.json()
+                except ValueError as exc:
+                    raise InterceptApiError(
+                        response.status_code,
+                        f"Intercept API returned non-JSON body: {exc}",
+                    ) from exc
+
+            raise InterceptApiError(
+                response.status_code,
+                _format_error(response),
+            )
+
+
+def _parse_retry_after(value: str | None) -> float:
+    """Parse a numeric `Retry-After` header into seconds. Falls back to 1.0s."""
+    if value is None:
+        return 1.0
+    try:
+        return max(0.0, float(value))
+    except (TypeError, ValueError):
+        return 1.0
+
+
+def _format_error(response: httpx.Response) -> str:
+    """Translate an HTTP error response into a short, readable message."""
+    code = response.status_code
+    detail = _extract_detail(response)
+    if code == 401:
+        return (
+            "authentication failed: INTERCEPT_MCP_API_KEY is missing or invalid. "
+            "Generate a personal-scope key from Settings -> Integrations."
+        )
+    if code == 403:
+        return f"permission denied{_suffix(detail)}"
+    if code == 404:
+        return f"not found{_suffix(detail)}"
+    if code == 422:
+        return f"validation error{_suffix(detail)}"
+    if code == 429:
+        retry = response.headers.get("Retry-After", "?")
+        return f"rate limited, retry after {retry}s"
+    if 500 <= code < 600:
+        return f"server error {code}{_suffix(detail)}"
+    return f"HTTP {code}{_suffix(detail)}"
+
+
+def _extract_detail(response: httpx.Response) -> str | None:
+    """Pull `detail` from a JSON error body, or return None."""
+    try:
+        body = response.json()
+    except ValueError:
+        return None
+    if isinstance(body, dict):
+        detail = body.get("detail")
+        if isinstance(detail, str):
+            return detail
+        if detail is not None:
+            return str(detail)
+    return None
+
+
+def _suffix(detail: str | None) -> str:
+    return f": {detail}" if detail else ""

intercept_mcp/logging_setup.py

@@ -0,0 +1,78 @@
+"""JSON logging to stderr with API-key redaction."""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import sys
+from typing import Any
+
+_API_KEY_RE = re.compile(r"hsk_[A-Za-z0-9_\-]{8,}")
+_REDACTED = "[REDACTED]"
+
+
+def _redact(value: Any) -> Any:
+    """Recursively replace API-key-shaped substrings with `[REDACTED]`."""
+    if isinstance(value, str):
+        return _API_KEY_RE.sub(_REDACTED, value)
+    if isinstance(value, dict):
+        return {k: _redact(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_redact(v) for v in value]
+    return value
+
+
+class _JsonFormatter(logging.Formatter):
+    """Format each record as a single-line JSON object."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload: dict[str, Any] = {
+            "ts": self.formatTime(record, "%Y-%m-%dT%H:%M:%S%z"),
+            "level": record.levelname,
+            "logger": record.name,
+            "msg": _redact(record.getMessage()),
+        }
+        extras = getattr(record, "extra_fields", None)
+        if isinstance(extras, dict):
+            payload.update({k: _redact(v) for k, v in extras.items()})
+        if record.exc_info:
+            payload["exc"] = _redact(self.formatException(record.exc_info))
+        return json.dumps(payload, default=str)
+
+
+class _RedactingFilter(logging.Filter):
+    """Strip API-key-shaped substrings from the record message and args."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        if isinstance(record.msg, str):
+            record.msg = _API_KEY_RE.sub(_REDACTED, record.msg)
+        if record.args:
+            try:
+                record.args = tuple(_redact(a) for a in record.args)  # type: ignore[assignment]
+            except Exception:  # noqa: BLE001
+                pass
+        return True
+
+
+def configure_logging(level: int = logging.INFO) -> logging.Logger:
+    """Install a stderr-only JSON handler on the `intercept_mcp` logger.
+
+    Idempotent: replaces any previously installed handler so the stream
+    reference stays current when test frameworks swap `sys.stderr`.
+    """
+    logger = logging.getLogger("intercept_mcp")
+    logger.setLevel(level)
+    logger.propagate = False
+
+    for existing in list(logger.handlers):
+        if getattr(existing, "_intercept_mcp_handler", False):
+            logger.removeHandler(existing)
+
+    handler = logging.StreamHandler(stream=sys.stderr)
+    handler.setFormatter(_JsonFormatter())
+    handler.addFilter(_RedactingFilter())
+    handler._intercept_mcp_handler = True  # type: ignore[attr-defined]
+    logger.addHandler(handler)
+
+    return logger

intercept_mcp/main.py

@@ -0,0 +1,85 @@
+"""Console entry point for the `intercept-mcp` server."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import sys
+
+import mcp.server.stdio
+from mcp.server.lowlevel import NotificationOptions
+from mcp.server.models import InitializationOptions
+
+from intercept_mcp import __version__
+from intercept_mcp.client import DEFAULT_BASE_URL, InterceptApiClient
+from intercept_mcp.logging_setup import configure_logging
+from intercept_mcp.server import SERVER_NAME, build_server
+
+API_KEY_ENV = "INTERCEPT_MCP_API_KEY"
+API_URL_ENV = "INTERCEPT_API_URL"
+
+
+def _missing_key_message() -> str:
+    return (
+        f"{API_KEY_ENV} is not set. Generate a personal-scope MCP API key "
+        "from the Intercept web UI: Settings -> Integrations -> Generate "
+        "MCP API Key. Then export it from your shell profile, e.g.:\n"
+        f"  export {API_KEY_ENV}=hsk_...\n"
+        "Or set it in your MCP client config's env block."
+    )
+
+
+async def _serve(api_key: str, base_url: str) -> None:
+    log = logging.getLogger("intercept_mcp")
+    async with InterceptApiClient(api_key=api_key, base_url=base_url) as client:
+        server = build_server(client)
+        log.info(
+            "starting intercept-mcp",
+            extra={
+                "extra_fields": {
+                    "version": __version__,
+                    "base_url": base_url,
+                }
+            },
+        )
+        async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
+            await server.run(
+                read_stream,
+                write_stream,
+                InitializationOptions(
+                    server_name=SERVER_NAME,
+                    server_version=__version__,
+                    capabilities=server.get_capabilities(
+                        notification_options=NotificationOptions(),
+                        experimental_capabilities={},
+                    ),
+                ),
+            )
+
+
+def run() -> None:
+    """Validate environment, configure logging, and run the stdio loop.
+
+    Exit codes: 0 on clean shutdown, 2 on configuration or fatal error.
+    """
+    log = configure_logging()
+
+    api_key = os.environ.get(API_KEY_ENV, "").strip()
+    if not api_key:
+        print(_missing_key_message(), file=sys.stderr)
+        sys.exit(2)
+
+    base_url = os.environ.get(API_URL_ENV, DEFAULT_BASE_URL).strip() or DEFAULT_BASE_URL
+
+    try:
+        asyncio.run(_serve(api_key=api_key, base_url=base_url))
+    except KeyboardInterrupt:
+        log.info("shutdown: keyboard interrupt")
+    except Exception:
+        log.exception("fatal error in stdio loop")
+        sys.exit(2)
+
+
+if __name__ == "__main__":
+    run()

intercept_mcp/server.py

@@ -0,0 +1,106 @@
+"""MCP protocol layer: wires the tool registry into an MCP Server."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+import mcp.types as types
+from mcp.server.lowlevel import Server
+from pydantic import ValidationError
+
+from intercept_mcp import __version__
+from intercept_mcp.client import InterceptApiClient, InterceptApiError
+from intercept_mcp.tools import ALL_TOOLS, ToolSpec
+from intercept_mcp.utils.sanitize import redact_for_error
+
+SERVER_NAME = "intercept-mcp"
+
+_log = logging.getLogger("intercept_mcp")
+
+_MAX_VALIDATION_HINTS = 5
+
+
+def _summarize_validation_errors(exc: ValidationError) -> str:
+    """Render a short summary of a Pydantic ValidationError with redacted echoes."""
+    hints: list[str] = []
+    for err in exc.errors()[:_MAX_VALIDATION_HINTS]:
+        loc_parts = [str(p) for p in err.get("loc", ())]
+        loc = ".".join(loc_parts) or "<root>"
+        msg = err.get("msg", "invalid")
+        safe_msg = redact_for_error(msg)
+        hints.append(f"{loc}: {safe_msg}")
+    if len(exc.errors()) > _MAX_VALIDATION_HINTS:
+        hints.append(
+            f"...and {len(exc.errors()) - _MAX_VALIDATION_HINTS} more"
+        )
+    return "; ".join(hints)
+
+
+def build_server(client: InterceptApiClient, tools: list[ToolSpec] | None = None) -> Server:
+    """Construct an MCP `Server` bound to the supplied API client.
+
+    Tools default to `ALL_TOOLS`; tests can pass a subset.
+    """
+    spec_list = tools if tools is not None else ALL_TOOLS
+    by_name: dict[str, ToolSpec] = {s.name: s for s in spec_list}
+
+    server: Server = Server(SERVER_NAME, version=__version__)
+
+    @server.list_tools()
+    async def _list_tools() -> list[types.Tool]:
+        return [
+            types.Tool(
+                name=spec.name,
+                description=spec.description,
+                inputSchema=spec.input_schema,
+            )
+            for spec in spec_list
+        ]
+
+    @server.call_tool()
+    async def _call_tool(
+        name: str, arguments: dict[str, Any] | None
+    ) -> list[types.TextContent]:
+        spec = by_name.get(name)
+        if spec is None:
+            _log.warning(
+                "call_tool: unknown tool",
+                extra={"extra_fields": {"tool": redact_for_error(name)}},
+            )
+            raise ValueError(f"unknown tool: {redact_for_error(name)}")
+
+        try:
+            args = spec.input_model.model_validate(arguments or {})
+        except ValidationError as exc:
+            _log.info(
+                "call_tool: invalid arguments",
+                extra={
+                    "extra_fields": {
+                        "tool": name,
+                        "errors": exc.errors(),
+                    }
+                },
+            )
+            summary = _summarize_validation_errors(exc)
+            raise ValueError(
+                f"invalid arguments for {name}: {summary}"
+            ) from exc
+
+        try:
+            result = await spec.handler(client, args)
+        except InterceptApiError as exc:
+            _log.info(
+                "call_tool: api error",
+                extra={"extra_fields": {"tool": name, "status": exc.status_code}},
+            )
+            raise ValueError(redact_for_error(exc.message, truncate=False)) from exc
+
+        if isinstance(result, str):
+            text = result
+        else:
+            text = json.dumps(result, default=str)
+        return [types.TextContent(type="text", text=text)]
+
+    return server

intercept_mcp/tools/__init__.py

@@ -0,0 +1,9 @@
+"""MCP tool definitions for the Intercept server."""
+
+from intercept_mcp.tools.read import READ_TOOLS
+from intercept_mcp.tools.spec import ToolSpec
+from intercept_mcp.tools.write import WRITE_TOOLS
+
+ALL_TOOLS: list[ToolSpec] = [*READ_TOOLS, *WRITE_TOOLS]
+
+__all__ = ["ALL_TOOLS", "ToolSpec"]