Metadata-Version: 2.4
Name: suppevo-data-mcp
Version: 0.1.0
Summary: MCP server for the Suppevo supplement-tracking platform API
Project-URL: Homepage, https://github.com/GomezMera-IO-LLC/suppevo-data-mcp
Project-URL: Repository, https://github.com/GomezMera-IO-LLC/suppevo-data-mcp
Project-URL: Issues, https://github.com/GomezMera-IO-LLC/suppevo-data-mcp/issues
Author: GomezMera IO LLC
License-Expression: MIT
Keywords: health,mcp,suppevo,supplements
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

# Suppevo MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that exposes the Suppevo supplement-tracking platform API as tools for AI assistants.

## Features

| Category | Description |
|----------|-------------|
| **Profile** | Manage user profiles and preferences |
| **Products** | CRUD, bulk operations, search (admin + public) |
| **Supplements** | Track user supplement routines |
| **Schedules** | Dosing schedules with reminders |
| **Doses** | Log and query dose history |
| **Reviews** | Create, moderate, and browse reviews |
| **Rewards** | Points, badges, streaks, challenges |
| **Brands** | Brand management and discovery |
| **Brand Owners** | Brand owner portal tools |
| **Ingredients** | CRUD, search, bulk ops, intelligence |
| **Ingredient Intelligence** | Alternatives, interactions, dosing guides, effectiveness |
| **Biomarkers** | Admin and public biomarker data |
| **Evidence Links** | Scientific evidence management |
| **Benefits** | Health benefit categories |
| **Scoring** | Product and ingredient scoring |
| **Stack Analysis** | Analyze supplement stacks |
| **Suggestions** | User and admin suggestion workflows |
| **News** | Public news feed |
| **Exports** | Data export tools |
| **Admin** | User groups, brand assignments |

## Quick Start

### Prerequisites

- Python 3.11+
- A Suppevo API token (JWT from Cognito)

### Install from PyPI

```bash
pip install suppevo-mcp
```

Or run directly with `uvx` (no install needed):

```bash
uvx suppevo-mcp
```

### Install from source

```bash
git clone https://github.com/GomezMera-IO-LLC/suppevo-data-mcp.git
cd suppevo-data-mcp
pip install -e .
```

## Configuration

The server loads environment variables from `~/.env` (your home directory). This keeps credentials out of project files and version control.

### Setup your `~/.env`

Create or edit `~/.env`:

```bash
# Suppevo MCP Server
SUPPEVO_API_TOKEN=your-jwt-token-here
SUPPEVO_REFRESH_TOKEN=your-refresh-token-here
SUPPEVO_CLIENT_ID=your-cognito-client-id
# SUPPEVO_API_BASE_URL=https://dev.api.suppevo.com/
# SUPPEVO_COGNITO_REGION=us-east-1
```

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `SUPPEVO_API_TOKEN` | Yes | — | JWT access token for authenticated endpoints |
| `SUPPEVO_REFRESH_TOKEN` | No | — | Cognito refresh token for auto-renewal |
| `SUPPEVO_CLIENT_ID` | No | — | Cognito app client ID (needed for token refresh) |
| `SUPPEVO_API_BASE_URL` | No | `https://dev.api.suppevo.com/` | API base URL |
| `SUPPEVO_COGNITO_REGION` | No | `us-east-1` | AWS region for Cognito |

> **Note:** Environment variables passed directly (e.g. via MCP client `env` config) take precedence over values in `~/.env`.

### Getting your API token

1. Sign in to the Suppevo app
2. Retrieve your JWT token from the authenticated session (IdToken from Cognito)
3. Optionally grab the refresh token and client ID for automatic token renewal

## MCP Client Setup

### Kiro

Add to `.kiro/settings/mcp.json`:

```json
{
  "mcpServers": {
    "suppevo": {
      "command": "uvx",
      "args": ["suppevo-mcp"]
    }
  }
}
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "suppevo": {
      "command": "uvx",
      "args": ["suppevo-mcp"]
    }
  }
}
```

> Credentials are loaded automatically from `~/.env` — no need to put tokens in MCP config files.

### Running from source (development)

If you cloned the repo and want to point your MCP client at the local code:

```json
{
  "mcpServers": {
    "suppevo": {
      "command": "python3",
      "args": ["-m", "suppevo_mcp"],
      "cwd": "/path/to/suppevo-data-mcp"
    }
  }
}
```

## Usage

Once configured, your AI assistant will have access to all Suppevo tools. Examples:

- "Search for magnesium supplements"
- "Show my current supplement stack"
- "Log a dose of Vitamin D — 5000 IU taken this morning"
- "What are the interactions for ashwagandha?"
- "Create a new product called 'Omega-3 Fish Oil' in the heart category"
- "Show my points balance and current streak"

### Public vs Authenticated Tools

- **Public tools** (prefixed with `public_`) work without authentication and are read-only
- **Authenticated tools** require `SUPPEVO_API_TOKEN` and provide full CRUD access
- **Admin tools** require an admin-level token for write operations on products, brands, ingredients, etc.

## Token Refresh

If you provide `SUPPEVO_REFRESH_TOKEN` and `SUPPEVO_CLIENT_ID`, the server will automatically refresh expired access tokens via AWS Cognito. This prevents interruptions during long sessions.

Without a refresh token, you'll see a 401 error when the token expires and will need to update the token in your MCP config and restart.

## Development

```bash
# Install in editable mode
pip install -e .

# Run the server directly
python3 -m suppevo_mcp

# Test with MCP inspector
npx @modelcontextprotocol/inspector python3 -m suppevo_mcp
```

## Transport

The server uses **stdio** transport by default, which is the standard for MCP client integrations.

## License

MIT
