diff --git a/README.md b/README.md index 694f801..0fb37c7 100644 --- a/README.md +++ b/README.md @@ -14,189 +14,233 @@ Transform medical data analysis with AI! Ask questions about MIMIC-IV data in plain English and get instant insights. Choose between local demo data (free) or full cloud dataset (BigQuery). -## โจ Features +## Features -- ๐ **Natural Language Queries**: Ask questions about MIMIC-IV data in plain English -- ๐ **Local SQLite**: Fast queries on demo database (free, no setup) -- โ๏ธ **BigQuery Support**: Access full MIMIC-IV dataset on Google Cloud -- ๐ **Enterprise Security**: OAuth2 authentication with JWT tokens and rate limiting -- ๐ก๏ธ **SQL Injection Protection**: Read-only queries with comprehensive validation +- **Natural Language Queries**: Ask questions about MIMIC-IV data in plain English +- **Local SQLite**: Fast queries on demo database (free, no setup) +- **BigQuery Support**: Access full MIMIC-IV dataset on Google Cloud +- **Enterprise Security**: OAuth2 authentication with JWT tokens and rate limiting +- **SQL Injection Protection**: Read-only queries with comprehensive validation ## ๐ Quick Start -> ๐ก **Need more options?** Run `m3 --help` to see all available commands and options. +> ๐บ **Prefer video tutorials?** Check out [step-by-step video guides](https://rafiattrach.github.io/m3/) covering setup, PhysioNet configuration, and more. -### ๐ฆ Installation +### Install uv (required for `uvx`) -Choose your preferred installation method: +We use `uvx` to run the MCP server. Install `uv` from the official installer, then verify with `uv --version`. -#### Option A: Install from PyPI (Recommended) - -**Step 1: Create Virtual Environment** +**macOS and Linux:** ```bash -# Create virtual environment (recommended) -python -m venv .venv -source .venv/bin/activate # Windows: .venv\Scripts\activate +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +**Windows (PowerShell):** +```powershell +powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` -**Step 2: Install M3** +Verify installation: ```bash -# Install M3 -pip install m3-mcp +uv --version ``` -#### Option B: Docker +### BigQuery Setup (Optional - Full Dataset) -```bash -# Clone repo first -git clone https://github.com/rafiattrach/m3.git && cd m3 +**Skip this if using SQLite demo database.** -# SQLite (demo DB) -docker build -t m3:lite --target lite . -docker run -d --name m3-server m3:lite tail -f /dev/null +1. **Install Google Cloud SDK:** + - macOS: `brew install google-cloud-sdk` + - Windows/Linux: https://cloud.google.com/sdk/docs/install -# BigQuery (full dataset - requires GCP credentials) -docker build -t m3:bigquery --target bigquery . -docker run -d --name m3-server \ - -e M3_BACKEND=bigquery \ - -e M3_PROJECT_ID=YOUR_PROJECT_ID \ - -v $HOME/.config/gcloud:/root/.config/gcloud:ro \ - m3:bigquery tail -f /dev/null -``` +2. **Authenticate:** + ```bash + gcloud auth application-default login + ``` + *Opens your browser - choose the Google account with BigQuery access to MIMIC-IV.* + +### MCP Client Configuration + +Paste one of the following into your MCP client config, then restart your client. + +**Supported clients:** [Claude Desktop](https://www.claude.com/download), [Cursor](https://cursor.com/download), [Goose](https://block.github.io/goose/), and [more](https://github.com/punkpeye/awesome-mcp-clients). + +
| + +**SQLite (Demo Database)** + +Free, local, no setup required. -**MCP client config** (Claude Desktop, LM Studio, etc.): ```json { "mcpServers": { "m3": { - "command": "docker", - "args": ["exec", "-i", "m3-server", "python", "-m", "m3.mcp_server"] + "command": "uvx", + "args": ["m3-mcp"], + "env": { + "M3_BACKEND": "sqlite" + } } } } ``` -Stop container: `docker stop m3-server && docker rm m3-server` +*Demo database (136MB, 100 patients, 275 admissions) downloads automatically on first query.* -#### Option C: Install from Source + | +-#### Using standard `pip` -**Step 1: Clone and Navigate** -```bash -# Clone the repository -git clone https://github.com/rafiattrach/m3.git -cd m3 -``` +**BigQuery (Full Dataset)** -**Step 2: Create Virtual Environment** -```bash -# Create virtual environment -python -m venv .venv -source .venv/bin/activate # Windows: .venv\Scripts\activate -``` +Requires GCP credentials and PhysioNet access. -**Step 3: Install M3** -```bash -# Install M3 -pip install . +```json +{ + "mcpServers": { + "m3": { + "command": "uvx", + "args": ["m3-mcp"], + "env": { + "M3_BACKEND": "bigquery", + "M3_PROJECT_ID": "your-project-id" + } + } + } +} ``` -#### Using `UV` (Recommended) -Assuming you have [UV](https://docs.astral.sh/uv/getting-started/installation/) installed. +*Replace `your-project-id` with your Google Cloud project ID.* -**Step 1: Clone and Navigate** -```bash -# Clone the repository -git clone https://github.com/rafiattrach/m3.git -cd m3 -``` + | +
| -3. **Restart your MCP client** and ask: +**SQLite:** +```bash +git clone https://github.com/rafiattrach/m3.git && cd m3 +docker build -t m3:lite --target lite . +docker run -d --name m3-server m3:lite tail -f /dev/null +``` - - "What tools do you have for MIMIC-IV data?" - - "Show me patient demographics from the ICU" + | +-#### Option B: BigQuery (Full Dataset) +**BigQuery:** +```bash +git clone https://github.com/rafiattrach/m3.git && cd m3 +docker build -t m3:bigquery --target bigquery . +docker run -d --name m3-server \ + -e M3_BACKEND=bigquery \ + -e M3_PROJECT_ID=your-project-id \ + -v $HOME/.config/gcloud:/root/.config/gcloud:ro \ + m3:bigquery tail -f /dev/null +``` -**For researchers needing complete MIMIC-IV data** + | +