feat(dev): improve api error logs and autoreload start

Author: francescobianco

Makefile

@@ -38,6 +38,8 @@
 UV          := uv
 HOST        := 0.0.0.0
 MCP_PORT    := 8080
+MCP_ENV     ?= dev
+DEV_MODE    ?= 1
 NGROK_DOMAIN ?=
 
 ## =======
@@ -60,7 +62,7 @@ check-env:
 ## Setup the local environment and start the server (exposes a public ngrok URL if ngrok is installed)
 ## Set NGROK_DOMAIN=your-name.ngrok-free.app for a stable URL across restarts.
 start: check-env .install.stamp
-	@MCP_PORT=$(MCP_PORT) HOST=$(HOST) NGROK_DOMAIN=$(NGROK_DOMAIN) bash scripts/start.sh
+	@MCP_PORT=$(MCP_PORT) HOST=$(HOST) MCP_ENV=$(MCP_ENV) DEV_MODE=$(DEV_MODE) NGROK_DOMAIN=$(NGROK_DOMAIN) bash scripts/start.sh
 
 ## Start local MCP server and open Claude interactively - production (requires: export OPENAPI_TOKEN=your_token)
 try-claude: check-env .install.stamp

scripts/start.sh

@@ -2,6 +2,7 @@
 # Start the MCP server and expose it publicly via ngrok (if installed).
 # Usage: bash scripts/start.sh
 # Env:   MCP_PORT (default 8080), HOST (default 0.0.0.0)
+#        MCP_ENV (default dev), DEV_MODE (default 1)
 #        NGROK_DOMAIN — set to your reserved ngrok static domain to get a
 #                       stable URL that never changes across restarts.
 #                       Claim your free static domain at:
@@ -13,6 +14,8 @@ set -uo pipefail
 
 MCP_PORT="${MCP_PORT:-8080}"
 HOST="${HOST:-0.0.0.0}"
+MCP_ENV="${MCP_ENV:-dev}"
+DEV_MODE="${DEV_MODE:-1}"
 NGROK_DOMAIN="${NGROK_DOMAIN:-}"
 
 SERVER_PID=""
@@ -25,12 +28,34 @@ cleanup() {
 }
 trap cleanup EXIT INT TERM
 
-# ── clear Python bytecode cache so edited sources are always reloaded ──────
-find src/ -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+clear_python_cache() {
+    find src/ -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+}
+
+start_server() {
+    clear_python_cache
+    PYTHONPATH=src MCP_ENV="$MCP_ENV" \
+        uv run uvicorn openapi_mcp_sdk.main:app \
+        --host "$HOST" \
+        --port "$MCP_PORT" \
+        --log-config scripts/log_config.json &
+    SERVER_PID=$!
+}
+
+stop_server() {
+    [ -n "$SERVER_PID" ] && kill "$SERVER_PID" 2>/dev/null || true
+    wait "$SERVER_PID" 2>/dev/null || true
+    SERVER_PID=""
+}
+
+snapshot_sources() {
+    find src tests scripts -type f \( -name '*.py' -o -name '*.php' \) -print0 2>/dev/null \
+        | sort -z \
+        | xargs -0 stat -c '%n:%Y' 2>/dev/null
+}
 
 # ── start uvicorn ──────────────────────────────────────────────────────────
-PYTHONPATH=src uv run uvicorn openapi_mcp_sdk.main:app --host "$HOST" --port "$MCP_PORT" --log-config scripts/log_config.json &
-SERVER_PID=$!
+start_server
 
 # ── wait for server to accept connections ──────────────────────────────────
 printf "Waiting for server\n"
@@ -97,4 +122,30 @@ else
     echo "Check the dashboard at http://localhost:4040"
 fi
 
-wait "$SERVER_PID" 2>/dev/null || true
+if [ "$DEV_MODE" != "1" ]; then
+    wait "$SERVER_PID" 2>/dev/null || true
+    exit 0
+fi
+
+echo "dev mode enabled (MCP_ENV=${MCP_ENV})"
+echo "watching *.py and *.php for changes"
+
+LAST_SNAPSHOT="$(snapshot_sources)"
+while true; do
+    sleep 1
+
+    if [ -n "$SERVER_PID" ] && ! kill -0 "$SERVER_PID" 2>/dev/null; then
+        echo "server exited, restarting..."
+        start_server
+        LAST_SNAPSHOT="$(snapshot_sources)"
+        continue
+    fi
+
+    CURRENT_SNAPSHOT="$(snapshot_sources)"
+    if [ "$CURRENT_SNAPSHOT" != "$LAST_SNAPSHOT" ]; then
+        echo "source change detected, restarting server..."
+        stop_server
+        start_server
+        LAST_SNAPSHOT="$CURRENT_SNAPSHOT"
+    fi
+done

src/openapi_mcp_sdk/mcp_core.py

@@ -13,6 +13,49 @@
 
 logger = logging.getLogger(__name__)
 
+
+def _log_api_event(
+    tag: str,
+    client_ip: str,
+    action: str,
+    path: str,
+    reason: Optional[str] = None,
+) -> None:
+    if reason:
+        logger.info('%s %s "%s %s (%s)"', tag, client_ip, action, path, reason)
+        return
+    logger.info('%s %s "%s %s"', tag, client_ip, action, path)
+
+
+def _describe_http_error(error: requests.exceptions.HTTPError) -> str:
+    response = error.response
+    if response is None:
+        return "api error"
+
+    reason_parts = [f"api {response.status_code}"]
+    if response.reason:
+        reason_parts.append(str(response.reason).lower())
+
+    try:
+        payload = response.json()
+    except ValueError:
+        payload = None
+
+    if isinstance(payload, dict):
+        detail = payload.get("message") or payload.get("error")
+        if detail:
+            reason_parts.append(str(detail).strip())
+
+    return " - ".join(reason_parts)
+
+
+def _describe_request_exception(error: requests.exceptions.RequestException) -> str:
+    if isinstance(error, requests.exceptions.Timeout):
+        return "timeout"
+    if isinstance(error, requests.exceptions.ConnectionError):
+        return "connection failed"
+    return str(error).strip() or "request failed"
+
 # Create the MCP server instance
 mcp = FastMCP(
     name="Openapi.com MCP Gateway",
@@ -74,7 +117,6 @@ def make_api_call(ctx: Context, method: str, url: str, json_payload: Optional[di
     except Exception:
         client_ip = "?"
     tag = f"[{service}]"
-    logger.info('%s %s "%s %s"', tag, client_ip, method, parsed.path)
     # Attempt to retrieve the Authorization header from multiple sources
     try:
         auth_header = None
@@ -104,8 +146,10 @@ def make_api_call(ctx: Context, method: str, url: str, json_payload: Optional[di
             raise ValueError("Missing or malformed Header 'Authorization: Bearer <token>'.")
 
     except Exception as e:
+        _log_api_event(tag, client_ip, "ERROR", parsed.path, "token mancante")
         return ApiError(error="Auth Error", message=f"Missing Token from client: {e}").model_dump()
 
+    _log_api_event(tag, client_ip, method, parsed.path)
     headers = {"Authorization": auth_header, **kwargs.pop("headers", {})}
     try:
         request_args = dict(method=method, url=url, headers=headers, **kwargs)
@@ -126,8 +170,22 @@ def make_api_call(ctx: Context, method: str, url: str, json_payload: Optional[di
             return return_data
         return response_data
     except requests.exceptions.HTTPError as e:
+        _log_api_event(
+            tag,
+            client_ip,
+            "ERROR",
+            parsed.path,
+            _describe_http_error(e),
+        )
         error_details = e.response.text
         return e.response.json()
         return ApiError(error="API HTTP Error", message=f"{e.response.status_code}: {error_details}").model_dump()
     except requests.exceptions.RequestException as e:
+        _log_api_event(
+            tag,
+            client_ip,
+            "ERROR",
+            parsed.path,
+            _describe_request_exception(e),
+        )
         return ApiError(error="API Request Error", message=str(e)).model_dump()