Initial release: ESET Connect API MCP server (Python, MCP spec 2025-11-25)

A Model Context Protocol server wrapping the ESET Connect API as 106 tools,
4 resources and 3 prompts. Targets Claude Desktop, Claude Code, and any
MCP host speaking stdio or Streamable HTTP.

Highlights:

  • 102 tools auto-generated from 16 official OpenAPI 3.0.1 specs published
    by ESET (eu.esetconnect.eset.systems), covering every endpoint in their
    Connect gateway.

  • 4 hand-written high-level composites that fold 3-6 raw calls into one:
      - eset_search          — substring search across devices/users/policies/groups
      - device_full_profile  — device + detections + vulnerabilities + scans
      - incident_full_context — incident + comments + detections + devices
      - latest_detections    — newest detections, v2→v1 fallback, sorted by occurTime

  • RO / RW mode independent of the API account's permissions. In RO mode
    the server hides every RW tool from the catalog entirely (51 tools
    visible, down from 106), so the agent's context isn't wasted on
    things it can never call. An in-memory gate refuses RW tool names as
    defence in depth.

  • Two auth modes:
      - env   — credentials from .env (single tenant)
      - basic — Authorization: Basic header + X-ESET-Region per-request,
                so one MCP server can serve many ESET tenants
    Pool of credentials-bound HTTP clients keyed by (user, password_hash,
    region) — rotating a password mints a fresh OAuth token rather than
    reusing a stale one.

  • Streamable HTTP transport (per the November 2025 MCP spec) plus stdio.
    Production docker-compose profile launches Caddy with auto Let's Encrypt
    in front of an internally-bound MCP container.

  • Friendly errors: 401/403/429/5xx come back with operator-readable hints
    (e.g. on 403, "check Permission Sets in ESET PROTECT Hub").

  • Pagination, rate-limit retry (10 req/s + Fair Use), 202 long-polling
    (up to 10 min), proactive token refresh ~5 min before expiry.

  • 51 tests (RO smoke + unit + integration via MCP memory transport hitting
    the real tenant). Daily CI cron catches drift between the server and
    the official ESET OpenAPI specs.

Snyk clean, ruff clean.

Author: Maciek

.dockerignore

@@ -0,0 +1,19 @@
+.env
+.env.*
+!.env.example
+.git
+.gitignore
+.venv
+__pycache__
+*.pyc
+.pytest_cache
+.ruff_cache
+.mypy_cache
+.coverage
+htmlcov
+tests
+scripts
+eset_connect_enu.pdf
+eset_docs.txt
+test_eset_api.py
+.github

.env.example

@@ -0,0 +1,41 @@
+# ─── Auth mode ─────────────────────────────────────────────────────────────
+# env   — single tenant: ESET_USER/ESET_PASSWORD below are used for every
+#         request. Default. Works on both stdio and http transports.
+# basic — multi tenant: clients send `Authorization: Basic <base64(user:pw)>`
+#         (and optionally `X-ESET-Region`) on every request. Only valid with
+#         ESET_MCP_TRANSPORT=http. ESET_USER/ESET_PASSWORD below become optional.
+ESET_AUTH_MODE=env
+
+# ─── ESET API credentials (required when ESET_AUTH_MODE=env) ───────────────
+# Use a dedicated API user (NOT your regular console login). Create one in
+# ESET PROTECT Hub / ESET Business Account → API users.
+ESET_USER=api-user@yourdomain.tld
+ESET_PASSWORD=replace-me
+
+# ─── Server behaviour ───────────────────────────────────────────────────────
+# RO  — RW tools are visible but blocked before any HTTP request goes out.
+# RW  — full access; destructive tools carry destructiveHint=true in MCP annotations.
+ESET_MODE=RO
+
+# Default region for the API (eu/de/us/ca/jpn).
+# In basic-auth mode, clients can override this per-request with X-ESET-Region.
+ESET_REGION=eu
+
+# ─── MCP transport ─────────────────────────────────────────────────────────
+# stdio — for Claude Desktop / Claude Code (local stdin/stdout JSON-RPC).
+# http  — Streamable HTTP per MCP spec 2025-11-25; exposes an HTTP endpoint.
+ESET_MCP_TRANSPORT=stdio
+
+# Used only when ESET_MCP_TRANSPORT=http:
+ESET_MCP_HTTP_HOST=127.0.0.1
+ESET_MCP_HTTP_PORT=8765
+
+# ─── Optional logging level ────────────────────────────────────────────────
+ESET_LOG_LEVEL=INFO
+
+# ─── Production deployment (docker compose --profile prod) ─────────────────
+# Public domain Caddy will request a Let's Encrypt cert for. Must point at
+# the host running docker-compose. Only used by the `prod` profile.
+ESET_PUBLIC_DOMAIN=eset-mcp.example.com
+# Email Let's Encrypt uses for cert expiry notifications.
+ESET_ACME_EMAIL=ops@example.com

.github/workflows/integration.yml

@@ -0,0 +1,44 @@
+name: Integration tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    # Daily run at 03:17 UTC — catches drift between the MCP server and the
+    # ESET API (e.g. a new v3 endpoint appearing in Swagger).
+    - cron: "17 3 * * *"
+  workflow_dispatch: {}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check eset_mcp tests
+
+      - name: Run tests (RO only)
+        env:
+          ESET_USER: ${{ secrets.ESET_USER }}
+          ESET_PASSWORD: ${{ secrets.ESET_PASSWORD }}
+          ESET_REGION: ${{ secrets.ESET_REGION || 'eu' }}
+          ESET_MODE: RO
+        run: |
+          # -m "not rw" — skip RW-marked tests (CI's account is RO-only).
+          # Runs tests with the `ro` marker plus any unmarked tests.
+          pytest -v -m "not rw"

.gitignore

@@ -0,0 +1,38 @@
+# ───────── Secrets ─────────
+.env
+.env.local
+.env.*.local
+
+# ───────── Python ─────────
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.tox/
+
+# ───────── Editors / OS ─────────
+.DS_Store
+.idea/
+.vscode/
+*.swp
+
+# ───────── Local-only docs (large / ESET copyright) ─────────
+eset_connect_enu.pdf
+eset_docs.txt
+
+# ───────── Logs ─────────
+*.log
+logs/
+
+# ───────── Claude Code per-session worktrees (out of scope for the repo) ─────
+.claude/

Caddyfile

@@ -0,0 +1,38 @@
+# Caddy config for production deployment of ESET-MCP.
+#
+# Used only by the `prod` profile of docker-compose:
+#   docker compose --profile prod up -d
+#
+# Caddy fetches a Let's Encrypt cert for {$ESET_PUBLIC_DOMAIN} on first start
+# (HTTP-01 challenge on port 80) and serves the MCP server on HTTPS/443.
+# The MCP container itself only listens on the internal docker network — it
+# is never exposed to the outside world directly.
+
+{$ESET_PUBLIC_DOMAIN} {
+    # Let's Encrypt cert auto-provisioning.
+    tls {$ESET_ACME_EMAIL}
+
+    # Hard cap on request body — MCP messages are small.
+    request_body {
+        max_size 4MB
+    }
+
+    # Pass everything through to the MCP server (Streamable HTTP transport).
+    # The /mcp prefix is fixed by our Starlette Mount in eset_mcp/__main__.py.
+    reverse_proxy eset-mcp-http:8765 {
+        # Stream large/long-running responses (202-polled jobs etc).
+        flush_interval -1
+        # Forward client IP — used by ESET-MCP logs and (downstream) by ESET
+        # rate-limit accounting.
+        header_up X-Forwarded-For {remote_host}
+        header_up X-Forwarded-Proto {scheme}
+    }
+
+    encode gzip zstd
+
+    # Modest access log to stdout — let docker collect it.
+    log {
+        output stdout
+        format json
+    }
+}

Dockerfile

@@ -0,0 +1,30 @@
+# syntax=docker/dockerfile:1.6
+FROM python:3.13-slim AS base
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1
+
+WORKDIR /app
+
+# Copy pyproject first (no source) — better layer caching for deps.
+COPY pyproject.toml README.md ./
+RUN pip install --upgrade pip setuptools wheel
+
+# Copy the rest and install the package (deps come from pyproject).
+COPY eset_mcp ./eset_mcp
+RUN pip install .
+
+# Defaults: stdio. For HTTP, expose the port (override in docker-compose).
+ENV ESET_MCP_TRANSPORT=stdio \
+    ESET_MCP_HTTP_HOST=0.0.0.0 \
+    ESET_MCP_HTTP_PORT=8765
+
+EXPOSE 8765
+
+# Drop privileges.
+RUN useradd --create-home --uid 10001 esetmcp && chown -R esetmcp:esetmcp /app
+USER esetmcp
+
+ENTRYPOINT ["eset-mcp"]