npm package: @mealmastery/mcp-server
Description: MCP server for MealMastery AI meal planning - integrate with Claude Desktop, ChatGPT, VS Code, and other AI agents
Author: MealMastery Inc.
Latest version: 0.2.4

# @mealmastery/mcp-server

MCP server for MealMastery AI meal planning. Integrates with Claude Desktop, VS Code Copilot, and other MCP-compatible AI agents.

## Philosophy

The MCP server is a **mirror of core capabilities**, not a place where new features debut. Its value proposition is:

> "Everything you can do in the app, you can now do through natural conversation in Claude."

The MCP layer adds convenience (natural language) and composability (chaining tools), but the underlying capabilities exist in the core product first. New features should be built as API endpoints powering the web/mobile apps, then exposed through MCP -- never the other way around.

## Setup

1. Get your API key from [MealMastery Settings](https://www.mealmastery.ai/settings)
2. Add to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "mealmastery": {
      "command": "npx",
      "args": ["-y", "@mealmastery/mcp-server"],
      "env": {
        "MEALMASTERY_API_KEY": "mm_live_..."
      }
    }
  }
}
```

## Features

### 24 Tools

Full CRUD for meal planning, recipes, grocery lists, and user preferences -- plus AI generation with streaming progress.

### 3 Resources (read-only context)

| Resource URI | Description |
|---|---|
| `mealmastery://meal-plan/current` | Latest meal plan with all meals and nutrition |
| `mealmastery://user/preferences` | Dietary preferences, allergies, skill level |
| `mealmastery://grocery-list/current` | Grocery list for the current meal plan |

### 4 Prompt Templates (guided workflows)

| Prompt | Description |
|---|---|
| `weekly-meal-prep` | Full week planning: generate plan, review, grocery list, checkout |
| `swap-meal` | Replace a meal in the current plan |
| `order-groceries` | Preview and send grocery list to Instacart/Kroger |
| `quick-dinner` | Single quick meal idea with time constraints |

### Streaming & Progress

The `generate_meal_plan` tool supports MCP progress notifications. Clients that send a `progressToken` receive real-time updates during AI generation (0-100% progress with status messages). Clients without progress support gracefully fall back to the non-streaming endpoint.

### Quota Awareness

API key quotas (daily request limits based on subscription tier) are reported on every token exchange. Free tier: 1,000 requests/day. Paid tier: 10,000 requests/day.

## Available Tools

### User Context
- **get_user_context** - Load full user profile, preferences, subscription, and latest plan
- **get_user_preferences** - Get dietary preferences and cooking settings
- **update_user_preferences** - Update dietary, allergy, or cuisine preferences
- **get_subscription_status** - Check subscription tier and usage limits
- **get_checkout_providers** - See connected grocery providers (Instacart, Kroger)
- **checkout_grocery_list** - Send a grocery list to Instacart or Kroger

### Meal Planning
- **generate_meal_plan** - Generate a personalized meal plan using AI (with streaming progress)
- **get_latest_meal_plan** - Get the current/most recent meal plan
- **get_meal_plan** - Get a specific meal plan by ID
- **list_meal_plans** - Browse meal plan history
- **regenerate_meal** - Replace one meal in a plan with a new AI-generated meal
- **generate_and_add_meal** - Add a new AI meal to a plan at a specific slot
- **remove_meal** - Remove a meal from a plan

### Recipes
- **search_recipes** - Search saved recipes
- **get_recipe** - Get full recipe details
- **save_meal_as_recipe** - Save a generated meal as a reusable recipe
- **get_favorite_recipes** - Get list of favorited recipes
- **favorite_meal** - Mark a meal as favorite
- **get_meal_ratings** - Get ratings for meals in a plan
- **get_all_ratings** - Get all-time recipe ratings

### Grocery
- **generate_grocery_list** - Create a grocery list from a meal plan
- **get_grocery_list** - Get a specific grocery list
- **list_grocery_lists** - Browse grocery list history
- **update_grocery_items** - Check off, exclude, or adjust grocery items

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `MEALMASTERY_API_KEY` | Yes | - | Your developer API key (`mm_live_...`) |
| `MEALMASTERY_API_URL` | No | `https://api.mealmastery.ai` | API base URL |

## Security

- API keys are exchanged for short-lived JWTs (15 min) -- never sent on data requests
- HTTPS enforced for all non-localhost connections
- Scope-based access control (read, write, checkout, admin)
- Per-key daily quotas enforced server-side
- Error messages sanitized -- no internal API details leak to the agent

## Development

```bash
npm install
npm run build
npm start
```