# 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 (75+)

#### Content Creation (10 tools)

| Tool                 | Description                                      |
| -------------------- | ------------------------------------------------ |
| `create_content`     | Generate an AI article from a keyword            |
| `get_content_status` | Poll article generation progress                 |
| `get_content`        | Retrieve generated article (paginated HTML)      |
| `export_content`     | Get full article HTML without truncation         |
| `update_content`     | Update title, content, meta, or target keyword   |
| `list_contents`      | List articles with filters                       |
| `delete_content`     | Delete an article                                |
| `publish_content`    | Push to connected CMS                            |
| `import_content`     | Import an article from a URL                     |
| `parse_brief`        | Parse a content brief into generation parameters |

#### 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 (6 tools)

| Tool                     | Description                    |
| ------------------------ | ------------------------------ |
| `get_link_stats`         | Link Engine stats              |
| `get_link_categories`    | List link categories           |
| `delete_link_category`   | Delete a link category         |
| `list_link_sites`        | List sites in Link Engine      |
| `update_link_site`       | Update link site config        |
| `bulk_update_link_sites` | Bulk update link site settings |
| `refresh_link_sitemaps`  | Refresh sitemap indexes        |

#### Meta & Models (3 tools)

| Tool                | Description                 |
| ------------------- | --------------------------- |
| `list_models`       | Available text models       |
| `list_image_models` | Available image models      |
| `chat`              | Brand-aware chat completion |

### MCP Resources

In addition to tools, the server exposes MCP resources that can be fetched directly to disk without entering the AI context window:

| Resource URI                  | MIME Type   | Description                                                              |
| ----------------------------- | ----------- | ------------------------------------------------------------------------ |
| `cuppa://content/{articleId}` | `text/html` | Full article HTML. Use with `FetchMcpResource` + `downloadPath` to save. |

**Cursor example** (saves full HTML to disk, no truncation):

```
FetchMcpResource({
  server: "cuppa",
  uri: "cuppa://content/<article-id>",
  downloadPath: "content/blog/my-article.html"
})
```

### 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learn.cuppa.ai/rest-api/mcp-read-me.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.