Merge pull request #4 from humandotlearning/hf-spaces-config

README.md

@@ -1,20 +1,66 @@
-# CredentialWatch: NPI MCP Server
-
-This repository contains the **NPI (NPPES) Model Context Protocol (MCP) Server** for **CredentialWatch**, a demo product for the **Hugging Face MCP 1st Birthday / Gradio Agents Hackathon**.
+---
+title: CredentialWatch MCP Server
+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 exposing healthcare credential tools."
+tags:
+  - mcp
+  - gradio
+  - tools
+  - healthcare
+pinned: false
+---
+
+# CredentialWatch MCP Server
+
+Agent-ready Gradio Space that exposes healthcare credential tools (lookups, expiry checks, risk scoring) over **Model Context Protocol (MCP)**.
+
+## Hugging Face Space
+
+This repository is designed to run as a **Gradio Space**.
+
+- 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`)
+
+When you push this repo to a Space with SDK = **Gradio**, the UI and the MCP server will be started automatically.
 
 ## 🩺 About CredentialWatch
 
 **CredentialWatch** is an agentic system designed to manage healthcare provider credentials. It serves as a central radar to track expiries, license statuses, and compliance risks across multiple providers.
 
-The system is composed of multiple independent MCP servers and a central agent:
-1.  **`npi_mcp` (This Repo):** Read-only access to public provider data via the NPPES NPI Registry.
-2.  `cred_db_mcp`: Internal provider & credential database operations (SQLite).
-3.  `alert_mcp`: Alert logging and management.
-4.  **Agent UI:** A Gradio-based interface powered by LangGraph.
-
 ### Role of `npi_mcp`
 This MCP server exposes tools to search for and retrieve healthcare provider information from the public [NPPES NPI Registry](https://npiregistry.cms.hhs.gov/api). It acts as a proxy, forwarding requests to a backend **Modal** FastAPI service (`NPI_API`) which handles the actual external API communication and normalization.
 
+## MCP Server
+
+This Space exposes its tools via **Model Context Protocol (MCP)** using Gradio.
+
+### How MCP is enabled
+
+In `app.py` we:
+
+- install Gradio with MCP support: `pip install "gradio[mcp]"`
+- define typed Python functions with docstrings
+- launch the app with MCP support:
+
+```python
+demo.launch(mcp_server=True)
+```
+
+### MCP endpoints
+
+When the Space is running, Gradio exposes:
+
+- MCP SSE endpoint: `https://<space-host>/gradio_api/mcp/sse`
+- MCP schema: `https://<space-host>/gradio_api/mcp/schema`
+
 ## ✨ Tools
 
 This server exposes the following MCP tools:
@@ -25,46 +71,50 @@ This server exposes the following MCP tools:
 - **`get_provider_by_npi(npi)`**:
   - Retrieve detailed information for a specific provider using their 10-digit NPI number.
 
-## 🚀 Setup & Installation
-
-### Prerequisites
-- Python 3.11+
-- [`uv`](https://github.com/astral-sh/uv) package manager
-
-### Installation
+## Using this Space from an MCP client
 
-1. Clone the repository:
-   ```bash
-   git clone <repo-url>
-   cd npi-mcp-server
-   ```
+### Easiest: Hugging Face MCP Server (no manual config)
 
-2. Install dependencies:
-   ```bash
-   uv sync
-   ```
+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 server requires the URL of the backend Modal service. Set the following environment variable:
+If your MCP client uses a JSON config, you can point it to the SSE endpoint via `mcp-remote`:
 
-```bash
-export NPI_API_BASE_URL="https://your-modal-app-url.modal.run"
+```jsonc
+{
+  "mcpServers": {
+    "credentialwatch": {
+      "command": "npx",
+      "args": [
+        "mcp-remote",
+        "https://<space-host>/gradio_api/mcp/sse"
+      ]
+    }
+  }
+}
 ```
 
-*Defaults to `http://localhost:8000` if not set.*
+Replace `<space-host>` with the full URL of your Space.
 
-## 🏃 Usage
-
-To run the MCP server:
+## Local development
 
 ```bash
-uv run python -m npi_mcp_server.main
+# 1. Install deps
+uv pip install "gradio[mcp]" -r requirements.txt
+
+# 2. Run locally
+uv run python app.py
+# or
+GRADIO_MCP_SERVER=True uv run python app.py
 ```
 
-The server uses `FastMCP` and communicates over stdio (by default) or SSE depending on how it's invoked by the client.
+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`.
 
-## 🧪 Development
+### Testing
 
 Run tests using `pytest`:
 
@@ -72,6 +122,26 @@ Run tests using `pytest`:
 uv run pytest
 ```
 
+**Note:** The server requires the URL of the backend Modal service. Set the following environment variable:
+
+```bash
+export NPI_API_BASE_URL="https://your-modal-app-url.modal.run"
+```
+
+## Deploying to Hugging Face Spaces
+
+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. Go to **Settings** in your Space and add `NPI_API_BASE_URL` as a secret or variable if you have a private backend, or ensure the default works.
+5. Wait for the Space to build and start — it should show an **MCP badge** automatically.
+
+## Troubleshooting
+
+- **Configuration error**: Verify `sdk`, `app_file`, and `python_version` in the YAML header.
+- **MCP badge missing**: Check that `app.py` calls `demo.launch(mcp_server=True)` or `GRADIO_MCP_SERVER=True` is set. Confirm the Space is public.
+- **Tools not working**: Ensure `NPI_API_BASE_URL` is correctly set in the environment.
+
 ## 🏗️ Architecture
 
 - **Stack:** Python 3.11, `mcp`, `httpx`, `pydantic`.