Translate project to English + fix resource read handler

- All docstrings, comments, user-facing messages, prompts, error texts,
  README, .env.example, Dockerfile and CI workflow are now English-only.
  (Polish remains only in offline memory files outside the repo.)

- Fix: server resource handler compared the raw AnyUrl against a str,
  always falling through to "Unknown resource URI". MCP SDK passes
  pydantic AnyUrl objects; cast to str on entry.

- Add tests/test_resources_readable end-to-end probe so any future
  read_resource regression is caught (not just list_resources).

Verified: 13 tests pass (1 skipped — user-management 501 on this tenant),
ruff clean, Snyk clean, full MCP memory-transport smoke green,
Docker image builds and answers the MCP initialize handshake.

Author: Maciek

.env.example

@@ -1,25 +1,24 @@
-# ESET Connect API — dedykowane konto API (NIE zwykłe logowanie do panelu).
-# Utwórz w ESET PROTECT Hub / ESET Business Account → API users.
+# ESET Connect API — dedicated API user account (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
 
-# Tryb pracy MCP — niezależnie od uprawnień konta API.
-# RO  — rejestrowane są wszystkie tools, ale RW są blokowane przed wysłaniem requestu.
-# RW  — pełny dostęp; akcje destrukcyjne mają w MCP annotations destructiveHint=true.
+# MCP server operating mode — independent of the API account's permissions.
+# RO  — all tools are registered, but RW tools are blocked before the HTTP request.
+# RW  — full access; destructive tools carry destructiveHint=true in MCP annotations.
 ESET_MODE=RO
 
-# Region — decyduje o domenach API (eu/de/us/ca/jpn).
-# EU obsługuje większość klientów z PL.
+# Region — selects the API domains (eu/de/us/ca/jpn).
 ESET_REGION=eu
 
-# Transport MCP (opcjonalne; default: stdio).
-# stdio       — dla Claude Desktop / Claude Code (lokalnie, przez stdin/stdout).
-# http        — Streamable HTTP (najnowszy spec MCP 2025-11-25); wystawia HTTP endpoint.
+# MCP transport (optional; default: stdio).
+# stdio       — for Claude Desktop / Claude Code (local, stdin/stdout JSON-RPC).
+# http        — Streamable HTTP (MCP spec 2025-11-25); exposes an HTTP endpoint.
 ESET_MCP_TRANSPORT=stdio
 
-# Tylko przy ESET_MCP_TRANSPORT=http:
+# Only used when ESET_MCP_TRANSPORT=http:
 ESET_MCP_HTTP_HOST=127.0.0.1
 ESET_MCP_HTTP_PORT=8765
 
-# Opcjonalne: poziom logowania (DEBUG/INFO/WARNING/ERROR).
+# Optional logging level (DEBUG/INFO/WARNING/ERROR).
 ESET_LOG_LEVEL=INFO

.github/workflows/integration.yml

@@ -6,8 +6,8 @@ on:
   pull_request:
     branches: [main]
   schedule:
-    # Codzienne uruchomienie 03:17 UTC — wykrywa rozjazd MCP z ESET API
-    # (np. nowa wersja v3 endpointu pojawiająca się w Swaggerze).
+    # 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: {}
 
@@ -39,6 +39,6 @@ jobs:
           ESET_REGION: ${{ secrets.ESET_REGION || 'eu' }}
           ESET_MODE: RO
         run: |
-          # -m "not rw" — pomiń testy RW (konto w CI ma tylko RO).
-          # Testy z markerem `ro` + unit-testy bez markerów.
+          # -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

@@ -20,16 +20,16 @@ venv/
 htmlcov/
 .tox/
 
-# ───────── Editor / OS ─────────
+# ───────── Editors / OS ─────────
 .DS_Store
 .idea/
 .vscode/
 *.swp
 
-# ───────── Local-only docs (zbyt duże / copyright ESET) ─────────
+# ───────── Local-only docs (large / ESET copyright) ─────────
 eset_connect_enu.pdf
 eset_docs.txt
 
-# ───────── Logi ─────────
+# ───────── Logs ─────────
 *.log
 logs/

Dockerfile

@@ -8,15 +8,15 @@ ENV PYTHONDONTWRITEBYTECODE=1 \
 
 WORKDIR /app
 
-# Najpierw skopiuj pyproject (bez kodu) — lepsze cache layer'y dla deps.
+# Copy pyproject first (no source) — better layer caching for deps.
 COPY pyproject.toml README.md ./
 RUN pip install --upgrade pip setuptools wheel
 
-# Skopiuj resztę i zainstaluj paczkę (deps z pyproject).
+# Copy the rest and install the package (deps come from pyproject).
 COPY eset_mcp ./eset_mcp
 RUN pip install .
 
-# Default: stdio. Dla HTTP wystaw port (override w docker-compose).
+# 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

README.md

@@ -1,116 +1,121 @@
 # ESET-MCP
 
-Serwer [Model Context Protocol](https://modelcontextprotocol.io) (spec **2025-11-25**)
-opakowujący [ESET Connect API](https://help.eset.com/eset_connect/en-US/) jako zestaw
-tools, resources i prompts do użycia w Claude Desktop, Claude Code lub innym MCP host.
-
-- **102 tools** wygenerowane z 16 oficjalnych OpenAPI specs ESET Connect (`eu.esetconnect.eset.systems`)
-- **Dwa tryby pracy** niezależne od uprawnień konta API:
-  - `RO` — RW tools widoczne w katalogu, ale zablokowane przed dotknięciem sieci
-  - `RW` — pełny dostęp, z `destructiveHint: true` annotations dla MCP host
-- **Dwa transporty**: stdio (lokalnie) i Streamable HTTP (zdalnie, wg najnowszego MCP spec)
-- **OAuth2** z automatycznym refresh ~5min przed wygaśnięciem tokenu (1h validity)
-- **Pagination** (nextPageToken), **rate limit** retry (10 req/s + Fair Use), **202 polling** do 10 min
+A [Model Context Protocol](https://modelcontextprotocol.io) server (spec **2025-11-25**)
+wrapping the [ESET Connect API](https://help.eset.com/eset_connect/en-US/) as a set of
+tools, resources, and prompts usable from Claude Desktop, Claude Code, or any MCP host.
+
+- **102 tools** auto-generated from 16 official OpenAPI specs published at
+  `eu.esetconnect.eset.systems`
+- **Two operating modes** independent of the API account's permissions:
+  - `RO` — RW tools remain visible in the catalog but are blocked before touching the network
+  - `RW` — full access; mutating tools carry `destructiveHint: true` MCP annotations
+- **Two transports**: stdio (local) and Streamable HTTP (remote, per the latest MCP spec)
+- **OAuth2** with automatic token refresh ~5 min before expiry (tokens are valid for 1 h)
+- **Pagination** (nextPageToken), **rate-limit** retry (10 req/s + Fair Use Policy),
+  **202 polling** up to 10 minutes
 - **Multi-region**: eu / de / us / ca / jpn
 
 ## Quick start
 
-### 1. Konfiguracja
+### 1. Configure
 
 ```bash
 cp .env.example .env
-# uzupełnij ESET_USER / ESET_PASSWORD (dedykowane konto API, NIE logowanie do panelu)
-# ustaw ESET_REGION i ESET_MODE
+# Fill in ESET_USER / ESET_PASSWORD (a dedicated API user, NOT your console login).
+# Set ESET_REGION and ESET_MODE.
 ```
 
-### 2. Uruchomienie lokalne (stdio)
+### 2. Run locally (stdio)
 
 ```bash
 python -m venv .venv && source .venv/bin/activate
 pip install -e ".[dev]"
 eset-mcp
 ```
 
-### 3. Podpięcie do Claude Desktop / Claude Code
+### 3. Wire it up to Claude Desktop / Claude Code
 
 ```jsonc
 // claude_desktop_config.json
 {
   "mcpServers": {
     "eset": {
       "command": "/absolute/path/to/.venv/bin/eset-mcp",
-      "env": { /* opcjonalnie nadpisz cokolwiek z .env */ }
+      "env": { /* optionally override anything from .env */ }
     }
   }
 }
 ```
 
-### 4. Docker (HTTP, dla zdalnego deployu)
+### 4. Docker (HTTP transport, for remote deployment)
 
 ```bash
 docker compose up --build eset-mcp-http
 # MCP endpoint: http://localhost:8765/mcp
 ```
 
-stdio w kontenerze (jednorazowe wywołanie):
+One-off stdio invocation inside a container:
 ```bash
 docker compose run --rm eset-mcp-stdio
 ```
 
-## Architektura
+## Architecture
 
 ```
 eset_mcp/
-├── __main__.py        # entrypoint — wybór transportu (stdio / http)
+├── __main__.py        # entrypoint — picks a transport (stdio / http)
 ├── server.py          # MCP server (tools / resources / prompts)
-├── tools_loader.py    # generator tools z OpenAPI specs
+├── tools_loader.py    # generator: tools from OpenAPI specs
 ├── http_client.py     # async httpx + 202 polling + 429 retry + 401 refresh
-├── auth.py            # OAuth2 password grant, proaktywny refresh
-├── regions.py         # region → domeny per service
-├── modes.py           # RO/RW gate (rzuca przed wysłaniem requestu)
-├── errors.py          # mapowanie HTTP errors → user-friendly text dla agenta
-├── config.py          # ładowanie .env
-└── openapi/           # 16 OpenAPI 3.0.1 specs ESET Connect
+├── auth.py            # OAuth2 password grant, proactive refresh
+├── regions.py         # region → per-service domains
+├── modes.py           # RO/RW gate (raises before any HTTP request)
+├── errors.py          # HTTP error → agent-friendly text
+├── config.py          # .env loading
+└── openapi/           # 16 ESET Connect OpenAPI 3.0.1 specs
 ```
 
-## Tryby RO / RW
+## RO / RW modes
 
-Tryb wybiera się przez `ESET_MODE` w `.env`. **Niezależnie** od uprawnień konta API:
+The mode is chosen via `ESET_MODE` in `.env`. **Independent** of the API
+account's permissions:
 
-| `ESET_MODE` | Działanie |
+| `ESET_MODE` | Behaviour |
 |-------------|-----------|
-| `RO`        | RW tools są widoczne w katalogu (agent wie, że istnieją), ale `call_tool` na nich kończy się czytelnym komunikatem `Tool '...' wymaga trybu RW, a serwer MCP jest w trybie RO`. Żaden request HTTP nie wychodzi. |
-| `RW`        | RW tools działają. Każdy z nich w MCP annotations ma `destructiveHint: true` — MCP host (np. Claude) dostaje sygnał i może wymagać dodatkowego potwierdzenia. |
+| `RO`        | RW tools are visible in the catalog (the agent knows they exist), but `call_tool` on them returns a clear message `Tool '...' requires RW mode, but the MCP server is in RO mode`. No HTTP request goes out. |
+| `RW`        | RW tools run normally. Every one of them carries `destructiveHint: true` in MCP annotations — the MCP host (e.g. Claude) can use that signal to require extra confirmation. |
 
-Dodatkowo agent dostaje czytelne komunikaty błędów dla wszystkich HTTP error codes
-(401 / 403 / 429 / 5xx) — m.in. wskazówkę co sprawdzić w ESET PROTECT Hub przy 403.
+The server additionally surfaces agent-friendly messages for every HTTP error
+(401 / 403 / 429 / 5xx) — for instance, on 403 it suggests checking Permission
+Sets in ESET PROTECT Hub.
 
 ## MCP Resources
 
-- `eset://config/mode` — `RO` lub `RW`
-- `eset://config/region` — aktualny region
-- `eset://config/tools-catalog` — JSON-owy katalog wszystkich 102 tools (nazwa, mode, method, path, service, description)
-- `eset://docs/rate-limits` — przypomnienie o limitach 10 req/s
+- `eset://config/mode` — `RO` or `RW`
+- `eset://config/region` — current region
+- `eset://config/tools-catalog` — JSON catalog of all 102 tools (name, mode, method, path, service, description)
+- `eset://docs/rate-limits` — quick reminder about the 10 req/s ceiling
 
-## MCP Prompts (wbudowane recepty)
+## MCP Prompts (built-in recipes)
 
-- `audit_inactive_devices(days=30)` — kandydaci do offboardingu
-- `vulnerability_report` — raport CVE per device
-- `incident_triage` — otwarte incydenty + powiązane detekcje
+- `audit_inactive_devices(days=30)` — offboarding candidates
+- `vulnerability_report` — per-device CVE report
+- `incident_triage` — open incidents + related detections
 
-## Testy
+## Tests
 
 ```bash
-pytest                  # wszystko (RO smoke + unit catalog vs OpenAPI)
-pytest -m "not rw"      # tylko RO (default w CI)
-pytest -m rw            # RW (wymaga konta z uprawnieniami RW)
+pytest                  # everything (RO smoke + unit catalog vs OpenAPI)
+pytest -m "not rw"      # RO only (the default in CI)
+pytest -m rw            # RW (requires an account with RW permissions)
 ```
 
 CI workflow: [.github/workflows/integration.yml](.github/workflows/integration.yml) —
-puszcza się on-PR, on-push do `main` i raz dziennie (3:17 UTC). Cron-job
-łapie rozjazdy MCP z dokumentacją ESET (np. nowa wersja endpointu w Swaggerze).
+runs on PR, on push to `main`, and once a day at 03:17 UTC. The cron job
+catches drift between the MCP server and ESET's documentation (e.g. a new
+endpoint version appearing in Swagger).
 
-## Aktualizacja OpenAPI
+## Refreshing the OpenAPI specs
 
 ```bash
 cd eset_mcp/openapi
@@ -123,8 +128,9 @@ for name in business-account application-management asset-management automation
 done
 ```
 
-Po aktualizacji koniecznie puść testy — `test_catalog_vs_openapi.py` złapie nowe / zmienione operacje.
+Run the tests after an update — `test_catalog_vs_openapi.py` will flag any new
+or changed operations.
 
-## Licencja
+## License
 
 MIT

docker-compose.yml

@@ -1,5 +1,5 @@
 services:
-  # Tryb HTTP (Streamable HTTP, MCP spec 2025-11-25) — wystawia /mcp na 0.0.0.0:8765.
+  # HTTP mode (Streamable HTTP, MCP spec 2025-11-25) — exposes /mcp on 0.0.0.0:8765.
   eset-mcp-http:
     build: .
     container_name: eset-mcp-http
@@ -12,8 +12,8 @@ services:
     ports:
       - "8765:8765"
 
-  # Tryb stdio — uruchamiany ad-hoc do podłączenia jako lokalny serwer MCP
-  # (np. do Claude Desktop / Claude Code). Użyj:
+  # stdio mode — run on demand to attach as a local MCP server (e.g. from
+  # Claude Desktop / Claude Code):
   #   docker compose run --rm eset-mcp-stdio
   eset-mcp-stdio:
     build: .

eset_mcp/__init__.py

@@ -1,2 +1,2 @@
-"""ESET-MCP — serwer MCP dla ESET Connect API."""
+"""ESET-MCP — Model Context Protocol server for the ESET Connect API."""
 __version__ = "0.1.0"

eset_mcp/__main__.py

@@ -1,4 +1,4 @@
-"""Entrypoint serwera MCP — stdio albo Streamable HTTP."""
+"""Server entrypoint — stdio or Streamable HTTP transport."""
 from __future__ import annotations
 
 import asyncio
@@ -15,10 +15,10 @@ def main() -> None:
     logging.basicConfig(
         level=settings.log_level,
         format="%(asctime)s %(levelname)-7s %(name)s: %(message)s",
-        stream=sys.stderr,  # MCP stdio używa stdout do JSON-RPC — logi MUSZĄ iść do stderr.
+        stream=sys.stderr,  # MCP stdio uses stdout for JSON-RPC — logs MUST go to stderr.
     )
     log = logging.getLogger("eset_mcp")
-    log.info("ESET-MCP start — mode=%s region=%s transport=%s", settings.mode, settings.region, settings.transport)
+    log.info("ESET-MCP starting — mode=%s region=%s transport=%s", settings.mode, settings.region, settings.transport)
 
     asyncio.run(_run(settings))
 
@@ -32,7 +32,7 @@ async def _run(settings: Settings) -> None:
             async with stdio_server() as (read, write):
                 await server.run(read, write, server.create_initialization_options())
         elif settings.transport == "http":
-            # Streamable HTTP — najnowszy transport wg spec MCP 2025-11-25.
+            # Streamable HTTP — the current transport per MCP spec 2025-11-25.
             import uvicorn
             from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
             from starlette.applications import Starlette
@@ -45,7 +45,7 @@ async def _run(settings: Settings) -> None:
             )
             await uvicorn.Server(config).serve()
         else:
-            raise RuntimeError(f"Nieznany transport: {settings.transport!r}")
+            raise RuntimeError(f"Unknown transport: {settings.transport!r}")
 
 
 if __name__ == "__main__":

eset_mcp/auth.py

@@ -1,7 +1,7 @@
-"""OAuth2 password grant + automatyczny refresh.
+"""OAuth2 password grant + automatic token refresh.
 
-Token jest ważny 1h (docs ESET). Odświeżamy proaktywnie 5 min przed wygaśnięciem,
-żeby uniknąć race podczas long-running tool calls.
+The access token is valid for 1h (per ESET docs). We refresh proactively
+5 minutes before expiry to avoid a race during long-running tool calls.
 """
 from __future__ import annotations
 
@@ -15,7 +15,7 @@
 from .errors import map_http_error
 from .regions import auth_url
 
-# Bufor bezpieczeństwa — odśwież token N sekund przed nominalnym expiry.
+# Safety margin — refresh the token N seconds before its nominal expiry.
 _REFRESH_MARGIN_S = 300
 
 
@@ -30,7 +30,7 @@ def expired_or_expiring(self, margin: int = _REFRESH_MARGIN_S) -> bool:
 
 
 class TokenManager:
-    """Trzyma jeden token na proces serwera MCP. Odświeża proaktywnie i pod 401."""
+    """Holds a single token for the MCP server process; refreshes proactively and on 401."""
 
     def __init__(self, settings: Settings, http: httpx.AsyncClient):
         self._settings = settings
@@ -39,24 +39,24 @@ def __init__(self, settings: Settings, http: httpx.AsyncClient):
         self._lock = asyncio.Lock()
 
     async def get_access_token(self) -> str:
-        """Zwróć ważny access_token. Odśwież jeśli expired/expiring."""
+        """Return a valid access_token, refreshing it if expired or expiring soon."""
         async with self._lock:
             if self._token is None or self._token.expired_or_expiring():
                 await self._refresh_locked()
             assert self._token is not None
             return self._token.access_token
 
     async def force_refresh(self) -> str:
-        """Wymusza refresh — używamy po 401 z serwera."""
+        """Force a refresh — used after a 401 from the server."""
         async with self._lock:
             await self._refresh_locked()
             assert self._token is not None
             return self._token.access_token
 
     async def _refresh_locked(self) -> None:
-        """Wewnętrzne — wywołuj tylko przy nabytym _lock."""
-        # Jeśli mamy refresh_token i jeszcze nie wygasł całkiem, użyj go.
-        # Inaczej — od zera przez password grant.
+        """Internal — must be called while holding _lock."""
+        # If we have a refresh_token and it has not fully expired, use it.
+        # Otherwise — fall back to the password grant.
         if self._token and self._token.refresh_token and not self._token.expired_or_expiring(margin=0):
             data = {
                 "grant_type": "refresh_token",