Merge pull request #10 from openapi/dev

Improve CI workflows and enhance API error logging

Author: francescobianco

.github/copilot-instructions.md

@@ -25,7 +25,6 @@ Common patterns and code examples
 Environment and runtime
 - Run locally: `python src/openapi_mcp_sdk/main.py` (README shows `python main.py` from project root; in this layout use the module path). The server binds to 0.0.0.0:PORT (reads `PORT` env var, default 80).
 - Virtualenv: repository uses `uv` in README but `pyproject.toml` shows `requires-python = ">=3.13"`. Note: README states Python 3.9+. If you modify runtime or CI, confirm the correct Python target.
-- Memcached configuration is read from `MEMCACHED_HOST`, `MEMCACHED_PORT`, and `X-DEV-VM`/`K_SERVICE` influence defaults. Tests or dev runs can run with a mocked `memory_store` (it falls back to in-process dict on Memcached errors).
 
 Developer workflows (concrete)
 - Start server (local):
@@ -42,7 +41,6 @@ Conventions and gotchas for agents
 - When adding a new API/tool module:
   - Follow the `@mcp.tool` decorator pattern and ensure the module is imported from `main.py` or otherwise registered during startup.
   - Prefer to call `make_api_call` for HTTP interactions so the common auth/header extraction is reused.
-- Beware `BASE_URL` / `callbackUrl` derivation in `memory_store.py` — it depends on `K_SERVICE` and `X-DEV-VM`. Tests running on CI may need to set these env vars.
 - The code expects `ctx` to contain `request_context.request.headers` in some places; use defensive checks when reading headers if you add new code paths.
 
 What I couldn't verify automatically

.github/workflows/build.yml

@@ -14,7 +14,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11"]
+        python-version: ["3.10", "3.11"]
 
     steps:
       - uses: actions/checkout@v4
@@ -30,9 +30,9 @@ jobs:
       - name: Lint with flake8
         run: |
           # stop the build if there are Python syntax errors or undefined names
-          flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+          flake8 src --count --select=E9,F63,F7,F82 --show-source --statistics
           # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
-          flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+          flake8 src --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
       - name: Test with pytest
         run: |
           pytest

.github/workflows/pylint.yml

@@ -1,4 +1,4 @@
-name: Pylint
+name: pylint
 
 on: [push]
 
@@ -20,4 +20,4 @@ jobs:
           pip install pylint
       - name: Analysing the code with pylint
         run: |
-          pylint $(git ls-files '*.py')
+          pylint $(git ls-files 'src/*.py')

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/apis/async_tool.py

@@ -1,16 +1,22 @@
+"""Async status tools."""
+
 import logging
-logging.getLogger(__name__).debug("module loaded")
-from fastmcp import Context
 from typing import Any
+
+from fastmcp import Context  # pylint: disable=import-error
+
 from ..mcp_core import mcp
 from ..memory_store import get_callback_result
 
 logger = logging.getLogger(__name__)
+logger.debug("module loaded")
+
 
 @mcp.tool
 async def check_async_status(request_id: str, ctx: Context) -> Any:
     """Show the last status of an async request
     Args:
         request_id: required, returned by an async downgraded request to the mcp server
     """
+    del ctx
     return get_callback_result(request_id)

src/openapi_mcp_sdk/apis/automotive.py

@@ -1,20 +1,37 @@
+"""Automotive tools."""
+
+# MCP tool names and parameter names intentionally mirror the public API.
+# pylint: disable=invalid-name,redefined-builtin
+
 import logging
-logging.getLogger(__name__).debug("module loaded")
-from fastmcp import Context
 from typing import Any
+
+from fastmcp import Context  # pylint: disable=import-error
+
 from ..mcp_core import make_api_call, mcp
 from ..memory_store import OPENAPI_HOST_PREFIX
 
 logger = logging.getLogger(__name__)
+logger.debug("module loaded")
+
 
 @mcp.tool
-async def check_license_plate(countryCode: str, type: str, licensePlate: str, ctx: Context) -> Any:
-    """Retrieve informations about type=car,bike,insurance,mot from a countryCode=IT,FR,UK,DE,PT,ES and a licensePlate.
-    Available Combinations: IT-car, IT-bike, IT-insurance,FR-car,FR-bike,UK-car,UK-bike,UK-mot,PT-car,PT-insurance,ES-car,ES-bike
+async def check_license_plate(
+    countryCode: str, type: str, licensePlate: str, ctx: Context
+) -> Any:
+    """Retrieve vehicle data for a supported country and plate.
+
+    Available combinations:
+    IT-car, IT-bike, IT-insurance, FR-car, FR-bike, UK-car, UK-bike,
+    UK-mot, PT-car, PT-insurance, ES-car, ES-bike.
+
     Args:
         countryCode: required, 2 digit country code (IT|FR|UK|DE|PT|ES)
         type: required, type of information needed (car|bike|insurance|mot)
         licensePlate: required, the license plate to check
     """
-    url = f"https://{OPENAPI_HOST_PREFIX}automotive.openapi.com/{countryCode}-{type}/{licensePlate}"
+    url = (
+        f"https://{OPENAPI_HOST_PREFIX}automotive.openapi.com/"
+        f"{countryCode}-{type}/{licensePlate}"
+    )
     return make_api_call(ctx, "GET", url)

src/openapi_mcp_sdk/apis/cap.py

@@ -1,11 +1,19 @@
+"""Italian postal code and municipality tools."""
+
+# MCP tool names and parameter names intentionally mirror the public API.
+# pylint: disable=invalid-name
+
 import logging
-logging.getLogger(__name__).debug("module loaded")
-from fastmcp import Context
 from typing import Any
+
+from fastmcp import Context  # pylint: disable=import-error
+
 from ..mcp_core import make_api_call, mcp
 from ..memory_store import OPENAPI_HOST_PREFIX
 
 logger = logging.getLogger(__name__)
+logger.debug("module loaded")
+
 
 @mcp.tool
 async def get_IT_regions_list(ctx: Context) -> Any:
@@ -15,6 +23,7 @@ async def get_IT_regions_list(ctx: Context) -> Any:
     url = f"https://{OPENAPI_HOST_PREFIX}cap.openapi.it/regioni"
     return make_api_call(ctx, "GET", url)
 
+
 @mcp.tool
 async def get_IT_provinces_list(ctx: Context) -> Any:
     """
@@ -23,6 +32,7 @@ async def get_IT_provinces_list(ctx: Context) -> Any:
     url = f"https://{OPENAPI_HOST_PREFIX}cap.openapi.it/province"
     return make_api_call(ctx, "GET", url)
 
+
 @mcp.tool
 async def get_IT_metropolitan_cities_list(ctx: Context) -> Any:
     """
@@ -31,6 +41,7 @@ async def get_IT_metropolitan_cities_list(ctx: Context) -> Any:
     url = f"https://{OPENAPI_HOST_PREFIX}cap.openapi.it/citta_metropolitane"
     return make_api_call(ctx, "GET", url)
 
+
 @mcp.tool
 async def get_suppressed_italian_municipalities(ctx: Context) -> Any:
     """
@@ -39,6 +50,7 @@ async def get_suppressed_italian_municipalities(ctx: Context) -> Any:
     url = f"https://{OPENAPI_HOST_PREFIX}cap.openapi.it/comuni_soppressi"
     return make_api_call(ctx, "GET", url)
 
+
 @mcp.tool
 async def find_IT_istat_by_comune_name(comune: str, ctx: Context) -> Any:
     """
@@ -48,6 +60,7 @@ async def find_IT_istat_by_comune_name(comune: str, ctx: Context) -> Any:
     params = {"comune": comune}
     return make_api_call(ctx, "GET", url, params=params)
 
+
 @mcp.tool
 async def find_IT_municipality_by_istat(istatCode: str, ctx: Context) -> Any:
     """
@@ -76,6 +89,7 @@ async def find_IT_municipality_by_istat(istatCode: str, ctx: Context) -> Any:
     url = f"https://{OPENAPI_HOST_PREFIX}cap.openapi.it/comuni_advance/{istatCode}"
     return make_api_call(ctx, "GET", url)
 
+
 @mcp.tool
 async def find_IT_municipalities_by_zip(zip_code: str, ctx: Context) -> Any:
     """