Paprika MCP Server

# Paprika MCP Server A Model Context Protocol (MCP) server for the Paprika Recipe Manager, allowing AI assistants to search, read, and update recipes. ## Features - **Search Recipes**: Search across recipe titles, ingredients, categories, directions, and notes with context - **Read Recipes**: Get full recipe data including all metadata, ingredients, and directions - **Update Recipes**: Safely update recipe fields using find/replace (requires user confirmation) ## Prerequisites 1. Python 3.10 or higher (Python 3.13 recommended) 2. A Paprika account with recipes 3. Node.js (for pre-commit hooks, optional) ## Quick Start Run the setup script to install everything and configure credentials: ```bash cd paprika-mcp ./setup.sh ``` This will: 1. Install paprika-mcp with dependencies 2. Set up pre-commit hooks (if npm available) ## Manual Installation If you prefer manual setup: ### 1. Install paprika-recipes ```bash cd ../paprika-recipes python3 -m venv .venv source .venv/bin/activate pip install -e . deactivate ``` ### 2. Install paprika-mcp ```bash cd ../paprika-mcp python3 -m venv .venv source .venv/bin/activate pip install -e ".[dev]" ``` ### 3. Configure credentials **Option 1: Interactive setup** ```bash source .venv/bin/activate paprika-mcp setup ``` **Option 2: Manual config file** Create `~/.paprika-mcp/config.json`: ```json { "email": "your@email.com", "password": "yourpassword" } ``` Set permissions: ```bash chmod 600 ~/.paprika-mcp/config.json ``` **Option 3: Environment variables** ```bash export PAPRIKA_EMAIL="your@email.com" export PAPRIKA_PASSWORD="yourpassword" ``` ## Credential Management The server uses a credential flow designed for MCP stdio transport: **Priority order:** 1. `PAPRIKA_EMAIL` and `PAPRIKA_PASSWORD` environment variables 2. `~/.paprika-mcp/config.json` file **Note**: This server manages credentials independently from the paprika-recipes CLI tool's keyring storage. This simplifies the credential flow for MCP stdio transport where the process is spawned by the AI app. ## User-Agent If you have Paprika for Mac installed, the fork of the `paprika-recipes` Python package should automatically create a suitable User-Agent string. Otherwise, you might have to set the `PAPRIKA_USER_AGENT` environment variable or the "user_agent" property in `config.json`. ## Usage ### As an MCP Server Add to your MCP client configuration (e.g., Claude Desktop's `~/Library/Application Support/Claude/claude_desktop_config.json`): ```json { "mcpServers": { "paprika": { "command": "/Users/yourusername/Developer/paprika-mcp/.venv/bin/paprika-mcp" } } } ``` Or use environment variables: ```json { "mcpServers": { "paprika": { "command": "/Users/yourusername/Developer/paprika-mcp/.venv/bin/paprika-mcp", "env": { "PAPRIKA_EMAIL": "your@email.com", "PAPRIKA_PASSWORD": "yourpassword" } } } } ``` ### Available Tools #### format_fraction Format a fraction string to unicode fraction characters. **This tool is local-only** and doesn't require Paprika server connectivity - useful for testing. **Parameters:** - `fraction` (required): Fraction in the form "numerator/denominator" (e.g., "1/4", " 31 / 200 "), or already formatted unicode **Features:** - Handles already-formatted unicode fractions (returns them as-is) - Strips whitespace from input - Converts common fractions to dedicated unicode characters - Composes complex fractions using superscript/subscript digits **Examples:** ```json { "fraction": "1/4" } ``` Returns: `¼` ```json { "fraction": " 31 / 200 " } ``` Returns: `³¹⁄₂₀₀` (whitespace stripped) ```json { "fraction": "¼" } ``` Returns: `¼` (already formatted, returned as-is) Common fractions (1/4, 1/2, 3/4, 1/3, 2/3, etc.) use dedicated Unicode characters. Complex fractions are composed using superscript numerator + fraction slash (⁄) + subscript denominator. #### search_recipes Search for recipes by text across multiple fields. **Parameters:** - `query` (required): Text to search for - `fields` (optional): Array of fields to search in: `["name", "ingredients", "categories", "directions", "notes"]` - `context_lines` (optional): Number of context lines around matches (default: 2) **Example:** ```json { "query": "chicken", "fields": ["name", "ingredients"], "context_lines": 2 } ``` #### read_recipe Read full recipe data by ID or title. **Parameters:** - `id` or `title` (one required): Recipe UUID or exact recipe name **Note:** Title matching uses Unicode normalization (NFD), so it works correctly with accented characters regardless of their unicode representation (e.g., "café" will match "café"). **Example:** ```json { "id": "RECIPE-UUID-HERE" } ``` or ```json { "title": "Chocolate Chip Cookies" } ``` ### User Preferences (Prompts) You can provide context to the AI about how you want it to work with your recipes by creating a `~/.paprika-mcp/prompt.md` file. This will be automatically loaded as a prompt when the MCP server starts. **Example prompt file:** ```markdown # Recipe Management Preferences - Always preserve source URLs and attribution - Prefer metric measurements - I'm cooking for 2 people typically - I avoid peanuts (allergy) - Categorize using: Breakfast, Lunch, Dinner, Desserts, Snacks ``` See [`prompt.example.md`](prompt.example.md) for a complete template. #### update_recipe Update a recipe field using find/replace. **⚠️ DANGEROUS**: This tool modifies recipe data. User confirmation is recommended before execution. **Parameters:** - `id` (required): Recipe UUID - `field` (required): Field to update (name, ingredients, directions, notes, etc.) - `find` (required): Text to find - `replace` (required): Text to replace with - `regex` (optional): Treat find pattern as regex (default: false) **Example:** ```json { "id": "RECIPE-UUID-HERE", "field": "ingredients", "find": "1 cup sugar", "replace": "3/4 cup sugar" } ``` ### Code Changes and Rebuilding The package is installed in **editable mode** (`pip install -e .`), so: - **✓ No rebuild needed**: Changes to `.py` files are immediately available - **⚠️ Restart required**: MCP clients cache the stdio process - restart VS Code or your MCP client to pick up changes - **↻ Reinstall needed**: Only for `pyproject.toml` or entry point changes Force reinstall if needed: ```bash .venv/bin/pip install -e . --force-reinstall --no-deps ``` ### Pre-commit Hooks Pre-commit hooks run automatically via Husky when you commit. They: 1. Only run on staged Python files 2. Run isort, black, and ruff 3. Auto-fix issues and re-stage files To install hooks manually: ```bash npm install ``` ## Security Notes - Credentials are stored in plain text in `~/.paprika-mcp/config.json` - Environment variables (`PAPRIKA_EMAIL`, `PAPRIKA_PASSWORD`) are also supported ## License MIT ## Credits Built on top of [paprika-recipes](https://github.com/briantkatch/paprika-recipes) originally by Adam Coddington.