# 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

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

## Quick Start

```bash
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:

```text
http://127.0.0.1:8000/docs
```

Ask a grounded question:

```bash
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:

```bash
make mcp
```

The server exposes:

- `search_documents`
- `answer_question`
- `summarize_document`
- `extract_patient_timeline`
- `redact_phi`

Example Claude Desktop style configuration:

```json
{
  "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](docs/API.md) for examples.

## Evaluation

Seed the sample index and run the retrieval smoke evaluation:

```bash
make seed
python scripts/evaluate_retrieval.py
```

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

## Configuration

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

Optional OpenAI support:

```env
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.