Healthcare Document Intelligence RAG + MCP

Production-ready starter project for healthcare document intelligence using retrieval-augmented generation, medical document pipelines, PHI-aware preprocessing, a FastAPI service, and an MCP server for agent extensibility.

Highlights

• Healthcare-focused ingestion for clinical notes, discharge summaries, lab reports, and policy documents
• PHI redaction layer before indexing and prompt construction
• Hybrid retrieval with deterministic local embeddings by default and optional OpenAI embeddings
• Citation-grounded answers with document, section, and page metadata
• FastAPI REST API with OpenAPI docs at /docs
• MCP server exposing document search, patient timeline extraction, summarization, and evidence QA tools
• Docker, Compose, tests, linting, and GitHub Actions CI
• Offline sample dataset so reviewers can run the project without vendor keys

Architecture

documents
  -> parser
  -> PHI redactor
  -> medical chunker
  -> embedding model
  -> vector index
  -> retriever
  -> grounded response
        |-> FastAPI
        |-> MCP tools

Quick Start

cd healthcare-document-intelligence-rag-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
make seed
make test
make api

Open:

http://127.0.0.1:8000/docs

Ask a grounded question:

curl -X POST http://127.0.0.1:8000/query \
  -H "Content-Type: application/json" \
  -d '{"question":"What follow-up is recommended after discharge?","top_k":4}'

MCP Server

Run the MCP server locally:

make mcp

The server exposes:

• search_documents
• answer_question
• summarize_document
• extract_patient_timeline
• redact_phi

Example Claude Desktop style configuration:

{
  "mcpServers": {
    "healthcare-document-intelligence": {
      "command": "python",
      "args": ["-m", "meddoc_intel.mcp.server"],
      "cwd": "/absolute/path/to/healthcare-document-intelligence-rag-mcp"
    }
  }
}

API

Core endpoints:

• GET /health
• POST /documents
• POST /query
• POST /summaries
• POST /redact
• GET /documents

See docs/API.md for examples.

Evaluation

Seed the sample index and run the retrieval smoke evaluation:

make seed
python scripts/evaluate_retrieval.py

The evaluation uses expected-document recall for simple, reviewable regression checks. See docs/ML_PIPELINE.md.

Configuration

The default setup uses deterministic local embeddings, which are ideal for demos, CI, and reproducible tests.

Optional OpenAI support:

EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-...
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

This project is a developer portfolio and prototyping system. It is not medical advice, not a diagnostic device, and not a substitute for professional clinical judgment.