https://github.com/alwayssany/health-api
A comprehensive FastAPI microservice for health-related operations that also powered by MCP
https://github.com/alwayssany/health-api
alembic fastapi fastmcp mcp mcp-server postgresql pydantic python
Last synced: about 2 months ago
JSON representation
A comprehensive FastAPI microservice for health-related operations that also powered by MCP
- Host: GitHub
- URL: https://github.com/alwayssany/health-api
- Owner: AlwaysSany
- License: mit
- Created: 2025-06-14T16:50:25.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-15T03:21:50.000Z (about 1 year ago)
- Last Synced: 2025-06-15T04:27:31.181Z (about 1 year ago)
- Topics: alembic, fastapi, fastmcp, mcp, mcp-server, postgresql, pydantic, python
- Language: Python
- Homepage:
- Size: 125 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# Health Microservice API
A comprehensive FastAPI microservice for health-related operations with JWT authentication, PostgreSQL database, and Alembic migrations.It is backed by MCP server using `FastApiMCP`
## Working Demo
[health-api-mcp-server-with-fastapi-demo.webm](https://github.com/user-attachments/assets/49dee391-a380-4c66-b7b9-f27ce44c2836)
## Features
- JWT-based authentication
- PostgreSQL database with async SQLAlchemy
- Alembic database migrations
- Comprehensive health domain models (Patient, Doctor, Appointment, Medical Record)
- RESTful API endpoints
- Interactive API documentation (Swagger UI)
- Modular project structure
- CORS middleware
- Async/await support
- UV package manager for fast dependency resolution
- Comprehensive test suite
## Prerequisites
- Python 3.13.3+
- PostgreSQL
- UV package manager
## Project Structure
The project follows a modular structure suitable for large applications with clear separation of concerns between models, schemas, routes, and business logic.
## Installation
### Install UV
```bash
# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# Or with pip
pip install uv
```
## Setup Project
Clone the repository:
```bash
git clone
cd health-api
```
Install dependencies:
```bash
uv sync
```
Set up environment variables:
```bash
cp .env.example .env
# Edit .env with your database credentials and secret key
```
## Database Migrations with Alembic (using UV)
Alembic is used for handling database migrations. All commands below assume you are in the project root directory.
But first off all create up a PostgreSQL database:
```sql
CREATE DATABASE health_db;
```
### Generate a New Migration (Autogenerate)
```bash
uv run alembic revision --autogenerate -m "Your migration message"
```
### Apply Migrations (Upgrade Database)
```bash
uv run alembic upgrade head
```
Start the application (choose one):
```bash
uv run uvicorn app.main:app --host 0.0.0.0 --port 5000 --reload
# Or use the convenience script
chmod +x scripts/start.sh
./scripts/start.sh
```
## Some more required alembic migration commands
These commands are not required during setup but are useful for managing migrations in the future
during development.
#### Downgrade Database (Revert Last Migration)
```bash
uv run alembic downgrade -1
```
#### View Current Migration Status
```bash
uv run alembic current
```
#### Show Migration History
```bash
uv run alembic history
```
For more Alembic commands and usage, see the [Alembic documentation](https://alembic.sqlalchemy.org/en/latest/).
## Development
Install development dependencies:
```bash
uv sync --group dev
```
Run tests:
```bash
uv run pytest
# Or use the test script
chmod +x scripts/test.sh
./scripts/test.sh
```
Code formatting:
```bash
uv run black app/ tests/
uv run isort app/ tests/
```
Type checking:
```bash
uv run mypy app/
```
## Docker
Build and run with Docker Compose:
```bash
docker-compose up --build
```
This will start both the PostgreSQL database and the FastAPI application.
## API Documentation
Once the application is running, visit:
- Swagger UI: http://localhost:5000/docs
- ReDoc: http://localhost:5000/redoc
- MCP ping: check on terminal with the following command
```bash
curl -H "Authorization: Bearer "
-H "Accept: text/event-stream" http://localhost:5000/mcp
```
## Database Migrations
Create a new migration:
```bash
uv run alembic revision --autogenerate -m "Description of changes"
# Or use the migration script
chmod +x scripts/migrate.sh
./scripts/migrate.sh "Description of changes"
```
Apply migrations:
```bash
uv run alembic upgrade head
```
## Authentication
- Register a new user: `POST /auth/register`
- Login to get access token: `POST /auth/login`
- Use the token in Authorization header: `Bearer `
## Main API Endpoints (after authentication)
After obtaining a JWT access token, you can access the following endpoints:
🖼️ Click to see the Health Microservice API endpoints
### Doctors
- `GET /doctors` — List all doctors
- `GET /doctors/{doctor_id}` — Get a specific doctor by ID
- `POST /doctors` — Create a new doctor
- `PUT /doctors/{doctor_id}` — Update a doctor's information
- `DELETE /doctors/{doctor_id}` — Delete a doctor
### Patients
- `GET /patients` — List all patients
- `GET /patients/{patient_id}` — Get a specific patient by ID
- `POST /patients` — Create a new patient
- `PUT /patients/{patient_id}` — Update a patient's information
- `DELETE /patients/{patient_id}` — Delete a patient
### Medical Records
- `GET /medical-records` — List all medical records (optionally filter by patient)
- `GET /medical-records/{record_id}` — Get a specific medical record by ID
- `POST /medical-records` — Create a new medical record
- `PUT /medical-records/{record_id}` — Update a medical record
- `DELETE /medical-records/{record_id}` — Delete a medical record
### Appointments
- `GET /appointments` — List all appointments
- `GET /appointments/{appointment_id}` — Get a specific appointment by ID
- `POST /appointments` — Create a new appointment
- `PUT /appointments/{appointment_id}` — Update an appointment
- `DELETE /appointments/{appointment_id}` — Delete an appointment
### Telemedicine
- `POST /telemedicine/visits/` — Create a new virtual visit
- `GET /telemedicine/visits/` — List all virtual visits
- `GET /telemedicine/visits/{visit_id}` — Get a specific virtual visit by ID
- `POST /telemedicine/chats/` — Create a new chat log
- `GET /telemedicine/chats/` — List all chat logs
- `GET /telemedicine/chats/{chat_id}` — Get a specific chat log by ID
- `POST /telemedicine/videos/` — Create a new video session
- `GET /telemedicine/videos/` — List all video sessions
- `GET /telemedicine/videos/{video_id}` — Get a specific video session by ID
### Lab
- `POST /lab/orders/` — Create a new lab order
- `GET /lab/orders/` — List all lab orders
- `GET /lab/orders/{order_id}` — Get a specific lab order by ID
- `POST /lab/results/` — Create a new lab result
- `GET /lab/results/` — List all lab results
- `GET /lab/results/{result_id}` — Get a specific lab result by ID
- `POST /lab/images/` — Create a new diagnostic image
- `GET /lab/images/` — List all diagnostic images
- `GET /lab/images/{image_id}` — Get a specific diagnostic image by ID
### Referral
- `POST /referral/requests/` — Create a new referral request
- `GET /referral/requests/` — List all referral requests
- `GET /referral/requests/{request_id}` — Get a specific referral request by ID
- `POST /referral/statuses/` — Create a new referral status
- `GET /referral/statuses/` — List all referral statuses
- `GET /referral/statuses/{status_id}` — Get a specific referral status by ID
- `POST /referral/notes/` — Create a new specialist note
- `GET /referral/notes/` — List all specialist notes
- `GET /referral/notes/{note_id}` — Get a specific specialist note by ID
### Pharmacy
- `POST /pharmacy/medications/` — Create a new medication
- `GET /pharmacy/medications/` — List all medications
- `GET /pharmacy/medications/{med_id}` — Get a specific medication by ID
- `POST /pharmacy/prescriptions/` — Create a new prescription
- `GET /pharmacy/prescriptions/` — List all prescriptions
- `GET /pharmacy/prescriptions/{pres_id}` — Get a specific prescription by ID
- `POST /pharmacy/orders/` — Create a new pharmacy order
- `GET /pharmacy/orders/` — List all pharmacy orders
- `GET /pharmacy/orders/{order_id}` — Get a specific pharmacy order by ID
### Insurance
- `POST /insurance/plans/` — Create a new insurance plan
- `GET /insurance/plans/` — List all insurance plans
- `GET /insurance/plans/{plan_id}` — Get a specific insurance plan by ID
- `POST /insurance/claims/` — Create a new insurance claim
- `GET /insurance/claims/` — List all insurance claims
- `GET /insurance/claims/{claim_id}` — Get a specific insurance claim by ID
- `POST /insurance/payments/` — Create a new payment
- `GET /insurance/payments/` — List all payments
- `GET /insurance/payments/{payment_id}` — Get a specific payment by ID
- `POST /insurance/invoices/` — Create a new invoice
- `GET /insurance/invoices/` — List all invoices
- `GET /insurance/invoices/{invoice_id}` — Get a specific invoice by ID
All these endpoints require the Authorization: Bearer header. Refer to the interactive API docs at /docs for detailed request/response schemas and try out the endpoints interactively.
## Package Management with UV
UV provides fast dependency resolution and installation. Useful commands:
- `uv sync` - Install dependencies from lock file
- `uv add ` - Add a new dependency
- `uv remove ` - Remove a dependency
- `uv run ` - Run command in virtual environment
- `uv lock` - Update the lock file
## MCP Integration
Integration with MCP is done by using the
`FastApiMCP` class from the `fastapi_mcp` package.
The MCP server is mounted to the FastAPI
application using the `mount` method.
`windsurf` settings,
```json
{
"mcpServers": {
"health-api": {
"serverUrl": "http://localhost:5000/mcp",
"headers": {
"Authorization": "Bearer
"
}
}
}
}
```
`vscode` or `cursor` settings,
```json
{
"servers": {
"health-api": {
"url": "http://localhost:5000/mcp",
"headers": {
"Authorization": "Bearer
"
}
}
}
}
```
Note: I haven't tested on `vscode` or `cursor` yet.
## License
MIT License
## TODOs
- [ ] Add more test cases
- [ ] Add more features
- [ ] Add more documentation
- [ ] Add more security features
- [ ] Add more logging
- [ ] Add more monitoring
- [ ] Add more performance optimization
## Contributing
1. Install development dependencies: `uv sync
--group dev`
2. Make your changes
3. Run tests: `uv run pytest`
4. Format code: `uv run black app/ tests/`
5. Submit a pull request
See more at [Contributing](https://github.com/
AlwaysSany/health-api/blob/main/CONTRIBUTING.md).
## Contact
- Author: [Sany Ahmed](https://github.com/sany2k8)
- Email: sany2k8@gmail.com
## References
- [FastAPI](https://fastapi.tiangolo.com/)
- [SQLAlchemy](https://www.sqlalchemy.org/)
- [Alembic](https://alembic.sqlalchemy.org/)
- [Pydantic](https://pydantic-docs.helpmanual.io/)
- [Python](https://www.python.org/)
- [PostgreSQL](https://www.postgresql.org/)
- [UV](https://astral.sh/uv/)
- [JWT](https://jwt.io/)