# MCP Read Me

## @cuppa-ai/mcp-server

Model Context Protocol (MCP) server for [Cuppa AI](https://cuppa.ai). Gives AI clients (Cursor, Claude Desktop, Windsurf, etc.) full access to Cuppa's content generation, SEO optimization, and brand management capabilities.

### Quick Start

#### 1. Get your API key

Go to [Cuppa Settings > API Keys](https://app.cuppa.ai/team/settings/api/keys) and create a key.

#### 2. Configure your MCP client

**Cursor** (`.cursor/mcp.json` in your project or global config):

```json
{
  "mcpServers": {
    "cuppa": {
      "command": "npx",
      "args": ["-y", "@cuppa-ai/mcp-server"],
      "env": {
        "CUPPA_API_KEY": "cpa-your-key-here"
      }
    }
  }
}
```

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "cuppa": {
      "command": "npx",
      "args": ["-y", "@cuppa-ai/mcp-server"],
      "env": {
        "CUPPA_API_KEY": "cpa-your-key-here"
      }
    }
  }
}
```

**Windsurf / Cline / other MCP clients**: Same pattern. Point to `npx -y @cuppa-ai/mcp-server` with `CUPPA_API_KEY` env var.

### Available Tools (70+)

#### Content Creation (6 tools)

| Tool                 | Description                           |
| -------------------- | ------------------------------------- |
| `create_content`     | Generate an AI article from a keyword |
| `get_content_status` | Poll article generation progress      |
| `get_content`        | Retrieve generated article            |
| `list_contents`      | List articles with filters            |
| `delete_content`     | Delete an article                     |
| `publish_content`    | Push to connected CMS                 |

#### Content Grading & SERP (5 tools)

| Tool                | Description                      |
| ------------------- | -------------------------------- |
| `grade_content`     | Trigger SEO/readability grading  |
| `get_content_grade` | Get grading results              |
| `fetch_serp_data`   | Trigger SERP competitor analysis |
| `get_serp_data`     | Get SERP analysis results        |
| `optimize_content`  | Get AI optimization suggestions  |

#### Projects / Bulk Generation (4 tools)

| Tool             | Description                    |
| ---------------- | ------------------------------ |
| `create_project` | Create bulk generation project |
| `list_projects`  | List projects                  |
| `get_project`    | Get project details            |
| `export_project` | Export project articles        |

#### Research (4 tools)

| Tool                   | Description                      |
| ---------------------- | -------------------------------- |
| `research_keywords`    | Keyword research from seed terms |
| `research_serp`        | SERP analysis for a keyword      |
| `research_competitors` | Competitor content analysis      |
| `research_cluster`     | Topic cluster research           |

#### Images (2 tools)

| Tool                   | Description                        |
| ---------------------- | ---------------------------------- |
| `generate_image`       | Generate an AI image               |
| `generate_images_bulk` | Bulk image generation for articles |

#### Brand & Knowledge (7 tools)

| Tool                        | Description                             |
| --------------------------- | --------------------------------------- |
| `get_brand`                 | Get Brand DNA for a site                |
| `update_brand_context`      | Update brand context fields             |
| `update_brand_visual_style` | Update colors, fonts, logo              |
| `get_notebook`              | List client notes / meeting transcripts |
| `list_knowledge`            | List knowledge sources                  |
| `create_knowledge`          | Create text knowledge source            |
| `get_knowledge`             | Get knowledge source details            |

#### Presets / AI Instructions (5 tools)

| Tool            | Description          |
| --------------- | -------------------- |
| `list_presets`  | List writing presets |
| `get_preset`    | Get preset details   |
| `create_preset` | Create a preset      |
| `update_preset` | Update a preset      |
| `delete_preset` | Delete a preset      |

#### Templates (2 tools)

| Tool             | Description           |
| ---------------- | --------------------- |
| `list_templates` | List custom templates |
| `get_template`   | Get template details  |

#### Clusters (5 tools)

| Tool                 | Description            |
| -------------------- | ---------------------- |
| `generate_cluster`   | Generate topic cluster |
| `list_clusters`      | List clusters          |
| `get_cluster`        | Get cluster details    |
| `activate_cluster`   | Add cluster to plan    |
| `deactivate_cluster` | Remove from plan       |

#### Content Planner & Strategy (7 tools)

| Tool                      | Description                                       |
| ------------------------- | ------------------------------------------------- |
| `list_planner`            | List planner items                                |
| `create_planner_item`     | Add to content plan                               |
| `update_planner_item`     | Update planner item                               |
| `delete_planner_item`     | Remove planner item                               |
| `get_content_calendar`    | Unified calendar (articles + local + social)      |
| `get_content_strategy`    | Get site content strategy settings                |
| `update_content_strategy` | Update article defaults, social, newsletter, etc. |

#### Performance Hub (4 tools)

| Tool                    | Description                                                   |
| ----------------------- | ------------------------------------------------------------- |
| `get_brand_performance` | KPIs, visibility score, and quick wins from Performance Hub   |
| `get_content_health`    | Top pages, content decay, striking distance, cannibalization  |
| `get_ai_visibility`     | LLM mentions, top prompts, cited pages, citation gaps         |
| `get_backlinks`         | Domain rating, backlink stats, referring domains (via Ahrefs) |

#### Newsletters (3 tools)

| Tool                  | Description                                        |
| --------------------- | -------------------------------------------------- |
| `list_newsletters`    | List generated newsletters for a site              |
| `get_newsletter`      | Get newsletter details with full content and HTML  |
| `generate_newsletter` | Generate weekly newsletter from published articles |

#### Social Media (12 tools)

| Tool                    | Description                                                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `generate_social`       | Generate social post (from article OR standalone topic)                                                                    |
| `generate_social_multi` | Multi-platform post generation                                                                                             |
| `publish_social`        | Publish to platform immediately                                                                                            |
| `schedule_social`       | Schedule a post for future publishing                                                                                      |
| `list_social_platforms` | List connected platforms with best practices                                                                               |
| `list_social_posts`     | List social posts with filters                                                                                             |
| `get_social_post`       | Get social post details (with analytics)                                                                                   |
| `update_social_post`    | Update draft/scheduled post                                                                                                |
| `delete_social_post`    | Delete draft/scheduled post                                                                                                |
| `get_social_analytics`  | Live social analytics: impressions, engagements, reach, followers, best posting times, content decay, top posts with links |
| `generate_carousel`     | Generate LinkedIn carousel slides                                                                                          |
| `publish_carousel`      | Publish carousel to LinkedIn                                                                                               |

#### Sites & GSC (3 tools)

| Tool              | Description             |
| ----------------- | ----------------------- |
| `list_sites`      | List sites/brands       |
| `create_site`     | Create a new site       |
| `get_gsc_queries` | Get Search Console data |

#### Research Agents (3 tools)

| Tool                | Description                   |
| ------------------- | ----------------------------- |
| `list_agents`       | List research agents          |
| `get_agent`         | Get agent with latest results |
| `trigger_agent_run` | Trigger manual agent run      |

#### Links & Infrastructure (5 tools)

| Tool                  | Description                 |
| --------------------- | --------------------------- |
| `get_link_stats`      | Link Engine stats           |
| `get_link_categories` | List link categories        |
| `list_models`         | Available text models       |
| `list_image_models`   | Available image models      |
| `chat`                | Brand-aware chat completion |

### Environment Variables

| Variable        | Required | Description                                             |
| --------------- | -------- | ------------------------------------------------------- |
| `CUPPA_API_KEY` | Yes      | Your Cuppa API key (starts with `cpa-`)                 |
| `CUPPA_API_URL` | No       | Override API base URL (default: `https://api.cuppa.ai`) |

### Plan Requirements

Some tools require specific plan tiers:

| Feature                    | Minimum Plan |
| -------------------------- | ------------ |
| Content generation, images | All plans    |
| Knowledge sources          | Power        |
| Custom templates           | Business     |
| Research agents            | Power        |
| Link Engine                | Business     |
| Brand Notebook             | Agency       |

### Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run locally
CUPPA_API_KEY=cpa-xxx node dist/bin/cli.js
```

### License

MIT