{"id":28816765,"url":"https://github.com/alwayssany/health-api","last_synced_at":"2026-05-06T04:02:03.085Z","repository":{"id":299165610,"uuid":"1002072346","full_name":"AlwaysSany/health-api","owner":"AlwaysSany","description":"A comprehensive FastAPI microservice for health-related operations that also powered by MCP","archived":false,"fork":false,"pushed_at":"2025-06-15T03:21:50.000Z","size":128,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-15T04:27:31.181Z","etag":null,"topics":["alembic","fastapi","fastmcp","mcp","mcp-server","postgresql","pydantic","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AlwaysSany.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-14T16:50:25.000Z","updated_at":"2025-06-15T03:23:08.000Z","dependencies_parsed_at":"2025-06-15T04:27:34.487Z","dependency_job_id":"2bfba48d-4bf8-40fd-9237-989bb18f5b09","html_url":"https://github.com/AlwaysSany/health-api","commit_stats":null,"previous_names":["alwayssany/health-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/AlwaysSany/health-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlwaysSany%2Fhealth-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlwaysSany%2Fhealth-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlwaysSany%2Fhealth-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlwaysSany%2Fhealth-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlwaysSany","download_url":"https://codeload.github.com/AlwaysSany/health-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlwaysSany%2Fhealth-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260595742,"owners_count":23033789,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alembic","fastapi","fastmcp","mcp","mcp-server","postgresql","pydantic","python"],"created_at":"2025-06-18T17:06:49.424Z","updated_at":"2026-05-06T04:02:03.079Z","avatar_url":"https://github.com/AlwaysSany.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Health Microservice API\n\nA comprehensive FastAPI microservice for health-related operations with JWT authentication, PostgreSQL database, and Alembic migrations.It is backed by MCP server using `FastApiMCP`\n\n## Working Demo\n\n[health-api-mcp-server-with-fastapi-demo.webm](https://github.com/user-attachments/assets/49dee391-a380-4c66-b7b9-f27ce44c2836)\n\n## Features\n\n- JWT-based authentication\n- PostgreSQL database with async SQLAlchemy\n- Alembic database migrations\n- Comprehensive health domain models (Patient, Doctor, Appointment, Medical Record)\n- RESTful API endpoints\n- Interactive API documentation (Swagger UI)\n- Modular project structure\n- CORS middleware\n- Async/await support\n- UV package manager for fast dependency resolution\n- Comprehensive test suite\n\n## Prerequisites\n\n- Python 3.13.3+\n- PostgreSQL\n- UV package manager\n\n## Project Structure\n\nThe project follows a modular structure suitable for large applications with clear separation of concerns between models, schemas, routes, and business logic.\n\n![project_structure](https://github.com/user-attachments/assets/496bd188-ba19-40ff-80e1-05abc6882966)\n\n\n## Installation\n\n### Install UV\n\n```bash\n# On macOS and Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# On Windows\npowershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n\n# Or with pip\npip install uv\n```\n\n## Setup Project\n\nClone the repository:\n\n```bash\ngit clone \u003crepository-url\u003e\ncd health-api\n```\n\nInstall dependencies:\n\n```bash\nuv sync\n```\n\nSet up environment variables:\n\n```bash\ncp .env.example .env\n# Edit .env with your database credentials and secret key\n```\n\n## Database Migrations with Alembic (using UV)\n\nAlembic is used for handling database migrations. All commands below assume you are in the project root directory.\n\nBut first off all create up a PostgreSQL database:\n\n```sql\nCREATE DATABASE health_db;\n```\n\n### Generate a New Migration (Autogenerate)\n\n```bash\nuv run alembic revision --autogenerate -m \"Your migration message\"\n```\n\n### Apply Migrations (Upgrade Database)\n\n```bash\nuv run alembic upgrade head\n```\n\nStart the application (choose one):\n\n```bash\nuv run uvicorn app.main:app --host 0.0.0.0 --port 5000 --reload\n# Or use the convenience script\nchmod +x scripts/start.sh\n./scripts/start.sh\n```\n\n## Some more required alembic migration commands\n\nThese commands are not required during setup but are useful for managing migrations in the future\nduring development.\n\n#### Downgrade Database (Revert Last Migration)\n\n```bash\nuv run alembic downgrade -1\n```\n\n#### View Current Migration Status\n\n```bash\nuv run alembic current\n```\n\n#### Show Migration History\n\n```bash\nuv run alembic history\n```\n\nFor more Alembic commands and usage, see the [Alembic documentation](https://alembic.sqlalchemy.org/en/latest/).\n\n\n## Development\n\nInstall development dependencies:\n\n```bash\nuv sync --group dev\n```\n\nRun tests:\n\n```bash\nuv run pytest\n# Or use the test script\nchmod +x scripts/test.sh\n./scripts/test.sh\n```\n\nCode formatting:\n\n```bash\nuv run black app/ tests/\nuv run isort app/ tests/\n```\n\nType checking:\n\n```bash\nuv run mypy app/\n```\n\n## Docker\n\nBuild and run with Docker Compose:\n\n```bash\ndocker-compose up --build\n```\n\nThis will start both the PostgreSQL database and the FastAPI application.\n\n## API Documentation\n\nOnce the application is running, visit:\n\n- Swagger UI: http://localhost:5000/docs\n- ReDoc: http://localhost:5000/redoc\n- MCP ping: check on terminal with the following command\n  \n```bash\ncurl -H \"Authorization: Bearer \u003cyour_bearer_token\u003e\" \n-H \"Accept: text/event-stream\" http://localhost:5000/mcp\n```\n\n## Database Migrations\n\nCreate a new migration:\n\n```bash\nuv run alembic revision --autogenerate -m \"Description of changes\"\n# Or use the migration script\nchmod +x scripts/migrate.sh\n./scripts/migrate.sh \"Description of changes\"\n```\n\nApply migrations:\n\n```bash\nuv run alembic upgrade head\n```\n\n## Authentication\n\n- Register a new user: `POST /auth/register`\n- Login to get access token: `POST /auth/login`\n- Use the token in Authorization header: `Bearer \u003ctoken\u003e`\n\n## Main API Endpoints (after authentication)\n\nAfter obtaining a JWT access token, you can access the following endpoints:\n\n![Health-Microservice-API-Swagger-UI](https://github.com/user-attachments/assets/9c43f8c2-2cb0-4113-86ff-4c983bf77da5)\n\n\u003cdetails\u003e\n  \u003csummary\u003e🖼️ Click to see the Health Microservice API endpoints\u003c/summary\u003e\n  \n### Doctors\n- `GET /doctors` — List all doctors\n- `GET /doctors/{doctor_id}` — Get a specific doctor by ID\n- `POST /doctors` — Create a new doctor\n- `PUT /doctors/{doctor_id}` — Update a doctor's information\n- `DELETE /doctors/{doctor_id}` — Delete a doctor\n\n### Patients\n- `GET /patients` — List all patients\n- `GET /patients/{patient_id}` — Get a specific patient by ID\n- `POST /patients` — Create a new patient\n- `PUT /patients/{patient_id}` — Update a patient's information\n- `DELETE /patients/{patient_id}` — Delete a patient\n\n### Medical Records\n- `GET /medical-records` — List all medical records (optionally filter by patient)\n- `GET /medical-records/{record_id}` — Get a specific medical record by ID\n- `POST /medical-records` — Create a new medical record\n- `PUT /medical-records/{record_id}` — Update a medical record\n- `DELETE /medical-records/{record_id}` — Delete a medical record\n\n### Appointments\n- `GET /appointments` — List all appointments\n- `GET /appointments/{appointment_id}` — Get a specific appointment by ID\n- `POST /appointments` — Create a new appointment\n- `PUT /appointments/{appointment_id}` — Update an appointment\n- `DELETE /appointments/{appointment_id}` — Delete an appointment\n\n### Telemedicine\n- `POST /telemedicine/visits/` — Create a new virtual visit\n- `GET /telemedicine/visits/` — List all virtual visits\n- `GET /telemedicine/visits/{visit_id}` — Get a specific virtual visit by ID\n- `POST /telemedicine/chats/` — Create a new chat log\n- `GET /telemedicine/chats/` — List all chat logs\n- `GET /telemedicine/chats/{chat_id}` — Get a specific chat log by ID\n- `POST /telemedicine/videos/` — Create a new video session\n- `GET /telemedicine/videos/` — List all video sessions\n- `GET /telemedicine/videos/{video_id}` — Get a specific video session by ID\n\n### Lab\n- `POST /lab/orders/` — Create a new lab order\n- `GET /lab/orders/` — List all lab orders\n- `GET /lab/orders/{order_id}` — Get a specific lab order by ID\n- `POST /lab/results/` — Create a new lab result\n- `GET /lab/results/` — List all lab results\n- `GET /lab/results/{result_id}` — Get a specific lab result by ID\n- `POST /lab/images/` — Create a new diagnostic image\n- `GET /lab/images/` — List all diagnostic images\n- `GET /lab/images/{image_id}` — Get a specific diagnostic image by ID\n\n### Referral\n- `POST /referral/requests/` — Create a new referral request\n- `GET /referral/requests/` — List all referral requests\n- `GET /referral/requests/{request_id}` — Get a specific referral request by ID\n- `POST /referral/statuses/` — Create a new referral status\n- `GET /referral/statuses/` — List all referral statuses\n- `GET /referral/statuses/{status_id}` — Get a specific referral status by ID\n- `POST /referral/notes/` — Create a new specialist note\n- `GET /referral/notes/` — List all specialist notes\n- `GET /referral/notes/{note_id}` — Get a specific specialist note by ID\n\n### Pharmacy\n- `POST /pharmacy/medications/` — Create a new medication\n- `GET /pharmacy/medications/` — List all medications\n- `GET /pharmacy/medications/{med_id}` — Get a specific medication by ID\n- `POST /pharmacy/prescriptions/` — Create a new prescription\n- `GET /pharmacy/prescriptions/` — List all prescriptions\n- `GET /pharmacy/prescriptions/{pres_id}` — Get a specific prescription by ID\n- `POST /pharmacy/orders/` — Create a new pharmacy order\n- `GET /pharmacy/orders/` — List all pharmacy orders\n- `GET /pharmacy/orders/{order_id}` — Get a specific pharmacy order by ID\n\n### Insurance\n- `POST /insurance/plans/` — Create a new insurance plan\n- `GET /insurance/plans/` — List all insurance plans\n- `GET /insurance/plans/{plan_id}` — Get a specific insurance plan by ID\n- `POST /insurance/claims/` — Create a new insurance claim\n- `GET /insurance/claims/` — List all insurance claims\n- `GET /insurance/claims/{claim_id}` — Get a specific insurance claim by ID\n- `POST /insurance/payments/` — Create a new payment\n- `GET /insurance/payments/` — List all payments\n- `GET /insurance/payments/{payment_id}` — Get a specific payment by ID\n- `POST /insurance/invoices/` — Create a new invoice\n- `GET /insurance/invoices/` — List all invoices\n- `GET /insurance/invoices/{invoice_id}` — Get a specific invoice by ID\n  \n\u003c/details\u003e\n\nAll these endpoints require the Authorization: Bearer \u003ctoken\u003e header. Refer to the interactive API docs at /docs for detailed request/response schemas and try out the endpoints interactively.\n\n## Package Management with UV\n\nUV provides fast dependency resolution and installation. Useful commands:\n\n- `uv sync` - Install dependencies from lock file\n- `uv add \u003cpackage\u003e` - Add a new dependency\n- `uv remove \u003cpackage\u003e` - Remove a dependency\n- `uv run \u003ccommand\u003e` - Run command in virtual environment\n- `uv lock` - Update the lock file\n\n## MCP Integration\n\nIntegration with MCP is done by using the \n`FastApiMCP` class from the `fastapi_mcp` package. \nThe MCP server is mounted to the FastAPI \napplication using the `mount` method.\n\n`windsurf` settings,\n\n```json \n{\n  \"mcpServers\": {\n    \"health-api\": {\n      \"serverUrl\": \"http://localhost:5000/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer \n        \u003cput_your_bearer_token_here\u003e\"\n      } \n    }\n  }\n}\n```\n\n`vscode` or `cursor` settings,\n\n```json\n{\n  \"servers\": {\n    \"health-api\": {\n      \"url\": \"http://localhost:5000/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer \n        \u003cput_your_bearer_token_here\u003e\"\n      }\n    }\n  }\n}\n```\n\nNote: I haven't tested on `vscode` or `cursor` yet.\n\n## License\n\nMIT License\n\n## TODOs\n- [ ] Add more test cases\n- [ ] Add more features\n- [ ] Add more documentation\n- [ ] Add more security features\n- [ ] Add more logging\n- [ ] Add more monitoring\n- [ ] Add more performance optimization\n\n## Contributing\n\n1. Install development dependencies: `uv sync \n--group dev`\n2. Make your changes\n3. Run tests: `uv run pytest`\n4. Format code: `uv run black app/ tests/`\n5. Submit a pull request\n\nSee more at [Contributing](https://github.com/\nAlwaysSany/health-api/blob/main/CONTRIBUTING.md).\n\n## Contact\n\n- Author: [Sany Ahmed](https://github.com/sany2k8)\n- Email: sany2k8@gmail.com\n\n## References\n- [FastAPI](https://fastapi.tiangolo.com/)\n- [SQLAlchemy](https://www.sqlalchemy.org/)\n- [Alembic](https://alembic.sqlalchemy.org/)\n- [Pydantic](https://pydantic-docs.helpmanual.io/)\n- [Python](https://www.python.org/)\n- [PostgreSQL](https://www.postgresql.org/)\n- [UV](https://astral.sh/uv/)\n- [JWT](https://jwt.io/)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falwayssany%2Fhealth-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falwayssany%2Fhealth-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falwayssany%2Fhealth-api/lists"}