node804-mcp-toolkit 0.1.0__py3-none-any.whl

node804_mcp_toolkit/__init__.py

@@ -0,0 +1,45 @@
+"""Shared utilities for token-efficient MCP servers.
+
+Public API re-exported here for convenience::
+
+    from node804_mcp_toolkit import Mode, ModeGate, audit, open_sink, whitelist, ...
+"""
+
+from .audit import (
+    AuditCategory,
+    AuditEvent,
+    AuditSink,
+    JsonlSink,
+    audit,
+    open_sink,
+    sanitize_args,
+)
+from .lean import filter_by_pattern, paginate, strip_keys, whitelist
+from .params import FieldsList, Pagination, Pattern, VerboseFlag
+from .rbac import Mode, ModeGate
+from .tls import TlsConfig, describe_tls, resolve_tls_config
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AuditCategory",
+    "AuditEvent",
+    "AuditSink",
+    "FieldsList",
+    "JsonlSink",
+    "Mode",
+    "ModeGate",
+    "Pagination",
+    "Pattern",
+    "TlsConfig",
+    "VerboseFlag",
+    "audit",
+    "describe_tls",
+    "filter_by_pattern",
+    "open_sink",
+    "paginate",
+    "resolve_tls_config",
+    "sanitize_args",
+    "strip_keys",
+    "whitelist",
+]

node804_mcp_toolkit/audit.py

@@ -0,0 +1,315 @@
+"""Audit logging for MCP tool invocations.
+
+Each tool call emits one JSON-lines event with timing, success/error state,
+sanitized arguments, and a request ID for correlation. The sink is
+configured at startup via env var; when unset the sink is a no-op so the
+decorator costs nothing in the default case.
+
+Usage::
+
+    from node804_mcp_toolkit.audit import audit, open_sink
+
+    sink = open_sink({"PANOS_AUDIT_LOG": "/var/log/panos-audit.jsonl"})
+
+    @mcp.tool()
+    @audit(sink, category="READ", tool_name="get_security_rules")
+    async def get_security_rules(...): ...
+
+In practice the ModeGate.tool decorator from rbac.py composes the audit and
+gating decorators together, so most callers never invoke audit() directly.
+"""
+
+from __future__ import annotations
+
+import functools
+import os
+import sys
+import time
+import uuid
+from collections.abc import Awaitable, Callable, Mapping
+from pathlib import Path
+from typing import Any, Literal, Protocol, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+AuditCategory = Literal["READ", "WRITE", "ADMIN", "UNKNOWN"]
+
+
+class AuditEvent(BaseModel):
+    """One audit log line. Field names are stable across MCPs in the suite."""
+
+    ts: str = Field(description="ISO-8601 timestamp with millisecond precision, UTC")
+    request_id: str = Field(description="UUID4 — correlates one tool call across logs")
+    tool: str = Field(description="MCP tool name (e.g. get_security_rules)")
+    category: AuditCategory = Field(description="READ / WRITE / ADMIN / UNKNOWN")
+    mode: str = Field(description="Active permission mode at call time (e.g. 'read', 'admin')")
+    args: dict[str, Any] = Field(description="Sanitized tool arguments — sensitive keys redacted")
+    success: bool = Field(description="True for successful calls; False for handler errors")
+    duration_ms: int = Field(description="Wall-clock duration of the tool call")
+    error: str | None = Field(default=None, description="Error message when success=False")
+    extra: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Per-MCP optional fields (e.g. {'firewall': 'hq-fw'} for panos-mcp)",
+    )
+
+    model_config = ConfigDict(frozen=True)
+
+
+class AuditSink(Protocol):
+    """Protocol for audit destinations. Implement ``write`` to plug in a custom sink."""
+
+    enabled: bool
+
+    def write(self, event: AuditEvent) -> None: ...
+
+    def describe(self) -> str: ...
+
+
+class _NoopSink:
+    """Sink that drops events. Used when audit logging is unconfigured."""
+
+    enabled: bool = False
+
+    def write(self, event: AuditEvent) -> None:
+        return None
+
+    def describe(self) -> str:
+        return "disabled"
+
+
+class JsonlSink:
+    """Append-only JSON-lines sink writing to a single file path.
+
+    The path's parent directory is created on first use. Write failures
+    warn once to stderr and never raise — audit must not break tool calls.
+    """
+
+    enabled: bool = True
+
+    def __init__(self, path: Path) -> None:
+        self._path = path
+        self._warned = False
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+    def write(self, event: AuditEvent) -> None:
+        try:
+            with self._path.open("a", encoding="utf-8") as f:
+                f.write(event.model_dump_json() + "\n")
+        except OSError as err:
+            if not self._warned:
+                print(
+                    f"[node804-mcp-toolkit] WARNING: audit log write failed ({err}). "
+                    "Subsequent failures suppressed.",
+                    file=sys.stderr,
+                )
+                self._warned = True
+
+    def describe(self) -> str:
+        return f"enabled → {self._path}"
+
+
+def open_sink(
+    env: Mapping[str, str] | None = None,
+    *,
+    env_var: str = "MCP_AUDIT_LOG",
+) -> AuditSink:
+    """Open an audit sink based on environment.
+
+    Returns a :class:`JsonlSink` when ``env_var`` is set; otherwise a no-op
+    sink. Directory creation failures fall back to no-op with a stderr
+    warning rather than raising — audit should be best-effort.
+    """
+    e = env if env is not None else os.environ
+    raw = e.get(env_var, "").strip()
+    if not raw:
+        return _NoopSink()
+
+    path = Path(raw)
+    try:
+        return JsonlSink(path)
+    except OSError as err:
+        print(
+            f"[node804-mcp-toolkit] WARNING: could not initialize audit sink at '{raw}' ({err}). "
+            "Audit logging DISABLED.",
+            file=sys.stderr,
+        )
+        return _NoopSink()
+
+
+# --- Sanitization ---------------------------------------------------------
+
+DEFAULT_SENSITIVE_KEYS = frozenset(
+    {
+        "api_key",
+        "apikey",
+        "password",
+        "passwd",
+        "secret",
+        "token",
+        "auth",
+        "authorization",
+        "x-api-key",
+    }
+)
+"""Keys whose values are replaced with ``<redacted>`` regardless of nesting depth.
+
+The current schemas in this MCP suite don't accept any of these as tool arguments
+(api keys live in the keychain, not in tool params), but this is defense in depth —
+a future tool that inadvertently accepts one will not leak it to the audit log.
+"""
+
+DEFAULT_MAX_VALUE_LEN = 2048
+"""Strings longer than this are replaced with '<elided: N chars>' so a giant
+``set_config`` element doesn't blow a single audit line out to 100K+ chars."""
+
+
+def sanitize_args(
+    args: Any,
+    *,
+    sensitive_keys: frozenset[str] = DEFAULT_SENSITIVE_KEYS,
+    max_value_len: int = DEFAULT_MAX_VALUE_LEN,
+) -> dict[str, Any]:
+    """Deep-copy ``args`` with sensitive values redacted and long strings elided.
+
+    Returns ``{}`` when ``args`` is not a dict (audit log fields are typed
+    as ``dict[str, Any]`` for stability; a non-dict input usually means
+    "tool was called with no kwargs" which is fine).
+    """
+    if not isinstance(args, Mapping):
+        return {}
+    sanitized = _sanitize_value(args, sensitive_keys, max_value_len)
+    # _sanitize_value preserves dict-ness for dict inputs; cast for mypy.
+    assert isinstance(sanitized, dict)
+    return sanitized
+
+
+def _sanitize_value(
+    value: Any,
+    sensitive: frozenset[str],
+    max_len: int,
+) -> Any:
+    if isinstance(value, str):
+        if len(value) > max_len:
+            return f"<elided: {len(value)} chars>"
+        return value
+    if isinstance(value, (int, float, bool)) or value is None:
+        return value
+    if isinstance(value, Mapping):
+        out: dict[str, Any] = {}
+        for k, v in value.items():
+            if isinstance(k, str) and k.lower() in sensitive:
+                out[k] = "<redacted>"
+            else:
+                out[k] = _sanitize_value(v, sensitive, max_len)
+        return out
+    if isinstance(value, (list, tuple)):
+        return [_sanitize_value(item, sensitive, max_len) for item in value]
+    # bytes, sets, custom classes: stringify defensively rather than crash
+    return str(value)
+
+
+# --- Decorator ------------------------------------------------------------
+
+T = TypeVar("T")
+F = TypeVar("F", bound=Callable[..., Awaitable[Any]])
+
+
+def _now_iso() -> str:
+    """ISO-8601 with millisecond precision, UTC."""
+    # Build by hand because datetime.isoformat default is microsecond.
+    t = time.time()
+    ms = int((t - int(t)) * 1000)
+    return time.strftime("%Y-%m-%dT%H:%M:%S", time.gmtime(t)) + f".{ms:03d}Z"
+
+
+def audit(
+    sink: AuditSink,
+    *,
+    category: AuditCategory,
+    tool_name: str | None = None,
+    mode_provider: Callable[[], str] = lambda: "unknown",
+    extra_extractor: Callable[[dict[str, Any]], dict[str, Any]] | None = None,
+) -> Callable[[F], F]:
+    """Decorator that wraps an async tool handler with audit logging.
+
+    Parameters
+    ----------
+    sink
+        Where to write events. Use :func:`open_sink` to construct.
+    category
+        ``READ`` / ``WRITE`` / ``ADMIN`` — what the tool does at a high level.
+        Used for ``filter category=ADMIN`` in audit log analysis.
+    tool_name
+        MCP tool name. Defaults to the wrapped function's ``__name__``.
+    mode_provider
+        Callable returning the active permission mode string. Typically passed
+        ``lambda: gate.mode.value`` from rbac.ModeGate.
+    extra_extractor
+        Optional function ``(kwargs) -> dict`` that pulls per-MCP fields out
+        of the call kwargs into the event's ``extra`` field. For panos-mcp
+        this would extract ``firewall``; for freshservice-mcp, perhaps a
+        workspace identifier.
+    """
+
+    def decorator(func: F) -> F:
+        if not sink.enabled:
+            return func
+
+        name = tool_name or func.__name__
+
+        @functools.wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            start = time.monotonic()
+            request_id = str(uuid.uuid4())
+            success = False
+            error: str | None = None
+            try:
+                result = await func(*args, **kwargs)
+                # FastMCP tools that return {"error": "..."} should be recorded as failures.
+                if isinstance(result, Mapping) and isinstance(result.get("error"), str):
+                    error = result["error"]
+                    success = False
+                else:
+                    success = True
+                return result
+            except Exception as exc:
+                error = str(exc) or exc.__class__.__name__
+                raise
+            finally:
+                duration_ms = int((time.monotonic() - start) * 1000)
+                extra: dict[str, Any] = {}
+                if extra_extractor is not None:
+                    try:
+                        extra = extra_extractor(kwargs) or {}
+                    except Exception:
+                        extra = {}
+                event = AuditEvent(
+                    ts=_now_iso(),
+                    request_id=request_id,
+                    tool=name,
+                    category=category,
+                    mode=mode_provider(),
+                    args=sanitize_args(kwargs),
+                    success=success,
+                    duration_ms=duration_ms,
+                    error=error,
+                    extra=extra,
+                )
+                sink.write(event)
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+__all__ = [
+    "DEFAULT_MAX_VALUE_LEN",
+    "DEFAULT_SENSITIVE_KEYS",
+    "AuditCategory",
+    "AuditEvent",
+    "AuditSink",
+    "JsonlSink",
+    "audit",
+    "open_sink",
+    "sanitize_args",
+]

node804_mcp_toolkit/lean.py

@@ -0,0 +1,128 @@
+"""Pure response-shaping utilities for token-efficient MCP responses.
+
+Tools assemble their default response shape using these helpers — typically:
+
+1. :func:`strip_keys` to drop SDK internals (UUIDs, dirty-state flags) that
+   the AI never needs.
+2. :func:`whitelist` to keep only the fields the tool's default response
+   should expose, unless ``verbose=True`` is requested.
+3. :func:`filter_by_pattern` for server-side name filtering when the caller
+   passed a ``pattern`` arg.
+4. :func:`paginate` to enforce ``limit``/``offset`` before serializing.
+
+All functions are pure — no I/O, no global state, easy to test and compose.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Mapping
+from typing import Any, TypeVar
+
+
+def whitelist(
+    data: Mapping[str, Any] | Iterable[Mapping[str, Any]],
+    fields: Iterable[str],
+) -> dict[str, Any] | list[dict[str, Any]]:
+    """Keep only the listed top-level keys.
+
+    Accepts either a single dict or an iterable of dicts; returns the same
+    shape with non-listed keys removed. Field names that aren't present in
+    the input are silently skipped (so callers can pass a generous whitelist).
+
+    Nested dict values are passed through unchanged — whitelisting is
+    intentionally shallow because the field whitelist is per-tool and tools
+    that need nested filtering should compose multiple whitelist calls.
+    """
+    keep = set(fields)
+    if isinstance(data, Mapping):
+        return {k: v for k, v in data.items() if k in keep}
+    return [{k: v for k, v in item.items() if k in keep} for item in data]
+
+
+def strip_keys(
+    data: Any,
+    keys: Iterable[str],
+    *,
+    recursive: bool = True,
+) -> Any:
+    """Remove the listed keys from a dict (or list of dicts) at any depth.
+
+    Useful for stripping SDK internals like ``@_uuid``, ``@_dirtyId``,
+    ``@_loc`` that various XML responses include but the AI never reasons over.
+
+    Set ``recursive=False`` to only strip top-level keys (rare; useful when
+    the caller has already validated nested structure).
+    """
+    drop = set(keys)
+    return _strip(data, drop, recursive)
+
+
+def _strip(value: Any, drop: set[str], recursive: bool) -> Any:
+    if isinstance(value, dict):
+        out = {k: v for k, v in value.items() if k not in drop}
+        if recursive:
+            out = {k: _strip(v, drop, True) for k, v in out.items()}
+        return out
+    if recursive and isinstance(value, list):
+        return [_strip(item, drop, True) for item in value]
+    return value
+
+
+T = TypeVar("T")
+
+
+def paginate(items: list[T], limit: int, offset: int = 0) -> list[T]:
+    """Slice ``items[offset : offset + limit]``.
+
+    Returns an empty list when ``offset`` exceeds the list length, rather than
+    raising — pagination should be forgiving.
+    """
+    if offset < 0 or limit < 0:
+        raise ValueError("limit and offset must be non-negative")
+    return items[offset : offset + limit]
+
+
+def filter_by_pattern(
+    items: Iterable[Mapping[str, Any]],
+    pattern: str | None,
+    *,
+    name_field: str = "name",
+    case_sensitive: bool = False,
+    use_regex: bool = False,
+) -> list[Mapping[str, Any]]:
+    """Filter items by substring or regex on ``name_field``.
+
+    Default is case-insensitive substring matching, which is what the AI
+    typically wants ("find rules matching 'social'"). Set ``use_regex=True``
+    when the caller passed a regex; the regex compiles with the same case
+    flag as substring mode.
+
+    Items missing ``name_field`` are excluded (no implicit pass-through —
+    a missing name field signals the caller used the wrong filter on the
+    wrong list).
+    """
+    if not pattern:
+        return list(items)
+
+    if use_regex:
+        flags = 0 if case_sensitive else re.IGNORECASE
+        compiled = re.compile(pattern, flags)
+        return [
+            item for item in items
+            if isinstance(name := item.get(name_field), str) and compiled.search(name) is not None
+        ]
+
+    needle = pattern if case_sensitive else pattern.casefold()
+    out: list[Mapping[str, Any]] = []
+    for item in items:
+        name = item.get(name_field)
+        if not isinstance(name, str):
+            continue
+        haystack = name if case_sensitive else name.casefold()
+        if needle in haystack:
+            out.append(item)
+    return out
+
+
+__all__ = ["filter_by_pattern", "paginate", "strip_keys", "whitelist"]

node804_mcp_toolkit/params.py

@@ -0,0 +1,97 @@
+"""Shared Pydantic schemas for token-efficient MCP tool parameters.
+
+The point of this module is consistency across MCPs in the suite. Every tool
+that accepts a verbose flag, a field whitelist, pagination, or a pattern
+filter uses the same names, defaults, and descriptions. A user who learns
+``verbose`` / ``fields`` / ``limit`` / ``offset`` / ``pattern`` in one MCP
+finds the same conventions everywhere else.
+
+Usage in a FastMCP tool::
+
+    from node804_mcp_toolkit.params import VerboseFlag, FieldsList, Pagination, Pattern
+
+    @mcp.tool()
+    def get_security_rules(
+        verbose: VerboseFlag = False,
+        fields: FieldsList = None,
+        pagination: Pagination = Pagination(),
+        pattern: Pattern = None,
+    ) -> dict[str, Any]: ...
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import BaseModel, Field
+
+VerboseFlag = Annotated[
+    bool,
+    Field(
+        default=False,
+        description=(
+            "Return the full response from the underlying API. "
+            "Default false returns only the fields most relevant to the tool's purpose, "
+            "which typically reduces token use by 40-70%. "
+            "Set true when you need uncommon fields (UUIDs, audit timestamps, internal flags)."
+        ),
+    ),
+]
+"""Per-tool opt-in to full responses. Default false (lean)."""
+
+
+FieldsList = Annotated[
+    list[str] | None,
+    Field(
+        default=None,
+        description=(
+            "Optional explicit list of field names to include in the response. "
+            "Overrides the tool's default whitelist when set; takes precedence over verbose. "
+            "Use to project a small subset of fields when you know exactly what you need."
+        ),
+    ),
+]
+"""Per-tool field projection. Caller picks fields; bypasses default and verbose whitelists."""
+
+
+Pattern = Annotated[
+    str | None,
+    Field(
+        default=None,
+        description=(
+            "Optional case-insensitive substring filter applied server-side to the name field "
+            "of returned items. Returns only items whose name contains this substring. "
+            "Reduces token cost dramatically vs fetching the full inventory and filtering client-side."
+        ),
+    ),
+]
+"""Server-side substring filter on a name field. Reduces dump-and-filter patterns."""
+
+
+class Pagination(BaseModel):
+    """Pagination parameters for list-returning tools.
+
+    Defaults are tuned for token efficiency: a 100-item ceiling per call keeps
+    response size bounded for any inventory size. Callers paginate by
+    incrementing ``offset`` between calls when they need more.
+    """
+
+    limit: int = Field(
+        default=100,
+        ge=1,
+        le=1000,
+        description=(
+            "Maximum number of items to return. Default 100; max 1000. "
+            "Hard cap exists because dumping unbounded inventories can blow the AI's context window."
+        ),
+    )
+    offset: int = Field(
+        default=0,
+        ge=0,
+        description="Number of items to skip before returning. Use with limit to page through results.",
+    )
+
+    model_config = {"frozen": True}
+
+
+__all__ = ["FieldsList", "Pagination", "Pattern", "VerboseFlag"]

node804_mcp_toolkit/rbac.py

@@ -0,0 +1,262 @@
+"""Role-based access control for MCP tool registration.
+
+Each tool is decorated with a required :class:`Mode`. At decoration time
+(server startup), the :class:`ModeGate` checks whether the active mode (from
+env) meets the requirement. Tools that don't qualify are NOT registered
+with the MCP server, so the AI client never sees them — there's nothing
+to call.
+
+This is "default deny on misconfiguration": when ``PANOS_MODE`` is unset or
+holds an unrecognized value, the gate falls back to the lowest mode (``READ``).
+The operator must opt in to write capabilities explicitly.
+
+Usage::
+
+    from mcp.server.fastmcp import FastMCP
+    from node804_mcp_toolkit.rbac import Mode, ModeGate
+
+    mcp = FastMCP("panos-mcp")
+    gate = ModeGate.from_env(env_var="PANOS_MODE")
+
+    @gate.tool(mcp, required=Mode.READ)
+    async def get_security_rules(...): ...
+
+    @gate.tool(mcp, required=Mode.ADMIN)
+    async def commit(...): ...
+
+The ``gate.tool`` decorator composes :func:`audit` automatically when the
+gate is constructed with an ``audit_sink``::
+
+    sink = open_sink(env_var="PANOS_AUDIT_LOG")
+    gate = ModeGate.from_env(env_var="PANOS_MODE", audit_sink=sink)
+    # All gated tools now also emit audit events with no extra decorators.
+"""
+
+from __future__ import annotations
+
+import functools
+import os
+import sys
+from collections.abc import Awaitable, Callable, Mapping
+from enum import IntEnum
+from typing import Any, TypeVar
+
+from .audit import AuditCategory, AuditSink, audit
+
+F = TypeVar("F", bound=Callable[..., Awaitable[Any]])
+
+
+class Mode(IntEnum):
+    """Permission tier. Higher values include all capabilities of lower ones.
+
+    Modes are an integer enum so comparison is hierarchical out of the box::
+
+        if active_mode >= Mode.FULL: ...   # admin and full both pass
+    """
+
+    READ = 0
+    STANDARD = 1
+    FULL = 2
+    ADMIN = 3
+
+    @classmethod
+    def parse(cls, raw: str | None, *, default: Mode) -> Mode:
+        """Parse a string into a Mode, falling back to ``default`` on misses.
+
+        Accepts upper or lower case. Empty/None/unknown inputs return the
+        default — fail-safe to the most-restrictive mode usually.
+        """
+        if not raw:
+            return default
+        v = raw.strip().lower()
+        for m in cls:
+            if m.name.lower() == v:
+                return m
+        return default
+
+
+# Default audit category when one isn't supplied to gate.tool() — UNKNOWN
+# rather than READ so it's obviously something to fix in code review.
+_DEFAULT_AUDIT_CATEGORY: AuditCategory = "UNKNOWN"
+
+# Suggested mapping from Mode → AuditCategory when the caller doesn't override.
+_MODE_TO_CATEGORY: dict[Mode, AuditCategory] = {
+    Mode.READ: "READ",
+    Mode.STANDARD: "WRITE",
+    Mode.FULL: "WRITE",
+    Mode.ADMIN: "ADMIN",
+}
+
+
+class ModeGate:
+    """Holds the active mode and decorates tools with mode-gating + optional audit.
+
+    Construct with :meth:`from_env` to read the mode from environment, or
+    pass ``mode`` directly for tests. The instance keeps an internal map of
+    registered tools (``tool_name → required_mode``) populated as decorators
+    fire, which lets :meth:`summary` report exactly what's enabled at startup.
+    """
+
+    def __init__(
+        self,
+        *,
+        mode: Mode,
+        env_var: str,
+        audit_sink: AuditSink | None = None,
+    ) -> None:
+        self._mode = mode
+        self._env_var = env_var
+        self._audit_sink = audit_sink
+        # name → (required, category, registered)
+        # registered=False means the tool was decorated but didn't make the cut.
+        self._registry: dict[str, tuple[Mode, AuditCategory, bool]] = {}
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        env_var: str,
+        default: Mode = Mode.READ,
+        env: Mapping[str, str] | None = None,
+        audit_sink: AuditSink | None = None,
+        warn_on_invalid: bool = True,
+    ) -> ModeGate:
+        """Resolve the active mode from environment.
+
+        Reads ``env[env_var]``, parses to :class:`Mode`, falls back to
+        ``default`` on missing or unrecognized values. When the env var is
+        present but not a valid mode and ``warn_on_invalid=True``, prints
+        a one-time stderr warning so the misconfiguration is visible.
+        """
+        e = env if env is not None else os.environ
+        raw = e.get(env_var)
+        parsed = Mode.parse(raw, default=default)
+
+        # raw was set, didn't match any mode, fell back to default → warn
+        fell_back = (
+            bool(raw)
+            and parsed is default
+            and (raw or "").strip().lower() != default.name.lower()
+        )
+        if fell_back and warn_on_invalid:
+            valid = ", ".join(m.name.lower() for m in Mode)
+            print(
+                f"[node804-mcp-toolkit] WARNING: invalid {env_var}='{raw}'. "
+                f"Falling back to '{default.name.lower()}'. Valid modes: {valid}",
+                file=sys.stderr,
+            )
+
+        return cls(mode=parsed, env_var=env_var, audit_sink=audit_sink)
+
+    @property
+    def mode(self) -> Mode:
+        """The active permission mode."""
+        return self._mode
+
+    @property
+    def env_var(self) -> str:
+        """Name of the env var this gate reads from (e.g. ``PANOS_MODE``)."""
+        return self._env_var
+
+    def allows(self, required: Mode) -> bool:
+        """Return True when the active mode meets or exceeds ``required``."""
+        return self._mode >= required
+
+    def tool(
+        self,
+        mcp: Any,
+        *,
+        required: Mode,
+        category: AuditCategory | None = None,
+        tool_name: str | None = None,
+        extra_extractor: Callable[[dict[str, Any]], dict[str, Any]] | None = None,
+        **mcp_tool_kwargs: Any,
+    ) -> Callable[[F], F]:
+        """Decorator: register a tool only if ``required`` ≤ active mode.
+
+        When the gate denies, the function is recorded in the registry as
+        ``registered=False`` and returned unchanged (no MCP registration).
+        When the gate allows, the function is wrapped with audit (if a sink
+        was provided) and registered via ``mcp.tool(**mcp_tool_kwargs)``.
+
+        Parameters
+        ----------
+        mcp
+            The FastMCP server instance to register against.
+        required
+            Minimum mode level needed to expose this tool.
+        category
+            Audit category override. Defaults to a sensible value derived
+            from ``required`` (READ → READ, STANDARD/FULL → WRITE, ADMIN → ADMIN).
+        tool_name
+            Override for the tool's registered name. Defaults to ``func.__name__``.
+        extra_extractor
+            Forwarded to :func:`audit.audit` to pull MCP-specific fields
+            out of call kwargs into the event's ``extra`` field.
+        **mcp_tool_kwargs
+            Forwarded to ``mcp.tool()`` (e.g. ``description=...``).
+        """
+        cat = category if category is not None else _MODE_TO_CATEGORY.get(required, _DEFAULT_AUDIT_CATEGORY)
+
+        def decorator(func: F) -> F:
+            name = tool_name or func.__name__
+            allowed = self.allows(required)
+            self._registry[name] = (required, cat, allowed)
+
+            if not allowed:
+                # Don't register with MCP, don't wrap. The function still exists
+                # on the module, just isn't exposed as a tool.
+                return func
+
+            wrapped: F = func
+            if self._audit_sink is not None and self._audit_sink.enabled:
+                wrapped = audit(
+                    self._audit_sink,
+                    category=cat,
+                    tool_name=name,
+                    mode_provider=lambda: self._mode.name.lower(),
+                    extra_extractor=extra_extractor,
+                )(wrapped)
+
+            # FastMCP's tool() returns a decorator; passing name= explicitly
+            # so we use the override when present.
+            registered: F = mcp.tool(name=name, **mcp_tool_kwargs)(wrapped)
+            return registered
+
+        return decorator
+
+    @functools.cached_property
+    def all_known_tools(self) -> tuple[str, ...]:
+        """All tool names that have been decorated, in registration order."""
+        return tuple(self._registry.keys())
+
+    def summary(self) -> dict[str, Any]:
+        """Diagnostic snapshot for ``server_status`` tools and startup logs.
+
+        Returns counts, the active mode, and lists of enabled vs blocked tool
+        names. Stable shape across MCPs in the suite for cross-MCP tooling.
+        """
+        enabled = [name for name, (_, _, ok) in self._registry.items() if ok]
+        blocked = [name for name, (_, _, ok) in self._registry.items() if not ok]
+        return {
+            "mode": self._mode.name.lower(),
+            "env_var": self._env_var,
+            "tools_total": len(self._registry),
+            "tools_enabled": len(enabled),
+            "tools_blocked": len(blocked),
+            "enabled_tools": sorted(enabled),
+            "blocked_tools": sorted(blocked),
+            "audit": "enabled" if self._audit_sink and self._audit_sink.enabled else "disabled",
+        }
+
+    def describe(self) -> str:
+        """One-line stderr-friendly description for startup logs."""
+        s = self.summary()
+        return (
+            f"mode='{s['mode']}' "
+            f"({s['tools_enabled']}/{s['tools_total']} tools enabled, "
+            f"{s['tools_blocked']} blocked)"
+        )
+
+
+__all__ = ["Mode", "ModeGate"]

node804_mcp_toolkit/tls.py

@@ -0,0 +1,136 @@
+"""TLS verification config for MCP servers that talk to TLS endpoints directly.
+
+Verify-by-default with two opt-outs that match what enterprise IT environments
+actually need:
+
+- ``{PREFIX}_TLS_VERIFY=false`` to disable verification entirely. Emits a
+  one-time stderr warning so the choice is visible in logs.
+- ``{PREFIX}_TLS_CA=/path/to/ca.pem`` to load a custom CA bundle (typical for
+  internal-PKI-signed appliance certs). Setting this implies verify=true.
+
+The ``PREFIX`` is per-MCP, e.g. ``PANOS_TLS_VERIFY``, ``PRTG_TLS_VERIFY``,
+so users don't accidentally collide their settings across MCPs sharing a
+shell session.
+
+Most MCPs in the suite let their underlying SDK manage TLS internally
+(``pan-os-python``, FreshService's httpx client). This module exists for the
+ones that do raw httpx/requests calls — PRTG, Veeam, future direct REST
+clients.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class TlsConfig(BaseModel):
+    """Resolved TLS settings for an outbound HTTPS client."""
+
+    verify: bool = Field(
+        default=True,
+        description="Whether to verify the server certificate against the trust store.",
+    )
+    ca_path: Path | None = Field(
+        default=None,
+        description="Path to a PEM-encoded CA bundle to add to the trust store, if any.",
+    )
+    ca_bundle: bytes | None = Field(
+        default=None,
+        description="Loaded contents of ca_path, when readable. None if path missing or unreadable.",
+    )
+
+    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
+
+    @property
+    def description(self) -> str:
+        """Human-readable summary for startup logs."""
+        if not self.verify:
+            return "verify=OFF (disabled via env)"
+        if self.ca_bundle is not None:
+            return f"verify=ON (custom CA: {self.ca_path})"
+        return "verify=ON (system trust store)"
+
+
+_TRUTHY = frozenset({"true", "1", "yes", "on"})
+_FALSY = frozenset({"false", "0", "no", "off"})
+
+
+def _parse_bool(raw: str | None) -> bool | None:
+    """Parse an env-var string to bool with fail-safe semantics.
+
+    Returns None when the value is unrecognized so the caller can decide the
+    default. We never silently coerce a typo to False — that's how production
+    accidents happen.
+    """
+    if raw is None:
+        return None
+    v = raw.strip().lower()
+    if not v:
+        return None
+    if v in _TRUTHY:
+        return True
+    if v in _FALSY:
+        return False
+    return None
+
+
+def resolve_tls_config(
+    env: dict[str, str],
+    *,
+    prefix: str,
+    warn_on_disable: bool = True,
+) -> TlsConfig:
+    """Resolve TLS settings from environment.
+
+    Reads ``{PREFIX}_TLS_VERIFY`` (default true on missing/invalid) and
+    ``{PREFIX}_TLS_CA`` (optional PEM file path).
+
+    A CA bundle that fails to load (missing file, unreadable) warns to
+    stderr and falls back to the system trust store with verify still on.
+    Callers should treat this as a "soft failure" — the connection will
+    still attempt verification, just against the default trust store.
+
+    When verify is explicitly disabled and ``warn_on_disable=True``, prints
+    a one-time stderr warning so the operator sees the choice.
+    """
+    verify_var = f"{prefix}_TLS_VERIFY"
+    ca_var = f"{prefix}_TLS_CA"
+
+    explicit = _parse_bool(env.get(verify_var))
+    verify = True if explicit is None else explicit
+
+    ca_path: Path | None = None
+    ca_bundle: bytes | None = None
+    raw_path = env.get(ca_var, "").strip() or None
+    if raw_path:
+        ca_path = Path(raw_path)
+        try:
+            ca_bundle = ca_path.read_bytes()
+        except OSError as err:
+            print(
+                f"[node804-mcp-toolkit] WARNING: {ca_var}='{raw_path}' could not be read ({err}). "
+                "Falling back to system trust store.",
+                file=sys.stderr,
+            )
+            ca_bundle = None
+
+    if not verify and warn_on_disable:
+        print(
+            f"[node804-mcp-toolkit] WARNING: TLS certificate verification is DISABLED ({verify_var}=false). "
+            "Connections are vulnerable to man-in-the-middle attacks. "
+            f"Use {ca_var}=/path/to/ca.pem to trust an internal CA instead.",
+            file=sys.stderr,
+        )
+
+    return TlsConfig(verify=verify, ca_path=ca_path, ca_bundle=ca_bundle)
+
+
+def describe_tls(config: TlsConfig) -> str:
+    """One-line description for startup logs (delegates to TlsConfig.description)."""
+    return config.description
+
+
+__all__ = ["TlsConfig", "describe_tls", "resolve_tls_config"]

node804_mcp_toolkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: node804-mcp-toolkit
+Version: 0.1.0
+Summary: Shared utilities for token-efficient MCP servers — RBAC, audit logging, lean response shaping, TLS config
+Project-URL: Homepage, https://github.com/Node804/node804-mcp-toolkit
+Project-URL: Repository, https://github.com/Node804/node804-mcp-toolkit
+Project-URL: Issues, https://github.com/Node804/node804-mcp-toolkit/issues
+Author-email: Michael Pope <me@michaelpope.cv>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audit,mcp,model-context-protocol,rbac,tls
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.10.6
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# node804-mcp-toolkit
+
+[![CI](https://github.com/Node804/node804-mcp-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/Node804/node804-mcp-toolkit/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/node804-mcp-toolkit)](https://pypi.org/project/node804-mcp-toolkit/)
+[![Python](https://img.shields.io/pypi/pyversions/node804-mcp-toolkit)](https://pypi.org/project/node804-mcp-toolkit/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Shared utilities for building token-efficient, security-conscious [MCP](https://modelcontextprotocol.io) servers for IT operations. Provides the cross-cutting concerns every ops MCP needs — permission gating, audit logging, response shaping, TLS config — so each server in a suite implements them the same way.
+
+## Installation
+
+```bash
+pip install node804-mcp-toolkit
+```
+
+## What's in here
+
+| Module | Purpose |
+|---|---|
+| `rbac` | Hierarchical permission modes (`read` / `standard` / `full` / `admin`); a gate decorator that only registers tools with the MCP server when the active mode qualifies — ungated tools are invisible to the AI client, not just blocked |
+| `audit` | JSON-lines audit logging of every tool call with timing, success/error state, sensitive-key redaction, and long-value truncation |
+| `lean` | Pure response-shaping helpers: field whitelisting, internal-key stripping, pagination, server-side pattern filtering |
+| `tls` | Verify-by-default TLS config from env vars, with custom CA bundle support for internal PKI |
+| `params` | Shared Pydantic parameter types (`VerboseFlag`, `FieldsList`, `Pagination`, `Pattern`) so every tool uses the same names, defaults, and descriptions |
+
+## Quick start
+
+Gate tools by permission mode, with audit logging composed in:
+
+```python
+from mcp.server.fastmcp import FastMCP
+from node804_mcp_toolkit import Mode, ModeGate, open_sink
+
+mcp = FastMCP("panos-mcp")
+
+# Audit sink: writes JSONL when PANOS_AUDIT_LOG is set, no-op otherwise.
+sink = open_sink(env_var="PANOS_AUDIT_LOG")
+
+# Mode comes from env. Missing or invalid values fail safe to read-only.
+gate = ModeGate.from_env(env_var="PANOS_MODE", audit_sink=sink)
+
+@gate.tool(mcp, required=Mode.READ)
+async def get_security_rules(...): ...
+
+@gate.tool(mcp, required=Mode.ADMIN)
+async def commit(...): ...  # not registered at all unless PANOS_MODE=admin
+```
+
+Shape responses for token efficiency:
+
+```python
+from node804_mcp_toolkit import filter_by_pattern, paginate, strip_keys, whitelist
+
+rules = strip_keys(raw_rules, ["@uuid", "@loc"])          # drop SDK internals
+rules = filter_by_pattern(rules, pattern, name_field="name")
+rules = paginate(rules, limit=100, offset=0)
+rules = whitelist(rules, ["name", "action", "source", "destination"])
+```
+
+Resolve TLS settings from environment (verify-by-default):
+
+```python
+from node804_mcp_toolkit import resolve_tls_config
+import httpx, os
+
+tls = resolve_tls_config(dict(os.environ), prefix="PRTG")
+# PRTG_TLS_VERIFY=false  → verify off, with a loud stderr warning
+# PRTG_TLS_CA=/path.pem  → custom CA bundle for internal PKI
+client = httpx.Client(verify=str(tls.ca_path) if tls.ca_bundle else tls.verify)
+```
+
+## Design philosophy
+
+- **One toolkit, one set of patterns.** A user who learns the parameter conventions in any one MCP — `verbose`, `fields`, `limit`, `offset`, `pattern` — gets the same conventions in all of them.
+- **Default deny.** Unset or misconfigured mode env vars fall back to read-only. Tools above the active mode are never registered, so the AI client can't even see them.
+- **Token-lean by default.** Responses expose the fields the AI actually reasons over; `verbose=true` opts into the full payload.
+- **Best-effort observability.** Audit logging never breaks a tool call — sink failures warn once to stderr and move on.
+
+## Used by
+
+- [`node804-panos-mcp`](https://github.com/Node804) — Palo Alto firewall management
+- [`node804-freshservice-mcp`](https://github.com/Node804) — Freshservice ticketing
+- Planned: PRTG and Veeam MCPs
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+mypy src
+```
+
+Requires Python 3.11+. Fully typed (`py.typed` included), `mypy --strict` clean.
+
+## License
+
+[MIT](LICENSE)

node804_mcp_toolkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+node804_mcp_toolkit/__init__.py,sha256=7UUdbPIEaxYASi4LJM5pbht6fcbhDRDz4W1hl8kqpZw,951
+node804_mcp_toolkit/audit.py,sha256=l8RhknEUXIuTqZpq93-zFJVF3GcOccwAp2k9gNhqEps,10416
+node804_mcp_toolkit/lean.py,sha256=V03HgVZwQBp7aZABjyJSBoOhtuxPMS-Ndu19dMBel4g,4418
+node804_mcp_toolkit/params.py,sha256=3FX0629InyipVEQFogFrDZL5WRNjHqCcITFkqb8n83A,3195
+node804_mcp_toolkit/rbac.py,sha256=q3phtq8q8yW0VuXceppBmSEDgiux_l81hTpSiX4BJ14,9464
+node804_mcp_toolkit/tls.py,sha256=3Gl5EUJvX5SmNiAY4YxQupUUNPw4Z1kfX7nz-_zYGSo,4614
+node804_mcp_toolkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+node804_mcp_toolkit-0.1.0.dist-info/METADATA,sha256=WT1WKLnBD9iQgl1HcWrrR37gaY3tAzzVRtDT5L3ucO0,5584
+node804_mcp_toolkit-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+node804_mcp_toolkit-0.1.0.dist-info/licenses/LICENSE,sha256=MWZG7mvTKQAmF-bl5ZJ9VkzcpQy-ZPgzRoMe_rKekTc,1069
+node804_mcp_toolkit-0.1.0.dist-info/RECORD,,

node804_mcp_toolkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

node804_mcp_toolkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Pope
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.