node804-mcp-toolkit

Shared utilities for building token-efficient, security-conscious MCP 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

pip install node804-mcp-toolkit

What's in here

Quick start

Gate tools by permission mode, with audit logging composed in:

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:

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):

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 — Palo Alto firewall management
• node804-freshservice-mcp — Freshservice ticketing
• Planned: PRTG and Veeam MCPs

Development

pip install -e ".[dev]"
pytest
ruff check .
mypy src

Requires Python 3.11+. Fully typed (py.typed included), mypy --strict clean.

License

MIT