Refactor repo for Hugging Face Spaces compatibility

- Created root `app.py` as entry point initializing DB and launching Gradio with MCP.
- Updated `README.md` with HF Spaces YAML header and detailed instructions.
- Refactored `src/alert_mcp_server/tools.py` to use direct DB calls via `src.alert_mcp` instead of `httpx` HTTP requests, simplifying deployment.
- Updated `src/alert_mcp_server/app.py` to use relative imports.
- Updated tests to mock `mcp_tools` and verify Pydantic V2 compatibility.
- Created `requirements.txt` with pinned dependencies (`pydantic>=2.0`, `gradio[mcp]`).
- Ensured `__init__.py` files exist for package recognition.

README.md

@@ -1,127 +1,131 @@
-# CredentialWatch: Alert MCP Server
+---
+title: CredentialWatch Alert MCP
+emoji: 🩺
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+python_version: 3.11
+sdk_version: 6.0.0
+app_file: app.py
+fullWidth: true
+short_description: "Gradio MCP server for healthcare credential alerts."
+tags:
+  - mcp
+  - gradio
+  - tools
+  - healthcare
+pinned: false
+---
 
-## Overview
+# CredentialWatch Alert MCP Server
 
-CredentialWatch is a demo product for the **Hugging Face "MCP 1st Birthday / Gradio Agents Hackathon"**. It is designed to act as a unified, queryable view of provider credentials and a proactive alerting system for expirations (state licenses, board certs, DEA/CDS, etc.) in a US-style healthcare setting.
+Agent-ready Gradio Space that exposes healthcare credential alerts tools (log, view, resolve) over **Model Context Protocol (MCP)**.
 
-The system leverages:
--   **Model Context Protocol (MCP)** for standardized tool interfaces.
--   **LangGraph** for agentic workflows (sweeps, Q&A).
--   **Gradio** for the user interface.
--   **FastAPI & SQLite** for backend services and data persistence.
+## Hugging Face Space
 
-### System Architecture
+This repository is designed to run as a **Gradio Space**.
 
-The complete CredentialWatch system consists of three separate MCP servers:
-1.  **npi_mcp**: Read-only access to the public NPPES NPI Registry.
-2.  **cred_db_mcp**: Internal provider & credential database operations.
-3.  **alert_mcp** (This Repository): Alert logging, listing, and resolution.
+- SDK: Gradio (`sdk: gradio` in the README header)
+- Entry file: `app.py` (set via `app_file` in the YAML header)
+- Python: 3.11 (pinned with `python_version`)
 
-These servers interact with a **LangGraph Agent** and **Gradio UI** to provide a seamless experience for managing provider credentials and risks.
+When you push this repo to a Space with SDK = **Gradio**, the UI and the MCP server will be started automatically.
 
----
+## MCP Server
 
-## This Repository: `alert_mcp` & `alert_mcp_server`
+This Space exposes its tools via **Model Context Protocol (MCP)** using Gradio.
 
-This repository specifically houses the **Alert MCP** component, which includes:
+### How MCP is enabled
 
-1.  **`src/alert_mcp`**: A FastAPI backend service that manages the `alerts` table in a SQLite database. It provides endpoints to log alerts, retrieve open alerts, and mark them as resolved.
-2.  **`src/alert_mcp_server`**: A Gradio-based MCP server. It acts as a frontend/wrapper that exposes the alert capabilities as MCP tools (via SSE) and provides a simple web UI for testing and interaction.
+In `app.py` we:
 
-### Features
--   **Log Alert**: Create new alerts with severity levels (info, warning, critical).
--   **View Alerts**: Query open alerts, filtered by provider or severity.
--   **Resolve Alert**: Mark alerts as resolved with a note.
--   **Summarize**: Get a breakdown of alerts by severity.
--   **MCP Support**: Exposes these functions as MCP tools for agents to use.
+- initialize the database
+- launch the app with MCP support: `demo.launch(mcp_server=True)`
 
----
+### MCP endpoints
 
-## Prerequisites
+When the Space is running, Gradio exposes:
 
--   **Python 3.11**
--   **uv** (recommended for dependency management)
+- **MCP SSE endpoint**: `https://<space-host>/gradio_api/mcp/sse`
+- **MCP schema**: `https://<space-host>/gradio_api/mcp/schema`
 
-## Installation
+## Using this Space from an MCP client
 
-1.  **Clone the repository**:
-    ```bash
-    git clone <repo-url>
-    cd <repo-dir>
-    ```
+### Easiest: Hugging Face MCP Server (no manual config)
 
-2.  **Install dependencies**:
-    ```bash
-    uv sync
-    ```
-    Or using pip:
-    ```bash
-    pip install .
-    ```
+1. Go to your HF **MCP settings**: https://huggingface.co/settings/mcp
+2. Add this Space under **Spaces Tools** (look for the MCP badge on the Space).
+3. Restart your MCP client (VS Code, Cursor, Claude Code, etc.).
+4. The tools from this Space will appear as MCP tools and can be called directly.
 
-## Configuration
+### Manual config (generic MCP client using mcp-remote)
 
-The system uses environment variables for configuration. Create a `.env` file or set them in your environment:
+If your MCP client uses a JSON config, you can point it to the SSE endpoint via `mcp-remote`:
 
-```bash
-# src/alert_mcp_server/config.py
-ALERT_API_BASE_URL=http://localhost:8000  # URL of the backend alert_mcp service
-DB_FILE_PATH=/data/credentialwatch.db     # Path to SQLite DB (used by backend)
+```jsonc
+{
+  "mcpServers": {
+    "credentialwatch-alert": {
+      "command": "npx",
+      "args": [
+        "mcp-remote",
+        "https://<space-host>/gradio_api/mcp/sse"
+      ]
+    }
+  }
+}
 ```
 
-## Usage
+Replace `<space-host>` with the full URL of your Space.
 
-### 1. Run the Backend (`alert_mcp`)
-
-The backend service manages the database and API.
+## Local development
 
 ```bash
-uv run uvicorn src.alert_mcp.main:app --reload --port 8000
+# 1. Install deps
+uv pip install -r requirements.txt
+
+# 2. Run locally
+uv run python app.py
 ```
-This will start the FastAPI server at `http://localhost:8000`. It will automatically create the SQLite database at `DB_FILE_PATH` (defaulting to `./credentialwatch.db` or similar if not set).
 
-### 2. Run the Gradio MCP Server (`alert_mcp_server`)
+The local server will be available at http://127.0.0.1:7860, and MCP at http://127.0.0.1:7860/gradio_api/mcp/sse.
 
-The Gradio server connects to the backend and exposes the UI and MCP tools.
+## Deploying to Hugging Face Spaces
 
-```bash
-uv run python -m src.alert_mcp_server.main
-```
-This will launch the Gradio interface (usually at `http://localhost:7860`).
+1. Create a new Space with SDK = **Gradio**.
+2. Push this repo to the Space (Git or `huggingface_hub`).
+3. Ensure the YAML header in `README.md` is present and correct.
+4. Wait for the Space to build and start — it should show an **MCP badge** automatically.
 
-### Using with an MCP Client
+## Troubleshooting
 
-The `alert_mcp_server` exposes MCP tools via SSE (Server-Sent Events). An MCP-compatible agent (like the CredentialWatch LangGraph agent) can connect to this server to:
--   `log_alert(...)`
--   `get_open_alerts(...)`
--   `mark_alert_resolved(...)`
+- If the Space shows **Configuration error**, verify `sdk`, `app_file`, and `python_version` in the YAML header.
+- If the **MCP badge** doesn't appear, confirm `demo.launch(mcp_server=True)` is called in `app.py`.
+- Ensure `README.md` is at the root and not tracked by LFS.
 
-## Testing
+---
 
-Run the test suite using `pytest`:
+## Original Documentation
 
-```bash
-uv run pytest
-```
+### Overview
+
+CredentialWatch is a demo product for the **Hugging Face "MCP 1st Birthday / Gradio Agents Hackathon"**. It is designed to act as a unified, queryable view of provider credentials and a proactive alerting system.
+
+### Features
+-   **Log Alert**: Create new alerts with severity levels (info, warning, critical).
+-   **View Alerts**: Query open alerts, filtered by provider or severity.
+-   **Resolve Alert**: Mark alerts as resolved with a note.
+-   **Summarize**: Get a breakdown of alerts by severity.
+-   **MCP Support**: Exposes these functions as MCP tools for agents to use.
 
-## Project Structure
+### Project Structure
 
 ```
 .
+├── app.py                  # Entry point for HF Spaces
+├── requirements.txt        # Dependencies
 ├── src/
-│   ├── alert_mcp/          # FastAPI Backend & DB Models
-│   │   ├── main.py         # App entrypoint
-│   │   ├── models.py       # SQLAlchemy models (Alert)
-│   │   ├── db.py           # DB connection logic
-│   │   └── ...
-│   └── alert_mcp_server/   # Gradio UI & MCP Tool Wrapper
-│       ├── main.py         # Gradio app entrypoint
-│       ├── tools.py        # Client logic to talk to backend
-│       └── ...
-├── tests/                  # Test suite
-└── pyproject.toml          # Dependencies
+│   ├── alert_mcp/          # Backend logic & DB Models
+│   └── alert_mcp_server/   # Gradio UI & Tool Wrappers
+└── ...
 ```
-
-## License
-
-MIT

app.py

@@ -0,0 +1,17 @@
+import os
+import sys
+
+# Ensure the root directory is in the python path
+sys.path.append(os.path.dirname(os.path.abspath(__file__)))
+
+from src.alert_mcp.db import init_db
+from src.alert_mcp_server.app import create_demo
+
+# Initialize the database
+init_db()
+
+# Create and launch the demo
+demo = create_demo()
+
+if __name__ == "__main__":
+    demo.launch(mcp_server=True)

requirements.txt

@@ -0,0 +1,8 @@
+gradio[mcp]
+pydantic>=2.0
+python-dotenv
+mcp
+sqlalchemy
+fastapi
+uvicorn
+httpx

src/alert_mcp_server/app.py

@@ -1,5 +1,5 @@
 import gradio as gr
-from tools import log_alert, get_open_alerts, mark_alert_resolved, summarize_alerts
+from .tools import log_alert, get_open_alerts, mark_alert_resolved, summarize_alerts
 
 # Define the Gradio interface
 # We can use a TabbedInterface to organize the tools for the UI,

src/alert_mcp_server/tests/test_alert_mcp_server.py

@@ -1,104 +1,62 @@
-
 import pytest
-import httpx
-from unittest.mock import AsyncMock, MagicMock, patch
+from unittest.mock import MagicMock, patch
 from src.alert_mcp_server.tools import log_alert, get_open_alerts, mark_alert_resolved, summarize_alerts
 
-@pytest.mark.asyncio
-async def test_log_alert():
-    mock_response = {
-        "id": 1,
-        "provider_id": 1,
-        "severity": "info",
-        "message": "Test alert",
-        "created_at": "2023-10-27T10:00:00"
-    }
-
-    # We use new_callable=AsyncMock for the client.post method because it is awaited.
-    # However, the return value (the response object) should be a synchronous Mock (MagicMock)
-    # because methods like .json() and .raise_for_status() are synchronous on the Response object.
-    with patch("httpx.AsyncClient.post", new_callable=AsyncMock) as mock_post:
-        mock_response_obj = MagicMock()
-        mock_response_obj.status_code = 200
-        mock_response_obj.json.return_value = mock_response
-        mock_response_obj.raise_for_status.return_value = None
+@pytest.fixture
+def mock_db_session():
+    with patch("src.alert_mcp_server.tools.get_db") as mock_get_db:
+        mock_session = MagicMock()
+        mock_get_db.return_value = iter([mock_session])
+        yield mock_session
 
-        mock_post.return_value = mock_response_obj
+def test_log_alert(mock_db_session):
+    mock_alert_read = MagicMock()
+    # Mock model_dump return value
+    mock_alert_read.model_dump.return_value = {"id": 1, "provider_id": 1, "severity": "info", "message": "Test alert"}
 
-        result = await log_alert(
+    with patch("src.alert_mcp.mcp_tools.log_alert", return_value=mock_alert_read) as mock_log:
+        result = log_alert(
             provider_id=1,
             severity="info",
             window_days=30,
             message="Test alert"
         )
 
-        assert result == mock_response
-        mock_post.assert_called_once()
-        args, kwargs = mock_post.call_args
-        assert kwargs["json"]["provider_id"] == 1
-        assert kwargs["json"]["severity"] == "info"
-
-@pytest.mark.asyncio
-async def test_get_open_alerts():
-    mock_response = [
-        {
-            "id": 1,
-            "provider_id": 1,
-            "severity": "critical",
-            "message": "Critical alert",
-            "created_at": "2023-10-27T10:00:00"
-        }
-    ]
-
-    with patch("httpx.AsyncClient.get", new_callable=AsyncMock) as mock_get:
-        mock_response_obj = MagicMock()
-        mock_response_obj.status_code = 200
-        mock_response_obj.json.return_value = mock_response
-        mock_response_obj.raise_for_status.return_value = None
+        assert result["id"] == 1
+        mock_log.assert_called_once()
+        # Verify model_dump was called with mode='json'
+        mock_alert_read.model_dump.assert_called_with(mode='json')
 
-        mock_get.return_value = mock_response_obj
+def test_get_open_alerts(mock_db_session):
+    mock_alert_read = MagicMock()
+    mock_alert_read.model_dump.return_value = {"id": 1, "provider_id": 1, "severity": "critical"}
 
-        result = await get_open_alerts(provider_id=1)
+    with patch("src.alert_mcp.mcp_tools.get_open_alerts", return_value=[mock_alert_read]) as mock_get:
+        result = get_open_alerts(provider_id=1)
 
-        assert result == mock_response
+        assert len(result) == 1
+        assert result[0]["id"] == 1
         mock_get.assert_called_once()
-        args, kwargs = mock_get.call_args
-        assert kwargs["params"]["provider_id"] == 1
-
-@pytest.mark.asyncio
-async def test_mark_alert_resolved():
-    mock_response = {
-        "id": 1,
-        "resolved_at": "2023-10-27T12:00:00",
-        "resolution_note": "Fixed"
-    }
-
-    with patch("httpx.AsyncClient.post", new_callable=AsyncMock) as mock_post:
-        mock_response_obj = MagicMock()
-        mock_response_obj.status_code = 200
-        mock_response_obj.json.return_value = mock_response
-        mock_response_obj.raise_for_status.return_value = None
-
-        mock_post.return_value = mock_response_obj
-
-        result = await mark_alert_resolved(alert_id=1, resolution_note="Fixed")
+        mock_alert_read.model_dump.assert_called_with(mode='json')
 
-        assert result == mock_response
-        mock_post.assert_called_once()
+def test_mark_alert_resolved(mock_db_session):
+    mock_alert_read = MagicMock()
+    mock_alert_read.model_dump.return_value = {"id": 1, "resolved_at": "2023-10-27"}
 
-@pytest.mark.asyncio
-async def test_summarize_alerts():
-    mock_response = {"info": 5, "warning": 2, "critical": 1}
+    with patch("src.alert_mcp.mcp_tools.mark_alert_resolved", return_value=mock_alert_read) as mock_mark:
+        result = mark_alert_resolved(alert_id=1, resolution_note="Fixed")
 
-    with patch("httpx.AsyncClient.post", new_callable=AsyncMock) as mock_post:
-        mock_response_obj = MagicMock()
-        mock_response_obj.status_code = 200
-        mock_response_obj.json.return_value = mock_response
-        mock_response_obj.raise_for_status.return_value = None
+        assert result["id"] == 1
+        mock_mark.assert_called_once()
+        mock_alert_read.model_dump.assert_called_with(mode='json')
 
-        mock_post.return_value = mock_response_obj
+def test_summarize_alerts(mock_db_session):
+    mock_summary = MagicMock()
+    mock_summary.model_dump.return_value = {"total_alerts": 10, "by_severity": {"info": 5}}
 
-        result = await summarize_alerts(window_days=7)
+    with patch("src.alert_mcp.mcp_tools.summarize_alerts", return_value=mock_summary) as mock_sum:
+        result = summarize_alerts(window_days=7)
 
-        assert result == mock_response
-        mock_post.assert_called_once()
+        assert result["total_alerts"] == 10
+        mock_sum.assert_called_once()
+        mock_summary.model_dump.assert_called_with(mode='json')

src/alert_mcp_server/tools.py

@@ -1,15 +1,12 @@
-import httpx
+import json
 from typing import List, Optional, Dict, Any
-from config import ALERT_API_BASE_URL
-from schemas import AlertCreate, AlertRead, AlertResolution
+from src.alert_mcp.db import get_db
+from src.alert_mcp import mcp_tools
 
-# We'll use a synchronous client for simplicity in Gradio functions,
-# but Gradio supports async too. Let's use synchronous for now as it's often easier with Gradio tools.
-# Actually, httpx is great for async, but standard requests is often used.
-# Let's stick to httpx but use it synchronously or asynchronously depending on how we define the tools.
-# Gradio tools can be async def.
+# We use synchronous calls directly to the database logic
+# This avoids the need for a separate backend server process in the Space.
 
-async def log_alert(
+def log_alert(
     provider_id: int,
     severity: str,
     window_days: int,
@@ -28,32 +25,26 @@ async def log_alert(
         credential_id: Optional credential ID.
         channel: Notification channel (default: "ui").
     """
-    # Validation logic is handled by Pydantic model implicitly if we use it,
-    # but here we are constructing the payload.
-    # Basic validation for severity
-    if severity not in ["info", "warning", "critical"]:
-        raise ValueError("Severity must be one of: info, warning, critical")
+    db = next(get_db())
+    try:
+        alert = mcp_tools.log_alert(
+            db=db,
+            provider_id=provider_id,
+            credential_id=credential_id,
+            severity=severity,
+            window_days=window_days,
+            message=message,
+            channel=channel
+        )
+        return alert.model_dump(mode='json')
+    except ValueError as e:
+        return {"error": str(e)}
+    except Exception as e:
+        return {"error": f"An error occurred: {str(e)}"}
+    finally:
+        db.close()
 
-    payload = {
-        "provider_id": provider_id,
-        "credential_id": credential_id,
-        "severity": severity,
-        "window_days": window_days,
-        "message": message,
-        "channel": channel
-    }
-
-    async with httpx.AsyncClient(base_url=ALERT_API_BASE_URL) as client:
-        try:
-            response = await client.post("/alerts", json=payload)
-            response.raise_for_status()
-            return response.json()
-        except httpx.HTTPStatusError as e:
-            return {"error": f"HTTP error occurred: {e.response.status_code} - {e.response.text}"}
-        except Exception as e:
-            return {"error": f"An error occurred: {str(e)}"}
-
-async def get_open_alerts(
+def get_open_alerts(
     provider_id: Optional[int] = None,
     severity: Optional[str] = None
 ) -> List[Dict[str, Any]]:
@@ -64,30 +55,16 @@ async def get_open_alerts(
         provider_id: Optional filter by provider ID.
         severity: Optional filter by severity.
     """
-    params = {}
-    if provider_id is not None:
-        params["provider_id"] = provider_id
-    if severity is not None:
-        params["severity"] = severity
-
-    # Using POST /alerts/open with filters as per instructions, or GET if API supports params.
-    # Instruction says: "GET or POST to /alerts/open with filters."
-    # I'll try POST as it's more flexible for filters usually, or standard GET with query params.
-    # Let's assume POST for filters body if complex, or GET with query params.
-    # I will assume GET with query params first as it's standard for 'get', but the instruction says "GET or POST".
-    # I will implement as GET with query params for now.
+    db = next(get_db())
+    try:
+        alerts = mcp_tools.get_open_alerts(db=db, provider_id=provider_id, severity=severity)
+        return [a.model_dump(mode='json') for a in alerts]
+    except Exception as e:
+        return [{"error": str(e)}]
+    finally:
+        db.close()
 
-    async with httpx.AsyncClient(base_url=ALERT_API_BASE_URL) as client:
-        try:
-            response = await client.get("/alerts/open", params=params)
-            response.raise_for_status()
-            return response.json()
-        except httpx.HTTPStatusError as e:
-            return [{"error": f"HTTP error: {e.response.status_code}"}]
-        except Exception as e:
-            return [{"error": str(e)}]
-
-async def mark_alert_resolved(
+def mark_alert_resolved(
     alert_id: int,
     resolution_note: Optional[str] = None
 ) -> Dict[str, Any]:
@@ -98,35 +75,29 @@ async def mark_alert_resolved(
         alert_id: The ID of the alert to resolve.
         resolution_note: A note explaining the resolution.
     """
-    payload = {"resolution_note": resolution_note}
-
-    async with httpx.AsyncClient(base_url=ALERT_API_BASE_URL) as client:
-        try:
-            response = await client.post(f"/alerts/{alert_id}/resolve", json=payload)
-            response.raise_for_status()
-            return response.json()
-        except httpx.HTTPStatusError as e:
-            return {"error": f"HTTP error: {e.response.status_code}"}
-        except Exception as e:
-            return {"error": str(e)}
+    db = next(get_db())
+    try:
+        alert = mcp_tools.mark_alert_resolved(db=db, alert_id=alert_id, resolution_note=resolution_note)
+        return alert.model_dump(mode='json')
+    except ValueError as e:
+        return {"error": str(e)}
+    except Exception as e:
+        return {"error": str(e)}
+    finally:
+        db.close()
 
-async def summarize_alerts(window_days: Optional[int] = None) -> Dict[str, int]:
+def summarize_alerts(window_days: Optional[int] = None) -> Dict[str, Any]:
     """
     Get a summary of alerts (counts by severity).
 
     Args:
         window_days: Optional window in days to summarize over.
     """
-    payload = {}
-    if window_days is not None:
-        payload["window_days"] = window_days
-
-    async with httpx.AsyncClient(base_url=ALERT_API_BASE_URL) as client:
-        try:
-            response = await client.post("/alerts/summary", json=payload)
-            response.raise_for_status()
-            return response.json()
-        except httpx.HTTPStatusError as e:
-            return {"error": f"HTTP error: {e.response.status_code}"}
-        except Exception as e:
-            return {"error": str(e)}
+    db = next(get_db())
+    try:
+        summary = mcp_tools.summarize_alerts(db=db, window_days=window_days)
+        return summary.model_dump(mode='json')
+    except Exception as e:
+        return {"error": str(e)}
+    finally:
+        db.close()