Spaces:
Sleeping
Sleeping
| 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: | |
| 1. **A unified, queryable source of truth.** | |
| 2. **A proactive alerting system** for at-risk credentials. | |
| The system is designed to solve the real-world problem of missed credential expiries leading to compliance issues, denied claims, and scheduling conflicts. | |
| ## 🧩 Architecture | |
| 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. | |
| ## 🧪 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.* | |