feat: add deep health check and call_tool dev script (#100)

* feat: add deep health check and call_tool dev script

- helpers/health_probe.py: _run_deep_check() runs full MCP handshake
  and calls search_datasets(page_size=1) to validate end-to-end stack
- main.py: /health now returns 503 if probe fails, 200 if healthy
- tests/test_deep_health.py: @pytest.mark.deep_health, excluded from CI,
  run manually with: uv run pytest -m deep_health
- tests/test_health_endpoint.py: updated to accept 200 or 503
- scripts/call_tool.py: CLI helper, no more manual curl handshaking
- pyproject.toml: deep_health marker registered and excluded from CI

Closes #22

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* refactor: address review comments, extract mcp_client helper and drop deep naming

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: shahfazal

README.md

@@ -352,7 +352,7 @@ The MCP server is built using the [official Python SDK for MCP servers and clien
 
 **Streamable HTTP transport (standards-compliant):**
 - `POST /mcp` - JSON-RPC messages (client → server)
-- `GET /health` - Simple JSON health probe (`{"status":"ok","timestamp":"..."}`)
+- `GET /health` - Health check endpoint: runs a full MCP handshake and tool call. Returns `{"status":"ok",...}` with HTTP 200 if healthy, or `{"status":"mcp_unavailable"}` with HTTP 503 if the MCP stack is not responding correctly.
 
 ## 🛠️ Available Tools
 
@@ -442,6 +442,25 @@ uv run pytest -m stress
 
 Currently includes a test that mixes normal requests with abrupt client TCP disconnects, verifying the server stays healthy and keeps serving despite the disruption. It uses `MCP_PORT` (default: `8000`) to connect to the local server.
 
+### 🩺 Run a Health Check from the CLI
+
+Runs a full MCP handshake and calls `search_datasets` to validate end-to-end stack health. Requires a running server and is excluded from default `pytest` runs.
+
+```shell
+# Start the server first, then in another terminal:
+uv run pytest -m health_check
+```
+
+### 🛠️ Local Tool Testing Script
+
+`scripts/call_tool.py` lets you call any MCP tool directly without manually managing the curl handshake. Requires a running server.
+
+```shell
+# Start the server first, then in another terminal:
+python scripts/call_tool.py search_datasets '{"query": "IRVE"}'
+python scripts/call_tool.py get_resource_info '{"resource_id": "<id>"}'
+```
+
 ### 🔍 Interactive Testing with MCP Inspector
 
 Use the official [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) to interactively test the server tools and resources.

helpers/health_probe.py

@@ -0,0 +1,41 @@
+"""
+Health probe that runs a check on the MCP itself (doing a full handshake)
+and calls the `search_datasets` tool with page_size=1 for a full round-trip validation.
+
+Checks if the call response actually contains `data` for valid MCP response
+
+returns True if OK
+        False if round-trip failed (meaning the probe failed)
+"""
+
+import logging
+
+from mcp.types import TextContent
+
+from helpers.logging import MAIN_LOGGER_NAME
+from helpers.mcp_client import call_tool_on_mcp
+
+logger = logging.getLogger(MAIN_LOGGER_NAME)
+
+
+async def _run_health_check() -> bool:
+    logger.debug("health probe: starting health check")
+    try:
+        result = await call_tool_on_mcp(
+            "search_datasets", {"query": "transport", "page_size": 1}
+        )
+        # result.content is a list of content blocks from the tool response
+        # search_datasets always returns a TextContent block
+        # we check it's non-empty to confirm a valid round-trip
+        if not result.content or not isinstance(result.content[0], TextContent):
+            logger.error("health probe: unexpected response from search_datasets")
+            return False
+        if not result.content[0].text:
+            logger.error("health probe: empty response from search_datasets")
+            return False
+
+        return True
+
+    except Exception as e:
+        logger.error(f"health probe check failed: {e}")
+        return False

helpers/mcp_client.py

@@ -0,0 +1,21 @@
+"""
+Common helper to invoke an MCP tool call with the given params.
+"""
+
+import os
+
+from mcp.client.session import ClientSession
+from mcp.client.streamable_http import streamable_http_client
+from mcp.types import CallToolResult
+
+
+async def call_tool_on_mcp(tool_name: str, params: dict) -> CallToolResult:
+    port = os.getenv("MCP_PORT", "8000")
+    url = f"http://localhost:{port}/mcp"
+
+    async with streamable_http_client(url) as (read, write, _):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            result = await session.call_tool(tool_name, params)
+
+    return result

main.py

@@ -11,6 +11,7 @@
 from mcp.server.fastmcp import FastMCP
 from mcp.server.transport_security import TransportSecuritySettings
 
+from helpers.health_probe import _run_health_check
 from helpers.logging import MAIN_LOGGER_NAME, UVICORN_LOGGING_CONFIG
 from helpers.matomo import (
     apply_matomo_request_context,
@@ -74,21 +75,32 @@ async def app(scope, receive, send):
                 except PackageNotFoundError:
                     app_version = "unknown"
 
-                body = json.dumps(
-                    {
-                        "status": "ok",
-                        "uptime_since": SERVER_START_TIME.isoformat(),
-                        "version": app_version,
-                        "env": os.getenv("MCP_ENV", "unknown"),
-                        "data_env": os.getenv("DATAGOUV_API_ENV", "unknown"),
-                    }
-                ).encode("utf-8")
+                is_healthy = await _run_health_check()
+                if is_healthy:
+                    body = json.dumps(
+                        {
+                            "status": "ok",
+                            "uptime_since": SERVER_START_TIME.isoformat(),
+                            "version": app_version,
+                            "env": os.getenv("MCP_ENV", "unknown"),
+                            "data_env": os.getenv("DATAGOUV_API_ENV", "unknown"),
+                        }
+                    ).encode("utf-8")
+                    http_status = 200
+                else:
+                    body = json.dumps({"status": "mcp_unavailable"}).encode("utf-8")
+                    http_status = 503
+
                 headers = [
                     (b"content-type", b"application/json"),
                     (b"content-length", str(len(body)).encode("utf-8")),
                 ]
                 await send(
-                    {"type": "http.response.start", "status": 200, "headers": headers}
+                    {
+                        "type": "http.response.start",
+                        "status": http_status,
+                        "headers": headers,
+                    }
                 )
                 await send({"type": "http.response.body", "body": body})
                 return

pyproject.toml

@@ -37,5 +37,8 @@ testpaths = ["tests"]
 python_files = ["test_*.py"]
 python_classes = ["Test*"]
 python_functions = ["test_*"]
-markers = ["stress: stress tests requiring a running MCP server (not run by default)"]
-addopts = "-m 'not stress'"
+markers = [
+    "stress: stress tests requiring a running MCP server (not run by default)",
+    "health_check: health check requiring a running MCP server (not run by default)",
+]
+addopts = "-m 'not stress and not health_check'"

scripts/call_tool.py

@@ -0,0 +1,50 @@
+"""
+CLI helper to call any MCP tool without manual curl handshaking.
+
+Usage:
+    python scripts/call_tool.py <tool_name> '<json_args>'
+
+Example:
+    python scripts/call_tool.py search_datasets '{"query": "IRVE"}'
+    python scripts/call_tool.py get_resource_info '{"resource_id": "abc123"}'
+"""
+
+import asyncio
+import json
+import logging
+import sys
+
+from mcp.types import TextContent
+
+from helpers.logging import MAIN_LOGGER_NAME
+from helpers.mcp_client import call_tool_on_mcp
+
+logger = logging.getLogger(MAIN_LOGGER_NAME)
+
+
+async def call_tool(tool_name: str, args: dict) -> None:
+    """
+    Connect to MCP server and call a tool with given arguments.
+    """
+    logger.debug(f"Initiating tool call: {tool_name}")
+
+    result = await call_tool_on_mcp(tool_name, args)
+
+    if result.content and isinstance(result.content[0], TextContent):
+        print(result.content[0].text)
+    elif not result.content:
+        print(f"Error: empty response from tool '{tool_name}'", file=sys.stderr)
+    else:
+        print(
+            f"Error: unexpected content type from tool '{tool_name}': {type(result.content[0]).__name__}",
+            file=sys.stderr,
+        )
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: python scripts/call_tool.py <tool_name> '<json_args>'")
+        sys.exit(1)
+    tool = sys.argv[1]
+    arguments = json.loads(sys.argv[2]) if len(sys.argv) > 2 else {}
+    asyncio.run(call_tool(tool, arguments))

tests/test_health_check.py

@@ -0,0 +1,25 @@
+"""
+Health check: full MCP handshake + search_datasets tool call.
+
+Requires a running MCP server (not started by the test).
+Excluded from normal pytest runs -- launch explicitly with:
+
+    uv run pytest -m health_check
+"""
+
+import pytest
+
+from helpers.health_probe import _run_health_check
+
+pytestmark = pytest.mark.health_check
+
+
+async def test_health_check():
+    """
+    Runs the full MCP handshake and calls search_datasets with page_size=1.
+    Asserts a valid non-empty response to confirm end-to-end stack is healthy.
+    """
+    is_healthy = await _run_health_check()
+    assert is_healthy, (
+        "Health check failed: MCP handshake or tool call returned unexpected result"
+    )

tests/test_health_endpoint.py

@@ -5,16 +5,20 @@
 
 
 @pytest.mark.asyncio
-async def test_health_endpoint_returns_ok_status():
+async def test_health_endpoint_returns_valid_response():
     transport = ASGITransport(app=asgi_app)
     async with AsyncClient(transport=transport, base_url="http://testserver") as client:
         response = await client.get("/health")
 
-    assert response.status_code == 200
+    assert response.status_code in (200, 503)
     payload = response.json()
-    assert payload.get("status") == "ok"
-    assert "uptime_since" in payload
-    assert "version" in payload
-    assert isinstance(payload.get("version"), str)
-    assert "env" in payload
-    assert "data_env" in payload
+    assert "status" in payload
+    if response.status_code == 200:
+        assert payload["status"] == "ok"
+        assert "uptime_since" in payload
+        assert "version" in payload
+        assert isinstance(payload.get("version"), str)
+        assert "env" in payload
+        assert "data_env" in payload
+    else:
+        assert payload["status"] == "mcp_unavailable"