# Bar Assistant MCP Server

An MCP (Model Context Protocol) server for [Bar Assistant](https://barassistant.app/) - manage your home bar shelf and discover cocktails you can make.

## Features

- 📋 View ingredients on your bar shelf
- 🍸 See cocktails you can make with what you have
- ➕ Add ingredients to your shelf
- ➖ Remove ingredients from your shelf
- 🔍 Search for ingredients by name
- 🏪 Discover your available bars
- 🧪 Create new ingredients
- 🍹 Create new cocktail recipes
- ✏️ Update existing cocktail recipes

## Installation

### Using uvx (Recommended)

Run directly with uvx:

```bash
uvx --from git+https://github.com/the-real-py/bar-assistant-mcp bar-assistant-mcp \
  https://bar.johnprovost.com/bar/api \
  your_token_here \
  1
```

Or set environment variables in `.env` and run:

```bash
uvx --from git+https://github.com/the-real-py/bar-assistant-mcp bar-assistant-mcp
```

### Using pip

```bash
pip install git+https://github.com/the-real-py/bar-assistant-mcp
bar-assistant-mcp
```

## Configuration

Create a `.env` file in your project directory:

```bash
BAR_ASSISTANT_API_URL=https://bar.johnprovost.com/bar/api
BAR_ASSISTANT_TOKEN=your_bearer_token_here
BAR_ASSISTANT_BAR_ID=1
```

Or pass them as command-line arguments:

```bash
bar-assistant-mcp <api_url> <token> <bar_id>
```

### Getting Your Credentials

1. **API URL**: Your Bar Assistant instance URL + the API path
   - Standard setup: `http://localhost:8000/api`
   - Custom setup: Check your reverse proxy configuration (e.g., `https://bar.example.com/bar/api`)
2. **Token**: Generate a personal access token from your Bar Assistant profile settings
3. **Bar ID**: Use the `list_bars` tool to find your bar ID, or it's usually `1` for your first bar

**Important**: The `BAR_ASSISTANT_BAR_ID` is optional. If you don't set it, you can provide the `bar_id` parameter when calling tools, or use the `list_bars` tool first to discover your available bars.

## Usage with Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "bar-assistant": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/the-real-py/bar-assistant-mcp",
        "bar-assistant-mcp",
        "https://bar.johnprovost.com/bar/api",
        "your_token_here",
        "1"
      ]
    }
  }
}
```

Or using environment variables:

```json
{
  "mcpServers": {
    "bar-assistant": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/the-real-py/bar-assistant-mcp",
        "bar-assistant-mcp"
      ],
      "env": {
        "BAR_ASSISTANT_API_URL": "https://bar.johnprovost.com/bar/api",
        "BAR_ASSISTANT_TOKEN": "your_token_here",
        "BAR_ASSISTANT_BAR_ID": "1"
      }
    }
  }
}
```

## Available Tools

### `list_bars`
Discover all bars you have access to and get their IDs.

### `get_shelf_ingredients`
List all ingredients on your bar shelf.

**Parameters:**
- `bar_id` (optional): Bar ID to query
- `page` (optional): Page number for pagination

### `get_shelf_cocktails`
See all cocktails you can make with your current ingredients.

**Parameters:**
- `bar_id` (optional): Bar ID to query
- `page` (optional): Page number for pagination

### `add_ingredients_to_shelf`
Add ingredients to your shelf by their IDs.

**Parameters:**
- `ingredient_ids` (required): Array of ingredient IDs
- `bar_id` (optional): Bar ID to update

### `remove_ingredients_from_shelf`
Remove ingredients from your shelf.

**Parameters:**
- `ingredient_ids` (required): Array of ingredient IDs
- `bar_id` (optional): Bar ID to update

### `search_ingredients`
Search for ingredients by name to find their IDs.

**Parameters:**
- `name` (required): Ingredient name to search for
- `bar_id` (optional): Bar ID context

### `create_ingredient`
Create a new ingredient in the bar database. Use this when an ingredient doesn't exist and needs to be created before adding to a cocktail.

**Parameters:**
- `name` (required): Name of the ingredient
- `strength` (optional): Alcohol strength/percentage (e.g., 40 for 40% ABV)
- `description` (optional): Description of the ingredient
- `origin` (optional): Origin/country of the ingredient
- `color` (optional): Hex color code (e.g., '#ffffff')
- `parent_ingredient_id` (optional): Parent ingredient ID for categorization
- `units` (optional): Default units for this ingredient (e.g., 'ml', 'oz', 'dash')
- `bar_id` (optional): Bar ID context

### `create_cocktail`
Create a new cocktail recipe. First use `search_ingredients` to find ingredient IDs, then use `create_ingredient` for any missing ingredients.

**Parameters:**
- `name` (required): Name of the cocktail
- `instructions` (required): Step-by-step instructions for making the cocktail
- `ingredients` (required): Array of ingredients with:
  - `ingredient_id` (required): ID of the ingredient
  - `amount` (required): Amount of the ingredient
  - `units` (optional): Units for the amount (e.g., 'ml', 'oz', 'dash')
  - `optional` (optional): Whether this ingredient is optional
  - `note` (optional): Additional note for this ingredient
  - `sort` (optional): Sort order for the ingredient
- `description` (optional): Description of the cocktail
- `garnish` (optional): Garnish for the cocktail
- `source` (optional): Source/origin of the recipe
- `glass_id` (optional): ID of the glass type to use
- `method_id` (optional): ID of the mixing method (shaken, stirred, etc.)
- `tags` (optional): Array of tags for the cocktail
- `bar_id` (optional): Bar ID context

**Example - Creating a Margarita:**
```
1. search_ingredients(name="tequila") → ID: 45
2. search_ingredients(name="lime juice") → ID: 89  
3. search_ingredients(name="triple sec") → ID: 23
4. create_cocktail(
     name="Margarita",
     instructions="1. Add all ingredients to shaker with ice\n2. Shake well\n3. Strain into salt-rimmed glass",
     ingredients=[
       {"ingredient_id": 45, "amount": 60, "units": "ml"},
       {"ingredient_id": 89, "amount": 30, "units": "ml"},
       {"ingredient_id": 23, "amount": 30, "units": "ml"}
     ],
     garnish="Lime wheel, salt rim"
   )
```

### `update_cocktail`
Update an existing cocktail recipe. Use this to modify the name, instructions, ingredients, or other details of a cocktail.

**Parameters:**
- `id` (required): ID of the cocktail to update
- `name` (required): Name of the cocktail
- `instructions` (required): Step-by-step instructions for making the cocktail
- `ingredients` (required): Array of ingredients with:
  - `ingredient_id` (required): ID of the ingredient
  - `amount` (required): Amount of the ingredient
  - `units` (optional): Units for the amount (e.g., 'ml', 'oz', 'dash')
  - `optional` (optional): Whether this ingredient is optional
  - `note` (optional): Additional note for this ingredient
  - `sort` (optional): Sort order for the ingredient
- `description` (optional): Description of the cocktail
- `garnish` (optional): Garnish for the cocktail
- `source` (optional): Source/origin of the recipe
- `glass_id` (optional): ID of the glass type to use
- `method_id` (optional): ID of the mixing method (shaken, stirred, etc.)
- `tags` (optional): Array of tags for the cocktail
- `bar_id` (optional): Bar ID context

## Resources

- `bar://shelf/ingredients` - Your bar shelf ingredients
- `bar://shelf/cocktails` - Cocktails you can make

## Development

Clone and install in development mode:

```bash
git clone https://github.com/the-real-py/bar-assistant-mcp
cd bar-assistant-mcp
pip install -e .
```

## Troubleshooting

### Finding Your API URL

The Bar Assistant API URL depends on your setup:

1. **Standard Docker setup**: `http://localhost:8000/api`
2. **Custom reverse proxy**: Check your nginx/Traefik configuration for the API route
3. **Cloud hosted**: Usually provided by your hosting service

To verify your API URL is correct, run:
```bash
curl -H "Accept: application/json" YOUR_API_URL/server/version
```

You should get a JSON response with version information.

## License

MIT

## Links

- [Bar Assistant](https://barassistant.app/)
- [Bar Assistant Documentation](https://bar-assistant.github.io/docs/)
- [MCP Documentation](https://modelcontextprotocol.io/)