🩺 Clinisight

AI-assisted symptom analysis with PubMed-backed research — FastAPI + MCP server

Describe symptoms in plain language, get a possible diagnosis from GPT-4, and receive a summary grounded in recent PubMed abstracts.

Features · Quick Start · Usage · MCP Server · Project Structure

---

Disclaimer: Clinisight is an educational demo from the MCP Bootcamp. It is not a medical device and does not provide professional diagnosis or treatment advice. Always consult a qualified healthcare provider for real medical concerns.

---

✨ Features

Capability	Description
📝 Symptom extraction	Pulls known symptom keywords (headache, fever, nausea, fatigue, pain) from free-text descriptions
🧠 AI diagnosis	Uses GPT-4 to suggest possible conditions and general guidance from extracted symptoms
📚 PubMed lookup	Searches NCBI E-utilities for up to 3 relevant articles
📄 Research summary	GPT-4 summarizes fetched abstracts into a short, readable overview
🌐 REST API	FastAPI endpoint at POST /diagnosis for programmatic use
🔌 MCP integration	Exposes a single clinisight_ai tool for AI agents (Cursor, Claude Desktop, etc.)

---

🏗️ Architecture

flowchart TB
    subgraph Input["User Input"]
        A[Symptom description text]
    end

    subgraph Core["functions/"]
        B[extract_symptoms]
        C[get_diagnosis]
        D[fetch_pubmed_articles_with_metadata]
        E[summarize_text]
    end

    subgraph Interfaces["Entry points"]
        F[FastAPI app.py]
        G[MCP mcp_tool.py]
    end

    subgraph External["External Services"]
        H[(OpenAI GPT-4)]
        I[(NCBI PubMed E-utilities)]
    end

    A --> F
    A --> G
    F --> B
    G --> B
    B --> C
    B --> D
    D --> E
    C --> H
    E --> H
    D --> I

    style Input fill:#1E1E2E,stroke:#009688,color:#fff
    style Core fill:#1E1E2E,stroke:#412991,color:#fff
    style Interfaces fill:#1E1E2E,stroke:#326599,color:#fff
    style External fill:#1E1E2E,stroke:#97D700,color:#fff

Loading

---

📋 Prerequisites

Before you begin, make sure you have:

• Python 3.13+ (see .python-version)
• An OpenAI API key — used for diagnosis and abstract summarization
• uv (recommended) or pip for dependency management
• Network access to PubMed E-utilities (no separate PubMed API key required)

---

🚀 Quick Start

1. Enter the project

cd projects/clinisight

2. Install dependencies

Option A — uv (recommended)

uv sync

Option B — pip

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip install mcp   # MCP SDK (included in pyproject.toml when using uv)

3. Configure environment variables

Create a .env file in the project root:

OPENAI_API_KEY=sk-your-openai-key-here

⚠️ Never commit .env to version control. It is already listed in .gitignore.

4. Run the FastAPI server

uv run python app.py
# or
python app.py

The API listens on http://0.0.0.0:8000. Interactive docs: http://localhost:8000/docs.

---

📖 Usage

REST API

Endpoint: POST /diagnosis

Request body:

{
  "description": "I have had a bad headache and fever for two days with nausea."
}

Example with curl:

curl -X POST http://localhost:8000/diagnosis \
  -H "Content-Type: application/json" \
  -d '{"description": "headache, fever, and fatigue for 3 days"}'

Response:

{
  "symptoms": ["headache", "fever", "fatigue"],
  "diagnosis": "... GPT-4 generated text ...",
  "summary": "... GPT-4 summary of PubMed abstracts ..."
}

Processing pipeline

1. Extract — Regex matches supported symptom keywords in the input text.
2. Diagnose — GPT-4 (gpt-4) suggests possible conditions from the symptom list.
3. Research — PubMed is queried using the joined symptom terms; metadata (title, abstract, authors, date, URL) is parsed from XML.
4. Summarize — Abstracts are concatenated and summarized by GPT-4 for the summary field.

If PubMed returns no results or the request fails, the fetcher can fall back to mock article data so the pipeline still completes (see use_mock_if_empty in functions/pubmed_articles.py).

Supported symptom keywords

The extractor currently recognizes:

headache · fever · nausea · fatigue · pain

Extend the pattern in functions/symptom_extractor.py to support more terms.

---

🔌 MCP Server

Clinisight includes an MCP (Model Context Protocol) server built with FastMCP so AI assistants can run the full pipeline as a single tool.

Available tools

Tool	Parameters	Returns
clinisight_ai	symptom_text (string)	symptom, diagnosis, pubmed_summary

Run the MCP server

uv run python mcp_tool.py
# or
python mcp_tool.py

The server uses stdio transport by default.

Connect in Cursor

Add this to your Cursor MCP settings (.cursor/mcp.json or Settings → MCP):

{
  "mcpServers": {
    "clinisight": {
      "command": "uv",
      "args": ["run", "python", "mcp_tool.py"],
      "cwd": "/absolute/path/to/projects/clinisight",
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

Connect in Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "clinisight": {
      "command": "uv",
      "args": ["run", "python", "mcp_tool.py"],
      "cwd": "/absolute/path/to/projects/clinisight"
    }
  }
}

Ensure OPENAI_API_KEY is available in the environment (via .env when run from the project directory, or in the MCP config env block).

---

📁 Project Structure

clinisight/
├── app.py                      # FastAPI app — POST /diagnosis
├── mcp_tool.py                 # MCP server (stdio) — tool: clinisight_ai
├── pyproject.toml              # Project metadata & dependencies (uv)
├── requirements.txt            # Pip-compatible dependency list
├── uv.lock                     # Locked dependency versions
├── .env                        # API keys (local only — not committed)
├── .python-version             # Python version pin (3.13)
└── functions/
    ├── symptom_extractor.py    # Regex-based symptom keyword extraction
    ├── diagnos_symptoms.py     # OpenAI diagnosis from symptom list
    ├── pubmed_articles.py      # PubMed search + XML metadata parsing
    └── summerize_pubmed.py     # OpenAI abstract summarization

---

🛠️ Tech Stack

Layer	Technology
API	FastAPI + Uvicorn
LLM	OpenAI GPT-4
Literature	NCBI E-utilities (esearch + efetch)
HTML/XML parsing	BeautifulSoup4 + lxml
HTTP	requests
Agent protocol	MCP / FastMCP
Config	python-dotenv
Package manager	uv

---

⚙️ Configuration reference

Variable	Required	Description
OPENAI_API_KEY	✅	OpenAI API key for diagnosis and PubMed abstract summarization

---

🧪 Development

# Install deps
uv sync

# Run API server
uv run python app.py

# Run MCP server locally
uv run python mcp_tool.py

# Open API docs in browser
open http://localhost:8000/docs

---

📝 Notes

• Diagnosis and summaries are generative; quality depends on symptom extraction coverage and PubMed search results.
• PubMed requests use a standard browser User-Agent header; respect NCBI usage guidelines for rate limits in production.
• The MCP tool and REST API share the same functions/ modules but may format PubMed input to the summarizer slightly differently.
• Default OpenAI model is gpt-4 in both diagnosis and summarization modules.

---

📄 License

This project is part of the MCP Bootcamp — Next-Gen AI Agents course. Use and modify freely for learning purposes.

---

Built for learning how agents combine LLMs, APIs, and MCP