# Cardiology Knowledge Graph MCP Server

A Model Context Protocol (MCP) server that creates and queries a cardiology knowledge graph using Neo4j and LLM-powered entity extraction.

## Features

- 📚 **Document Ingestion**: Process PDF files or raw text to extract cardiology entities and relationships
- 🧠 **LLM-Powered Extraction**: Uses GPT-4 (or customizable models like BioGPT) for intelligent extraction
- 📊 **Knowledge Graph**: Stores data in Neo4j with proper relationships
- 🔍 **Natural Language Queries**: Query the graph using plain English
- ✏️ **Human-in-the-Loop**: Review and edit extractions before adding to graph
- 📈 **Graph Analytics**: Get statistics and insights about your knowledge graph

## Prerequisites

### 1. Neo4j Setup
- **Option A (Recommended)**: Download [Neo4j Desktop](https://neo4j.com/download/) for Mac
  - Create a new database with these credentials:
    - URI: `bolt://localhost:7687`
    - Username: `neo4j`
    - Password: `password` (or your choice)
  - Start the database

- **Option B**: Use [Neo4j Aura](https://neo4j.com/cloud/aura/) (free cloud instance)
  - Update connection details in your environment variables

### 2. API Key
- Get an OpenAI API key from [OpenAI Platform](https://platform.openai.com/api-keys)
- Or set up alternative models (see Configuration section)

## Installation

1. **Clone and setup**:
   ```bash
   git clone <your-repo>
   cd "Cardiology Knowledge Graph MCP"
   ```

2. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

3. **Set up environment variables**:
   ```bash
   cp .env.example .env
   # Edit .env with your actual values
   ```

4. **Test the server**:
   ```bash
   python mcp_server.py
   ```

## Claude Desktop Configuration

1. **Find your Claude Desktop config**:
   - Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Create the file if it doesn't exist

2. **Add the MCP server configuration**:
   ```json
   {
     "mcpServers": {
       "cardiology-kg": {
         "command": "python",
         "args": ["/full/path/to/your/mcp_server.py"],
         "env": {
           "NEO4J_URI": "bolt://localhost:7687",
           "NEO4J_USERNAME": "neo4j",
           "NEO4J_PASSWORD": "your-password",
           "OPENAI_API_KEY": "your-openai-key"
         }
       }
     }
   }
   ```

3. **Restart Claude Desktop** and look for the 🔨 hammer icon to confirm the server is connected.

## Usage

### 1. Document Ingestion

**Process a PDF file**:
```
Ingest this cardiology document: /path/to/cardiology-textbook-chapter.pdf
```

**Process raw text**:
```
Ingest this cardiology note: "Patient presents with atrial fibrillation. Echocardiogram shows left ventricular hypertrophy. Prescribed metoprolol for rate control."
```

The system will:
- Extract entities (conditions, medications, procedures, anatomy)
- Identify relationships (causes, treats, affects, etc.)
- Return a draft JSON for your review

### 2. Review and Edit Extractions

After ingestion, you'll get a draft like:
```json
{
  "entities": [
    {"name": "atrial fibrillation", "label": "Condition", "properties": {}},
    {"name": "metoprolol", "label": "Medication", "properties": {"class": "beta-blocker"}}
  ],
  "relationships": [
    {"source": "metoprolol", "target": "atrial fibrillation", "type": "TREATS", "properties": {"purpose": "rate control"}}
  ]
}
```

Edit as needed, then add to graph:
```
Add this to my knowledge graph: [paste your edited JSON]
```

### 3. Query the Knowledge Graph

Ask natural language questions:
```
What medications treat atrial fibrillation?
How does left ventricular hypertrophy affect cardiac function?
Show me all conditions that cause heart failure.
What procedures are used to diagnose coronary artery disease?
```

### 4. Graph Management

**Get statistics**:
```
Show me statistics about my cardiology knowledge graph
```

**Clear the graph** (caution!):
```
Clear my knowledge graph
```

## Advanced Configuration

### Using Alternative LLMs

**BioGPT (specialized medical model)**:
```python
# Uncomment in mcp_server.py:
from langchain_huggingface import HuggingFaceHub
llm = HuggingFaceHub(repo_id="microsoft/BioGPT")
```

**Local Ollama model**:
```python
# Uncomment in mcp_server.py:
from langchain_community.llms import Ollama
llm = Ollama(model="llama2")  # or "biomedical-llm"
```

### Custom Entity Types and Relationships

Edit the extraction prompt in `mcp_server.py` to focus on specific:
- Anatomical structures
- Drug classes
- Diagnostic criteria
- Treatment protocols

### Integration with Neo4j Official MCP Servers

Install additional Neo4j MCP servers for enhanced capabilities:
```bash
pip install mcp-neo4j-cypher mcp-neo4j-memory
```

Add to Claude config:
```json
{
  "mcpServers": {
    "cardiology-kg": { /* your custom server */ },
    "neo4j-cypher": {
      "command": "mcp-neo4j-cypher",
      "args": ["--db-url", "bolt://localhost:7687", "--user", "neo4j", "--password", "password"]
    }
  }
}
```

## Example Workflow

1. **Start with a textbook chapter**:
   ```
   Ingest this PDF: /Users/you/Downloads/cardiac-physiology-chapter.pdf
   ```

2. **Review the extraction** - you might see entities like:
   - Anatomy: "left ventricle", "aortic valve"
   - Processes: "cardiac cycle", "systole", "diastole"
   - Relationships: "systole FOLLOWS atrial contraction"

3. **Edit and refine** the JSON to add missing details or correct relationships

4. **Add to graph**:
   ```
   Add this to my knowledge graph: [your refined JSON]
   ```

5. **Query for insights**:
   ```
   Explain the cardiac cycle based on my knowledge graph
   What anatomical structures are involved in systole?
   How do beta-blockers affect the cardiac cycle?
   ```

## Troubleshooting

### Common Issues

**"Connection refused" error**:
- Ensure Neo4j database is running
- Check connection details in environment variables

**"API key not found"**:
- Verify OPENAI_API_KEY is set correctly
- Check Claude Desktop config environment variables

**"Module not found" errors**:
- Run `pip install -r requirements.txt` again
- Check Python virtual environment

**MCP server not appearing in Claude**:
- Verify the full path to `mcp_server.py` in config
- Restart Claude Desktop completely
- Check logs in Claude Desktop (Help → Show Logs)

### Logs and Debugging

The server logs helpful information. To see detailed logs:
```bash
python mcp_server.py 2>&1 | tee server.log
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Acknowledgments

- Built on the Model Context Protocol by Anthropic
- Uses Neo4j for graph database capabilities
- Powered by LangChain for LLM integration
- Inspired by medical informatics and knowledge representation research