MCP_INTEGRATION.md

# MCP Integration Guide

This guide explains how to connect the Spice Bae MCP server to various AI clients.

## Overview

Spice Bae exposes its tools via the Model Context Protocol (MCP), allowing AI assistants like Cline and Claude Desktop to query spice information, nutritional data, and health benefits directly.

**MCP Endpoint**: `https://mcp-1st-birthday-spice-bae.hf.space/gradio_api/mcp/sse`

## Prerequisites

- Node.js 18+ installed
- `npx` available in your PATH
- The Spice Bae Space deployed on Hugging Face

## Connecting with Cline (VS Code)

### Step 1: Locate the Settings File

Cline stores MCP server configurations in `cline_mcp_settings.json`. The location varies by OS:

- **Windows**: `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
- **macOS**: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
- **Linux**: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`

### Step 2: Add the Server Configuration

Edit `cline_mcp_settings.json` and add:

```json
{
  "mcpServers": {
    "medicinal-cuisine": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp-1st-birthday-spice-bae.hf.space/gradio_api/mcp/sse"
      ]
    }
  }
}
```

Note: The `-y` flag auto-confirms npx prompts.

### Step 3: Restart Cline

Restart VS Code or reload the Cline extension for changes to take effect.

## Connecting with Claude Desktop

### Step 1: Locate the Settings File

Claude Desktop stores configurations in:

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

### Step 2: Add the Server Configuration

Edit `claude_desktop_config.json` and add:

```json
{
  "mcpServers": {
    "medicinal-cuisine": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp-1st-birthday-spice-bae.hf.space/gradio_api/mcp/sse"
      ]
    }
  }
}
```

Note: The `-y` flag auto-confirms npx prompts.

### Step 3: Restart Claude Desktop

**Important**: You must completely quit Claude Desktop and reopen it (not just close the window). On macOS, use Cmd+Q or right-click the dock icon and select Quit. On Windows, ensure Claude is fully closed from the system tray.

## Available Tools

Once connected, the following tools are available:

| Tool | Parameters | Description |
|------|------------|-------------|
| `get_spice_information` | `spice_name: str` | Get comprehensive spice data with nutrients |
| `get_nutrient_content` | `spice_name: str, nutrient_name: str` | Get specific nutrient content |
| `compare_spices` | `spice1: str, spice2: str` | Side-by-side nutritional comparison |
| `list_available_spices` | None | List all 88+ spices in the database |
| `get_health_benefits` | `spice_name: str` | Get health benefits from NCCIH |
| `get_safety_info` | `spice_name: str` | Get side effects and cautions |
| `find_substitute_spices` | `spice_name: str` | Find nutritionally similar alternatives |
| `find_spices_for_condition` | `condition: str` | Find spices for a health condition |

## Example Queries

After connecting, you can ask your AI assistant questions like:

- "What are the health benefits of turmeric?"
- "Compare the nutritional content of cinnamon and ginger"
- "Find spices that may help with inflammation"
- "What are the side effects of taking too much garlic?"
- "List all available spices in the database"
- "What can I substitute for cumin in a recipe?"

## Troubleshooting

### Connection Errors

1. **Verify the Space is running**: Visit your Hugging Face Space URL directly
2. **Check the endpoint**: Ensure you're using `/gradio_api/mcp/sse` (not `/gradio_api/mcp/`)
3. **Install mcp-remote**: Run `npm install -g mcp-remote` if npx fails

### Tool Not Found

1. Restart your AI client after adding the configuration
2. Check JSON syntax in the settings file
3. Verify the Space has finished building

### Rate Limiting

The server includes guardrails:
- 10 requests per minute per session
- 100 requests per day per session

If you hit rate limits, wait a moment before retrying.

## Security Notes

- The MCP server is read-only and cannot modify any data
- All responses include medical disclaimers
- No personal data is collected or stored
- API usage is tracked for cost control only

## References

- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)
- [Gradio MCP Server Guide](https://www.gradio.app/guides/mcp-server)
- [mcp-remote Package](https://www.npmjs.com/package/mcp-remote)