---
title: Aurora-MCP
emoji: 🌿
colorFrom: green
colorTo: indigo
sdk: docker
pinned: false
---

# 🌿 Aurora-MCP
**Model Context Protocol (MCP) server providing access to datasets of natural 
and synthetic small molecules, with a focus on identifying potential 
mitochondrial Complex I inhibitors that may occur in plant species.**

---

## 🔍 Overview

**Aurora-MCP** is a Model Context Protocol (MCP) server and data integration layer that connects natural-product, biodiversity, and mitochondrial-inhibitor datasets.
It enables LLMs and users to query relationships between plant species, small molecules, and mitochondrial Complex I inhibition—bridging COCONUT, Laji.fi, GBIF, 
and AI-derived PubMed data through structured joins and metadata schemas.

**Aurora-MCP** is a lightweight **MCP server + Hugging Face Space** designed to bridge two complementary knowledge sources:

1. 🌿 **[Aurora](https://github.com/ndaniel/aurora)** — natural-product and plant biodiversity data, mapping compounds to genera and species found in Nordic ecosystems.  
2. 🧬 **[Aurora-Mito-ETL](https://github.com/ndaniel/aurora-mito-etl)** — curated PubMed-derived corpus of small-molecule inhibitors of mitochondrial Complex I (NADH dehydrogenase).

Together they form a conversational dataset where **ChatGPT** (or any MCP-compatible LLM) can reason over structured biological data, ask questions, 
and perform targeted searches on small compounds, plants, and mechanistic links between them.

---

## 🧠 Concept

**Goal:** allow scientific dialogue with an LLM grounded in domain data, for example:

> *“Show me plant-derived compounds that inhibit mitochondrial Complex I.”*  
> *“Find PubMed evidence for arctigenin as a Complex I inhibitor.”*  
> *“List Nordic plants whose metabolites overlap with known ETC inhibitors.”*

Aurora-MCP turns your static text/TSV data into an **interactive semantic backend**, exposing programmatic tools for searching, linking, and reasoning.
 a FastAPI‑based MCP endpoint (`/mcp`) that ChatGPT (or any MCP‑aware client)
can connect to. It also provides `/healthz` for status checks and simple debug HTTP routes
for local testing.

---

## 🚀 Quick start (local)

```bash
# 1. Create a clean environment
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 2. Run the MCP HTTP server
uvicorn mcp_server.server:app --host 0.0.0.0 --port 7860

# 3. Check health
curl -s http://127.0.0.1:7860/healthz | jq

# 4. Optional: test the debug routes
curl -s 'http://127.0.0.1:7860/debug/list_files?path=data' | jq
```

You should see something like:

```json
{
  "ok": true,
  "mcp": "mounted at /mcp",
  "tools": ["list_files","read_text"]
}
```

---

## 🧠 Using with ChatGPT (MCP)

1. Deploy this repository to a **Hugging Face Space** (Docker SDK).  
2. Wait until the Space is running and `/healthz` returns 200 OK:  
   `https://huggingface.co/spaces/<you>/<space>/healthz`
3. In ChatGPT → **Settings → Connectors / MCP → Add Server**
   - **Server URL:** `https://huggingface.co/spaces/<you>/<space>/mcp`
4. Open a new chat and try for example:
   - `list_files(path="data")`
   - `read_text(path="README.md")`
   - (Aurora domain tools can be added similarly.)

---

## 🐳 Docker (for Hugging Face Spaces)

```dockerfile
FROM python:3.12-slim

WORKDIR /app
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 PIP_NO_CACHE_DIR=1

RUN apt-get update && apt-get install -y --no-install-recommends     build-essential curl ca-certificates  && rm -rf /var/lib/apt/lists/*

COPY requirements.txt .
RUN pip install --upgrade pip && pip install -r requirements.txt

COPY . .
EXPOSE 7860
ENV PORT=7860

HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=5   CMD curl -fsS http://127.0.0.1:${PORT}/healthz || exit 1

CMD ["uvicorn","mcp_server.server:app","--host","0.0.0.0","--port","7860"]
```

---

## 🧩 Architecture overview

| Component | Description |
|------------|-------------|
| **FastAPI app** | Hosts the `/mcp` streaming endpoint and `/healthz` check |
| **FastMCP** | MCP server layer that exposes Python functions as MCP tools |
| **Tools** | Simple functions (`list_files`, `read_text`, etc.) that can be called by MCP clients |
| **Aurora domain** | (Future) plant‑compound and inhibitor analytics from your Aurora ETL data |

---

## 📂 Project layout

```
aurora-mcp/
├── mcp_server/
│   ├── server.py          # FastAPI + FastMCP entrypoint
│   ├── tools/
│   │   └── files.py       # Example tools (list_files, read_text)
│   └── __init__.py
├── data/                  # Local data (ignored by git)
├── requirements.txt
├── Dockerfile
├── huggingface.yaml
└── README.md
```

---

## ✅ Health & debug routes

| Endpoint | Purpose |
|-----------|----------|
| `/healthz` | lightweight JSON health check |
| `/debug/list_files` | list directory contents (no MCP) |
| `/debug/read_text` | read a file as plain text |

---

## ⚙️ Requirements

```
fastapi>=0.119
uvicorn>=0.37
mcp>=0.17.0
pydantic>=2.11.9
pandas>=2.3.3
```

Install with:

```bash
pip install -r requirements.txt
```

---

## 🧱 Hugging Face Space metadata

```yaml
# huggingface.yaml
title: Aurora-MCP
sdk: docker
emoji: 🌿
colorFrom: green
colorTo: indigo
pinned: false
```

---

## 🔍 Troubleshooting

| Symptom | Cause / Fix |
|----------|--------------|
| `GET /mcp` → 307/500 | Normal; only MCP clients can connect |
| `Task group is not initialized` | Fixed by FastMCP startup hook |
| `ModuleNotFoundError: mcp.server.fastapi` | Install correct SDK: `pip install mcp fastapi uvicorn` |
| `healthz` returns nothing | Curl 127.0.0.1 not 0.0.0.0 |

---

**Author:** Daniel Nicorici · University of Helsinki  
**License:** GNU GPL v3  
**URL:** https://github.com/ndaniel/aurora-mcp