# Cocktails RAG MCP Server

MCP tool for cocktail recommendations using RAG (Retrieval-Augmented Generation).

## Requirements

- **Python 3.11+**
- **uv package manager** - https://docs.astral.sh/uv/getting-started/installation/

## Quick Start

1. **Get Groq API key** (free): https://console.groq.com/keys

2. **Setup:**

   ```bash
   # Clone the repository
   git clone https://github.com/00200200/cocktails-rag-mcp.git
   cd cocktails-rag-mcp

   # Copy environment template
   cp .env.example .env

   # Edit .env and add your GROQ_API_KEY
   nano .env

   # Install dependencies
   uv sync
   ```

3. **Pre-download models (required):**

   Download embeddings and reranker models:

   ```bash
   uv run python -c "from src.rag.rag import RAG; RAG(); print('Models downloaed!')"
   ```

4. **Install for Claude Desktop:**

   ### Automatic (Recommended)

   ```bash
   uv run fastmcp install claude-desktop fastmcp.json --name cocktails --env-file .env
   ```

   ### Manual

   Edit config file:

   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

   ```json
   {
   	"mcpServers": {
   		"cocktails": {
   			"command": "uv",
   			"args": [
   				"run",
   				"--with","faiss-cpu",
   				"--with","fastmcp",
   				"--with","jq",
   				"--with","langchain",
   				"--with","langchain-community",
   				"--with","langchain-groq",
   				"--with","langchain-huggingface",
   				"--with","pandas",
   				"--with","python-dotenv",
   				"--with","sentence-transformers",
   				"fastmcp",
   				"run",
   				"/ABSOLUTE/PATH/TO/src/mcp/server.py:mcp"
   			],
   			"env": {
   				"GROQ_API_KEY": "your_groq_api_key_here"
   			}
   		}
   	}
   }
   ```

   Replace `/ABSOLUTE/PATH/TO/` with your project path and `GROQ_API_KEY` with your API key.

## Example Usage

<p align="center">
  <img src="assets/claude_example_1.png" width="600">
</p>

<p align="center">
  <img src="assets/claude_example_2.png" width="600">
</p>

## Local Testing

```bash
# Test RAG pipeline directly
uv run python -m src.rag.rag

# Test MCP server locally
uv run python src/mcp/server.py
```

## Development

### Code Formatting

```bash
# Format code with black
uv tool run black .

# Sort imports with isort
uv tool run isort .
```

## Project Structure

```
RAG/
├── src/
│   ├── mcp/         # MCP server implementation (FastMCP)
│   ├── rag/         # RAG pipeline (retrieve, rerank, generate)
│   ├── db/          # FAISS vector database handler
│   └── data/        # Data loading utilities
├── data/            # Cocktail dataset
├── faiss_index/     # Generated FAISS index (auto-created on first run)
├── notebooks/       # EDA notebook
├── fastmcp.json     # FastMCP configuration
├── pyproject.toml   # Project dependencies
└── .env.example     # Environment template
```

## Tech Stack

- **MCP Framework:** FastMCP
- **RAG Framework:** LangChain
- **Embeddings:** BAAI/bge-m3 (local via HuggingFace)
- **Vector DB:** FAISS (local)
- **Reranker:** BAAI/bge-reranker-v2-m3 (local via HuggingFace)
- **LLM:** Groq API (llama-3.1-8b-instant)
- **Package Manager:** uv