ubuntu-patient-care MCP server
## ๐ฅ Ubuntu Patient Care MCP Server: The Intelligent, Offline Authorization Gateway! ๐ฟ๐ฆ This **Model Context Protocol (MCP)** server eliminates the **15-minute healthcare bottleneck** โฐ by providing **instant, offline** medical scheme authorization in South Africa. --- ### ๐ ๏ธ Key MCP Tools Our server exposes three critical tools for seamless authorization: * `validate_medical_aid` ๐ณ: **Instant** member and plan validation (works completely **offline**). * `estimate_patient_cost` ๐ฐ: Calculates the exact patient co-payment (**$ZAR$**) instantly and accurately. * `create_preauth_request` โ : Validates and queues pre-authorization requests for an industry-leading **95% approval rate**! --- ### โญ Core Value Proposition * **SPEED:** **$30 \text{x}$ faster** ๐ than manual processes. * **RESILIENCE:** Works in **load shedding/remote areas** ๐ก with full offline capability. * **IMPACT:** Ensures financial transparency for patients. This system is **Built for African reality.** ๐
Ask AI about ubuntu-patient-care MCP server
Powered by Claude ยท Grounded in docs
I know everything about ubuntu-patient-care MCP server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
๐ก๏ธ SDOH Chat: Gift of the Givers (GOTG) Project
AI Partner Catalyst Hackathon Submission
Integrating Google Cloud Vertex AI, ElevenLabs, Confluent, and Datadog.
This module is a critical component of the Gift of the Givers advanced ecosystem, integrating with RIS (Radiology Information Systems), PACS, and Medical Dictation to address the Social Determinants of Health (SDOH).
๐ The Problem: The Void
Close your eyes and imagine the moment you stop being a human being.
Imagine you are standing in the middle of the street where you grew up. You are screaming for helpโyour lungs are burningโbut the people who used to know your name look right through you. Not with hate... but with nothing. You have become a ghost in your own home. Even the police, the ones paid to see you, walk past as if you are a shadow on the wall. This is Ostracization. It is the realization that the world has deleted you while you are still breathing.
[Visual: A shot of a clinical, white-tiled floor. A single plastic bowl of water. A pair of hands trembling.]
Imagine you are lying in a bed. You need to bathe. You need to wipe yourself. You have the dignity of a grown man, but you are trapped in the body of an infant. This is Frail Care. But here is the horror: Your mother is gone. Your brother is gone. Your wife was not lucky enough to survive the accident. There is no one left who loves you enough to touch you. You are waiting for a stranger in a uniform to perform the most intimate acts of your life for a paycheck. You aren't a person anymore; you are a 'task' on a clipboard.
We spend billions on healthcare. We build world-class PACS and RIS to scan the heart and mend the bone. But once your Inner Circle is takenโonce the few souls you lived for are in the groundโyour heart doesn't need a doctor. It needs a reason to beat.
When you have no one to live for, and no one who needs you to stay... death stops being a tragedy. It starts to feel like a blessing.
This is the 'Why' that medicine cannot fix. This is the crisis we ignore while we brag about our algorithms. We are keeping bodies alive in a world that has already buried their souls. We are losing our loved onesโnot to disease, but to the Void.
๐ฏ๏ธ The Solution: Rebuilding the Tether
But hope is not a clinical outcome. It is a biological force.
Think of the sound of your wife laughing at your wedding. Think of the look in your sonโs eyesโthat mix of terror and absolute trustโas you teach him to swim. That physical jolt in your chest when you hear the words: "Mama, I love you." These are not just 'moments.' They are the internal fuel that makes the human spirit unkillable.
In healthcare, we call it 'impossible' when a patient survives a trauma they shouldn't have. We call it a 'miracle' when an old man defies his charts. But it isn't a miracle. Itโs the Why.
Imagine if your whole community needed youโeven for something as simple as water. Imagine being part of a mission so much bigger than your own struggle that your life becomes a necessity for others. When you are a pillar, you cannot afford to fall. And that is when you become immortal.
It sounds complex to engineer 'meaning.' But when you embrace our deepest, most beautiful human flawsโour need to be seen, our need to be usefulโthe architecture becomes clear.
We created a simple, low-bandwidth gateway, powered by a complex orchestration of AI agents. We don't use technology to replace the tribe; we use it to rebuild the tether.
We have built a digital forge where redundancy is burned away and reliability is proven. Where a 'ghost' can earn their way back into the circle of the seen. Where we don't just mend the limb... we ignite the heart.
โก Technical Architecture & Stack
Our solution leverages the Google Cloud Partner Ecosystem to create a resilient, voice-first interface for the most vulnerable.
๐ง The Brain: Google Cloud Vertex AI (Gemini 2.5 Flash-Lite)
The core intelligence of the system. Gemini 2.5 Flash-Lite powers our Agent Forge and Quest Master, analyzing user inputs for emotional context, generating meaningful "Quests" (community tasks), and maintaining the integrity of the social graph.
- Why 2.5 Flash-Lite? It offers the perfect balance of speed and reasoning for real-time chat, ensuring low latency even on slower connections.
- Local Fallback: If the cloud is unreachable or quotas are hit, the system seamlessly switches to a local Ollama (Gemma 2B) instance, ensuring the "Forge" never goes silent.
๏ฟฝ The Ears: Whisper Mini (Local STT)
To ensure privacy and functionality in low-bandwidth environments, we use OpenAI's Whisper Mini model running locally on the edge.
- Privacy-First: Voice data is transcribed locally; audio files are not sent to the cloud unless necessary.
- Offline Capable: Transcription works even when internet connectivity is spotty.
๏ฟฝ๐ฃ๏ธ The Voice: ElevenLabs + Hybrid Fallback
To serve the illiterate and the elderly, the interface is voice-first.
- Primary: ElevenLabs API provides hyper-realistic, empathetic voices (Rachel, Emergency, Medical) that build trust.
- Resilience Layer: A custom Hybrid TTS Engine that automatically falls back to local neural models (Silero TTS) or browser-native synthesis if the internet connection degrades or API quotas are hit. This ensures the "voice" of the community never goes silent.
๐ The Nervous System: Confluent (Kafka)
Real-time event streaming handles the pulse of the community. Every "Quest" completed, every "Help Signal" sent is streamed via Confluent Cloud, allowing for immediate reaction and analysis without locking data in silos.
๐๏ธ The Eyes: Datadog
End-to-end observability monitors the health of our agents. We track:
- AI Latency: Ensuring Gemini and ElevenLabs respond in real-time.
- Community Health: Custom metrics tracking "Integrity Scores" and "Quest Completion Rates".
- System Vitals: Error rates on the Flask backend and Cloudflare tunnels.
๐ฎ Gamification: The Forge & Integrity XP
We gamify the healing process using "The Forge," an AI persona that acts as a mentor.
- Integrity XP: Users earn Experience Points (XP) for demonstrating vulnerability, insight, and resilience in their conversations.
- Insights Profile: A dedicated UI tracks the user's "Level" and stores a history of profound insights extracted from their conversations.
- Visual Feedback: Users see their XP grow in real-time, reinforcing positive mental health habits.
๐ System Diagrams
1. High-Level Architecture
%%{init: {'theme': 'default', 'themeVariables': { 'primaryColor': '#4285F4', 'primaryBorderColor': '#2C5AA0', 'primaryTextColor': '#fff', 'lineColor': '#2C5AA0', 'secondaryColor': '#34A853', 'tertiaryColor': '#EA4335', 'fontSize': '16px', 'fontFamily': 'arial'}}}%%
graph TD
subgraph Client["๐ฑ CLIENT LAYER - User Interface"]
UI["๐ฅ๏ธ Web Dashboard<br/>Low-Bandwidth Optimized"]
Mic["๐ค Voice Input<br/>Whisper STT"]
Speaker["๐ Audio Output<br/>Browser TTS"]
end
subgraph Security["๐ SECURITY LAYER - Cloudflare Edge"]
CF["๐ก๏ธ Cloudflare Tunnel<br/>SSL/TLS Encryption<br/>Global CDN"]
end
subgraph Backend["โ๏ธ BACKEND LAYER - Flask Core"]
API["๐ก REST API<br/>Low-Latency Routing"]
Auth["๐ JWT & RBAC<br/>Permission System"]
Proxy["๐ TTS Manager<br/>Smart Fallback Logic"]
end
subgraph AI_Cloud["โ๏ธ AI INTELLIGENCE LAYER"]
Gemini["๐ง Google Gemini 2.5 Flash-Lite<br/>Advanced Reasoning<br/>Context Understanding"]
Eleven["๐๏ธ ElevenLabs API<br/>Premium Voice Synthesis<br/>Multi-Language Support"]
end
subgraph Data_Stream["๐ DATA & STATE LAYER"]
Kafka["๐ Confluent Kafka<br/>Real-Time Event Streaming<br/>Community Pulse"]
SQLite["๐พ SQLite Database<br/>User Data & Messages<br/>Offline Capable"]
end
subgraph Fallback["โ RESILIENCE LAYER - Auto-Fallback"]
Silero["๐ต Silero TTS<br/>Local Neural Model<br/>Instant Response"]
Whisper["๐ Whisper Mini<br/>Local Speech Recognition<br/>Privacy First"]
end
Mic -->|๐๏ธ Voice| API
API -->|๐ Speech-to-Text| Whisper
Whisper -->|๐ Text| Gemini
Gemini -->|๐ฌ Response| API
API -->|๐ Synthesize| Proxy
Proxy -->|โญ Primary| Eleven
Proxy -.->|โก Fallback| Silero
Eleven -->|๐ Stream| Speaker
Silero -->|๐ WAV| Speaker
API -->|๐ค Events| Kafka
API -->|๐พ Persist| SQLite
Client <-->|๐ HTTPS| CF
CF <-->|๐ Fast| Backend
Backend <-->|โ๏ธ Async| AI_Cloud
Backend -->|๐ Hybrid| Fallback
Backend <-->|๐ Real-Time| Data_Stream
style Client fill:#E8F0FE,stroke:#4285F4,stroke-width:3px,color:#1a73e8
style Security fill:#C5E1A5,stroke:#7CB342,stroke-width:3px,color:#33691E
style Backend fill:#FFE0B2,stroke:#F57C00,stroke-width:3px,color:#E65100
style AI_Cloud fill:#F8BBD0,stroke:#C2185B,stroke-width:3px,color:#880E4F
style Data_Stream fill:#B3E5FC,stroke:#0277BD,stroke-width:3px,color:#01579B
style Fallback fill:#D1C4E9,stroke:#512DA8,stroke-width:3px,color:#311B92
2. The "Ghost to Pillar" Transformation Journey
%%{init: {'theme': 'default', 'themeVariables': { 'primaryColor': '#9C27B0', 'primaryBorderColor': '#6A1B9A', 'primaryTextColor': '#fff', 'lineColor': '#6A1B9A', 'fontSize': '14px'}}}%%
sequenceDiagram
actor Ghost as ๐ป The "Ghost"<br/>Invisible & Disconnected
participant Forge as โ๏ธ The Forge<br/>AI Integrity Coach
participant Quest as ๐ Quest Master<br/>Task Generator
participant Tribe as ๐๏ธ The Tribe<br/>Community
Note over Ghost,Tribe: STAGE 1: THE VOID - User Feels Invisible
Ghost->>Forge: "I have no one left who needs me..."
Forge->>Forge: ๐ง Analyzes emotional depth using Gemini
Note over Ghost,Tribe: STAGE 2: THE QUEST - System Creates Meaning
Forge->>Quest: "Create a meaningful task for this person"
Quest->>Ghost: ๐ Quest Assigned: "Check on Mrs. Higgins<br/>She hasn't had water today"
Note over Ghost,Tribe: STAGE 3: THE ACTION - User Becomes Useful
Ghost->>Tribe: ๐ง Delivers water to Mrs. Higgins
Ghost->>Tribe: ๐ค Checks in on 2 other elderly neighbors
Tribe->>Ghost: "Thank you, we couldn't do this without you!"
Note over Ghost,Tribe: STAGE 4: THE TRANSFORMATION - Recognition & Identity
Ghost->>Forge: "I actually helped people today."
Forge->>Ghost: โญ Integrity Score: 10 โ 47
Forge->>Ghost: ๐๏ธ New Status: "Community Pillar"
Forge->>Ghost: "You are SEEN. You are NEEDED."
Note over Ghost,Tribe: RESULT: ๐ป Ghost becomes ๐๏ธ Pillar of Community
3. Resilience & Fallback Logic - "Always Speaking"
%%{init: {'theme': 'default', 'themeVariables': { 'primaryColor': '#FF6F00', 'primaryBorderColor': '#E65100', 'primaryTextColor': '#fff', 'lineColor': '#E65100', 'fontSize': '13px'}}}%%
flowchart TD
Start(["๐ฏ User Requests TTS<br/>Speak Response"])
Start --> CheckAPI{๐ API Key Valid?}
CheckAPI -->|โ
YES| CallEleven["โญ PRIMARY:<br/>ElevenLabs API<br/>Premium Voice<br/>Highest Quality"]
CheckAPI -->|โ NO| SkipEleven["Skip Premium"]
CallEleven --> ElevenSuccess{โก API Responds<br/>in 2-3 seconds?}
ElevenSuccess -->|โ
YES| StreamAudio["๐๏ธ Stream<br/>High-Fidelity Audio<br/>Multiple Voices"]
ElevenSuccess -->|โ ๏ธ TIMEOUT<br/>or ERROR| LocalTTS
SkipEleven --> LocalTTS["โก SECONDARY:<br/>Silero Local TTS<br/>Instant Response<br/>less than 100ms"]
LocalTTS --> LocalSuccess{โ Model<br/>Initialized?}
LocalSuccess -->|โ
YES| StreamWav["๐ Stream Local WAV<br/>Fast & Reliable"]
LocalSuccess -->|โ FAIL| BrowserTTS["๐ TERTIARY:<br/>Browser Native TTS<br/>Always Available<br/>Ultimate Fallback"]
StreamAudio --> Success["โ
User Hears Voice<br/>Experience Uninterrupted"]
StreamWav --> Success
BrowserTTS --> Success
style Start fill:#FFF9C4,stroke:#F57F17,stroke-width:3px,color:#000
style CheckAPI fill:#FFE0B2,stroke:#FF6F00,stroke-width:2px,color:#000
style CallEleven fill:#FFB74D,stroke:#E65100,stroke-width:3px,color:#fff
style LocalTTS fill:#FFCC80,stroke:#FF6F00,stroke-width:3px,color:#000
style BrowserTTS fill:#FFD54F,stroke:#F57F17,stroke-width:3px,color:#000
style Success fill:#C8E6C9,stroke:#388E3C,stroke-width:3px,color:#000
๐ Getting Started
- Clone the Repository
- Install Dependencies:
pip install -r requirements.txt - Configure Keys: Update
config.iniwith your Google Cloud, ElevenLabs, and Confluent keys. - Run the Server:
python run.py - Access: Open
https://localhost:5000(or your Cloudflare URL).
Built with โค๏ธ for the AI Partner Catalyst Hackathon.
