Medical GraphRAG Assistant

A production-ready medical AI assistant platform built on Model Context Protocol (MCP), featuring GraphRAG multi-modal search, FHIR integration, and AWS Bedrock Claude Sonnet 4.5.

Originally forked from: FHIR-AI-Hackathon-Kit

What This Is

This is an agentic medical chat platform that uses:

• 🤖 Model Context Protocol (MCP) - Claude autonomously calls medical search tools

• 🧠 GraphRAG - Knowledge graph-based retrieval with entity and relationship extraction

• 🏥 FHIR Integration - Full-text search of clinical documents

• ☁️ AWS Bedrock - Claude Sonnet 4.5 with multi-iteration tool use

• 📊 Interactive UI - Streamlit interface with execution transparency

• 🗄️ InterSystems IRIS - Vector database with GraphRAG tables

Quick Start

1. Run the Streamlit Chat Interface

Visit http://localhost:8501 and start chatting!

2. Use as MCP Server (Claude Desktop, etc.)

Architecture

Features

MCP Tools (6 total)

1. search_fhir_documents - Full-text search of clinical notes

2. get_entity - Retrieve specific medical entities by ID

3. search_entities_by_type - Find entities by type (Condition, Medication, etc.)

4. get_entity_relationships - Get all relationships for an entity

5. search_relationships_by_type - Find relationships by type (treats, causes, etc.)

6. hybrid_search - Combined vector + graph search with relevance ranking

Chat Interface Features

• ✅ Execution Transparency - See which tools Claude calls and its reasoning

• ✅ Interactive Charts - Generate visualizations from data

• ✅ Conversation History - Multi-turn conversations with context

• ✅ Error Handling - Graceful handling of API issues with detailed logs

• ✅ Max Iterations Control - Prevents infinite loops (10 iteration limit)

• ✅ Type-Safe Content Processing - Robust handling of mixed content formats

Current Version: v2.10.2

Recent Improvements:

• Fixed "'str' object has no attribute 'get'" error with proper type checking

• Increased max iterations from 5 → 10 for complex queries

• Added execution details with expandable UI

• Improved error messages with context

Configuration

Required Environment Variables

Config Files

• config/fhir_graphrag_config.yaml - Local development config

• config/fhir_graphrag_config.aws.yaml - AWS deployment config

• config/aws-config.yaml - AWS infrastructure settings

Project Structure

Technology Stack

AI/ML:

• AWS Bedrock (Claude Sonnet 4.5)

• NVIDIA NIM Embeddings (1024-dim vectors)

• Model Context Protocol (MCP)

Database:

• InterSystems IRIS (Vector DB + GraphRAG tables)

• Native VECTOR(DOUBLE, 1024) support

• COSINE similarity search

Infrastructure:

• AWS EC2 (for IRIS database)

• Python 3.10+

• Streamlit for UI

Key Libraries:

• intersystems-irispython - IRIS native client

• boto3 - AWS SDK

• streamlit - Chat UI

• mcp - Model Context Protocol SDK

Example Queries

Try these in the chat interface:

FHIR Search:

• "Find patients with chest pain"

• "Search for diabetes cases"

• "Show recent emergency visits"

GraphRAG:

• "What medications treat hypertension?"

• "Show me the relationship between conditions and procedures"

• "What are the side effects of metformin?"

Hybrid Search:

• "Find treatment options for chronic pain" (combines vector + graph search)

Visualization:

• "Show a chart of conditions by frequency"

• "Graph the most common medications"

Development

Running Tests

Debug Mode

Enable debug logging:

Troubleshooting

See docs/troubleshooting.md for common issues.

Common Issues:

• AWS credentials not configured → Set AWS_PROFILE or AWS env vars

• IRIS connection failed → Check IRIS_HOST and credentials

• Max iterations reached → Query may be too complex, try simplifying

Documentation

• Architecture Overview - System design and data flow

• Deployment Guide - AWS deployment instructions

• MCP Server Complete - MCP implementation details

• Development History - Session notes and findings

Contributing

This project is based on the FHIR-AI-Hackathon-Kit. The original tutorial content remains in the tutorial/ directory.

License

Inherits license from upstream FHIR-AI-Hackathon-Kit repository.

Acknowledgments

• Original Project: FHIR-AI-Hackathon-Kit by gabriel-ing

• InterSystems IRIS for the vector database platform

• AWS Bedrock for Claude Sonnet 4.5 access

• Model Context Protocol by Anthropic