Merge pull request #4 from humandotlearning/update-for-hf-space

README.md

@@ -1,7 +1,125 @@
-# CredentialWatch
+---
+title: CredentialWatch MCP Server
+emoji: 🩺
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+python_version: 3.11
+sdk_version: 6.0.1
+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
 
 **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.
 
+## 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.
+
+### Configuration
+
+The server requires the backend Credential API URL to be configured. In your Space settings (or local `.env` file), add:
+
+```env
+CRED_API_BASE_URL=http://localhost:8000  # Replace with actual backend URL
+```
+
+## 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`
+
+## Using this Space from an MCP client
+
+### Easiest: Hugging Face MCP Server (no manual config)
+
+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.
+
+### Manual config (generic MCP client using mcp-remote)
+
+If your MCP client uses a JSON config, you can point it to the SSE endpoint via `mcp-remote`:
+
+```jsonc
+{
+  "mcpServers": {
+    "credentialwatch": {
+      "command": "npx",
+      "args": [
+        "mcp-remote",
+        "https://<space-host>/gradio_api/mcp/sse"
+      ]
+    }
+  }
+}
+```
+
+Replace `<space-host>` with the full URL of your Space.
+
+## Local development
+
+```bash
+# 1. Install deps
+uv sync
+# or
+pip install -r requirements.txt
+
+# 2. Run locally
+uv run python app.py
+```
+
+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.
+
+## 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. 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. The header must be the first thing in the file (no blank lines before `---`).
+- **MCP badge missing**: Check that your app calls `demo.launch(mcp_server=True)` and confirm the Space is public.
+- **LFS issues**: Ensure `README.md` is NOT tracked via Git LFS.
+
+---
+
 ## 🎯 Project Goal
 
 CredentialWatch transforms messy, decentralized provider data (state licenses, board certifications, DEA numbers) into:
@@ -58,52 +176,6 @@ The server exposes the following MCP tools (via Gradio's MCP support):
     *   Returns provider info + all credentials + alerts.
     *   *Usage*: Context retrieval for user queries.
 
-## 🚀 Getting Started
-
-### Prerequisites
-
-*   **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
-```
-
-### Running the Server
-
-Start the Gradio MCP server:
-
-```bash
-uv run src/cred_db_mcp_server/main.py
-```
-
-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`:

src/cred_db_mcp_server/main.py

@@ -20,7 +20,7 @@ def create_demo():
         inputs=[gr.Textbox(label="NPI")],
         outputs=gr.JSON(label="Provider Data"),
         description="Syncs a provider's data from the NPI registry.",
-        allow_flagging="never"
+        flagging_mode="never"
     )
 
     # Tool 2: add_or_update_credential
@@ -35,7 +35,7 @@ def create_demo():
         ],
         outputs=gr.JSON(label="Credential Data"),
         description="Adds or updates a credential for a provider.",
-        allow_flagging="never"
+        flagging_mode="never"
     )
 
     # Tool 3: list_expiring_credentials
@@ -48,7 +48,7 @@ def create_demo():
         ],
         outputs=gr.JSON(label="Expiring Credentials"),
         description="Lists credentials expiring within a certain number of days.",
-        allow_flagging="never"
+        flagging_mode="never"
     )
 
     # Tool 4: get_provider_snapshot
@@ -60,7 +60,7 @@ def create_demo():
         ],
         outputs=gr.JSON(label="Provider Snapshot"),
         description="Gets a snapshot of a provider's data including credentials and alerts.",
-        allow_flagging="never"
+        flagging_mode="never"
     )
 
     demo = gr.TabbedInterface(