Update README.md with CredentialWatch system context and fix tests

- Updated `README.md` to describe the full CredentialWatch architecture, including the 3 MCP servers, LangGraph agent, and Modal backend.
- Detailed the role of `cred_db_mcp_server` and its exposed tools.
- Added clear instructions for installation, configuration, and running with `uv`.
- Deleted obsolete `tests/test_cred_db_mcp.py` which referenced non-existent local models.
- Verified `tests/test_cred_db_mcp_server.py` passes and correctly mocks backend interactions.
- Added `pytest` as a dev dependency in `pyproject.toml`.

README.md

@@ -1,48 +1,124 @@
+# CredentialWatch
 
-# Usage of cred_db_mcp
+**CredentialWatch** is a proactive healthcare credential management system built for the **Hugging Face MCP 1st Birthday / Gradio Agents Hackathon**. It leverages the **Model Context Protocol (MCP)**, **LangGraph** agents, **Gradio**, and **Modal** to unify fragmented credential data and alert on upcoming expiries.
 
-This server provides direct database access and logic for **CredentialWatch** via MCP-compliant tools exposed as HTTP endpoints.
+## 🎯 Project Goal
 
-## Agents Usage
+CredentialWatch transforms messy, decentralized provider data (state licenses, board certifications, DEA numbers) into:
+1.  **A unified, queryable source of truth.**
+2.  **A proactive alerting system** for at-risk credentials.
 
-Agents can use this server to:
-1.  **Onboard new providers**: Call `sync_provider_from_npi` to fetch details from the NPI registry and create a local record.
-2.  **Manage Credentials**: Use `add_or_update_credential` to keep license data up to date.
-3.  **Monitor Compliance**: Use `list_expiring_credentials` to proactively find providers who need to renew licenses.
-4.  **Context Retrieval**: Use `get_provider_snapshot` to get all known data about a provider before answering user questions.
+The system is designed to solve the real-world problem of missed credential expiries leading to compliance issues, denied claims, and scheduling conflicts.
 
-## Running the Server
+## 🧩 Architecture
 
-```bash
-# Install dependencies
-pip install -e .
+The system follows a microservice-like architecture with strict separation of concerns, orchestrated by a LangGraph agent.
+
+### Components
+
+1.  **Agent UI (Gradio + LangGraph)**: The user interface where users interact with the agent (chat or sweep triggers).
+2.  **Three MCP Servers**:
+    *   **`npi_mcp`**: Read-only access to the public NPPES NPI Registry.
+    *   **`cred_db_mcp`**: (Hosted in this repo) Internal provider & credential database operations.
+    *   **`alert_mcp`**: Alert logging and resolution management.
+3.  **Modal Backend**: Hosting FastAPI microservices and the SQLite database (`credentialwatch.db`).
+
+### Data Flow
+
+```
+User <-> Gradio UI <-> LangGraph Agent
+                            |
+           -----------------------------------
+           |                |                |
+      [npi_mcp]      [cred_db_mcp]     [alert_mcp]
+           |                |                |
+      (NPI_API)        (CRED_API)       (ALERT_API)
+           |                |                |
+        NPPES         [SQLite DB]      [SQLite DB]
+```
+
+## 📂 Repository Contents: `cred_db_mcp_server`
+
+This repository currently hosts the **Credential Database MCP Server** (`cred_db_mcp`). This component provides the tools necessary for the agent to read from and write to the internal provider/credential database.
+
+### Exposed Tools
+
+The server exposes the following MCP tools (via Gradio's MCP support):
+
+*   **`sync_provider_from_npi(npi)`**:
+    *   Syncs a provider's data from the NPI registry (via backend) to the local database.
+    *   *Usage*: Onboarding new providers.
+*   **`add_or_update_credential(provider_id, type, issuer, number, expiry_date)`**:
+    *   Upserts a credential record for a provider.
+    *   *Usage*: Keeping license data current.
+*   **`list_expiring_credentials(window_days, dept?, location?)`**:
+    *   Returns a list of credentials expiring within the specified window (e.g., 90 days).
+    *   *Usage*: Proactive monitoring and sweeps.
+*   **`get_provider_snapshot(provider_id?, npi?)`**:
+    *   Returns provider info + all credentials + alerts.
+    *   *Usage*: Context retrieval for user queries.
+
+## 🚀 Getting Started
+
+### Prerequisites
 
-# Run
-uvicorn src.cred_db_mcp.main:app --reload
+*   **Python 3.11+**
+*   **uv** (recommended) or `pip`
+*   Access to the **Credential API Backend** (running locally or on Modal).
+
+### Installation
+
+1.  Clone the repository:
+    ```bash
+    git clone https://github.com/your-username/credential-watch-cred-db-mcp.git
+    cd credential-watch-cred-db-mcp
+    ```
+
+2.  Install dependencies using `uv`:
+    ```bash
+    uv sync
+    ```
+    Or with `pip`:
+    ```bash
+    pip install -e .
+    ```
+
+### Configuration
+
+The server requires the backend API URL to be configured. Create a `.env` file in the root directory:
+
+```env
+# URL of the backend Credential API service
+CRED_API_BASE_URL=http://localhost:8000
 ```
 
-## Example Tool Call
+### Running the Server
 
-**Tool:** `list_expiring_credentials`
-**Endpoint:** `POST /mcp/tools/list_expiring_credentials`
-**Headers:** `Content-Type: application/json`
+Start the Gradio MCP server:
 
-**Body:**
-```json
-{
-  "window_days": 90,
-  "dept": "Cardiology"
-}
+```bash
+uv run src/cred_db_mcp_server/main.py
 ```
 
-**Response:**
-```json
-[
-  {
-    "provider": { "full_name": "Dr. Alice Smith", ... },
-    "credential": { "type": "state_license", "expiry_date": "2023-12-01", ... },
-    "days_to_expiry": 25,
-    "risk_score": 3
-  }
-]
+The server will launch and:
+1.  Open a Gradio UI in your browser (usually `http://127.0.0.1:7860`) where you can manually test the tools.
+2.  Expose the MCP endpoints via SSE for the agent to connect to.
+
+## 🧪 Testing
+
+Run the unit tests using `pytest`:
+
+```bash
+uv run pytest
 ```
+
+## 🛠 Tech Stack
+
+*   **Python 3.11**
+*   **Gradio 5+** (Frontend & MCP Server)
+*   **FastAPI / HTTPX** (Networking)
+*   **Pydantic** (Data validation)
+*   **uv** (Package management)
+
+---
+*Built for the Hugging Face MCP 1st Birthday Hackathon.*

pyproject.toml

@@ -29,3 +29,8 @@ packages = ["src/cred_db_mcp_server"]
 [tool.pytest.ini_options]
 pythonpath = "src"
 testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.1",
+]

tests/test_cred_db_mcp.py

@@ -1,152 +0,0 @@
-import pytest
-from fastapi.testclient import TestClient
-from sqlalchemy import create_engine
-from sqlalchemy.orm import sessionmaker
-from sqlalchemy.pool import StaticPool
-from datetime import date, timedelta
-import os
-
-from src.cred_db_mcp.main import app, get_db
-from src.cred_db_mcp.db import Base
-from src.cred_db_mcp.models import Provider, Credential
-
-# Setup in-memory DB for tests
-# Use StaticPool to share the in-memory DB across multiple sessions/connections
-SQLALCHEMY_DATABASE_URL = "sqlite:///:memory:"
-
-engine = create_engine(
-    SQLALCHEMY_DATABASE_URL,
-    connect_args={"check_same_thread": False},
-    poolclass=StaticPool
-)
-TestingSessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
-
-def override_get_db():
-    try:
-        db = TestingSessionLocal()
-        yield db
-    finally:
-        db.close()
-
-app.dependency_overrides[get_db] = override_get_db
-
-@pytest.fixture(scope="module")
-def test_client():
-    # Create tables once for the module
-    Base.metadata.create_all(bind=engine)
-    client = TestClient(app)
-    yield client
-    Base.metadata.drop_all(bind=engine)
-
-@pytest.fixture(autouse=True)
-def clean_tables():
-    # Optional: Clear data between tests if needed, but for now just appending is fine
-    # as long as IDs/NPIs don't clash or we don't care about accumulation.
-    # To be safer, we can delete all data.
-    with engine.connect() as conn:
-        conn.execute(Credential.__table__.delete())
-        conn.execute(Provider.__table__.delete())
-        conn.commit()
-
-@pytest.fixture
-def db_session():
-    db = TestingSessionLocal()
-    yield db
-    db.close()
-
-def test_read_root(test_client):
-    response = test_client.get("/")
-    assert response.status_code == 200
-    assert response.json()["service"] == "cred_db_mcp"
-
-def test_add_and_snapshot_provider(test_client, db_session):
-    prov = Provider(
-        npi="999999", full_name="Test Doc", primary_specialty="General", is_active=True
-    )
-    db_session.add(prov)
-    db_session.commit()
-
-    response = test_client.post(
-        "/mcp/tools/get_provider_snapshot",
-        json={"npi": "999999"}
-    )
-    assert response.status_code == 200
-    data = response.json()
-    assert data["provider"]["full_name"] == "Test Doc"
-    assert len(data["credentials"]) == 0
-
-def test_add_credential(test_client, db_session):
-    # Seed provider
-    prov = Provider(
-        npi="888888", full_name="Credential Doc", primary_specialty="Surgery", is_active=True
-    )
-    db_session.add(prov)
-    db_session.commit()
-    db_session.refresh(prov)
-
-    # Add Credential via tool
-    expiry = (date.today() + timedelta(days=100)).strftime("%Y-%m-%d")
-    response = test_client.post(
-        "/mcp/tools/add_or_update_credential",
-        json={
-            "provider_id": prov.id,
-            "type": "board_cert",
-            "issuer": "ABMS",
-            "number": "XYZ123",
-            "expiry_date": expiry
-        }
-    )
-    assert response.status_code == 200
-    data = response.json()
-    assert data["number"] == "XYZ123"
-    assert data["status"] == "active"
-
-def test_list_expiring(test_client, db_session):
-    # Seed provider
-    prov = Provider(
-        npi="777777", full_name="Expiring Doc", dept="ER", location="NYC", is_active=True
-    )
-    db_session.add(prov)
-    db_session.commit()
-    db_session.refresh(prov)
-
-    # Add expiring credential (in 10 days)
-    # expiry date must be a date object for the model
-    expiry_1 = date.today() + timedelta(days=10)
-    cred = Credential(
-        provider_id=prov.id,
-        type="license",
-        issuer="State",
-        number="L1",
-        expiry_date=expiry_1,
-        status="active"
-    )
-    db_session.add(cred)
-
-    # Add non-expiring credential (in 100 days)
-    expiry_2 = date.today() + timedelta(days=100)
-    cred2 = Credential(
-        provider_id=prov.id,
-        type="license",
-        issuer="State",
-        number="L2",
-        expiry_date=expiry_2,
-        status="active"
-    )
-    db_session.add(cred2)
-    db_session.commit()
-
-    # Test tool
-    response = test_client.post(
-        "/mcp/tools/list_expiring_credentials",
-        json={
-            "window_days": 30,
-            "dept": "ER"
-        }
-    )
-    assert response.status_code == 200
-    data = response.json()
-    assert len(data) == 1
-    assert data[0]["credential"]["number"] == "L1"
-    assert data[0]["days_to_expiry"] == 10
-    assert data[0]["risk_score"] == 3  # < 30 days

uv.lock

@@ -201,6 +201,11 @@ test = [
     { name = "pytest-asyncio" },
 ]
 
+[package.dev-dependencies]
+dev = [
+    { name = "pytest" },
+]
+
 [package.metadata]
 requires-dist = [
     { name = "fastapi", specifier = ">=0.100.0" },
@@ -215,6 +220,9 @@ requires-dist = [
 ]
 provides-extras = ["test"]
 
+[package.metadata.requires-dev]
+dev = [{ name = "pytest", specifier = ">=9.0.1" }]
+
 [[package]]
 name = "fastapi"
 version = "0.123.0"