# svmmon-mcp

Generate TikTok slideshows from Claude (and any MCP client) using your [Svmmon](https://app.svmmonapp.com) account.

This is a thin, local **stdio MCP server** that wraps Svmmon's public `/api/v1` REST API. Install it, paste your key, and ask Claude to make slideshows in plain language. It adds no business logic — every tool maps 1:1 onto a real Svmmon endpoint.

> **Requires an active subscription.** The API works on any active paid plan (per-tier volume caps still apply). Install always works; the tools return a clean "requires an active subscription" message until you paste a valid paid key.

---

## Quickstart

### 1. Get your key

app.svmmonapp.com → **Settings → API Keys → Svmmon API → Generate key** (any paid plan). It looks like `svm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`.

> Treat this key like a password. If it's ever exposed, revoke it instantly in **Settings → API Keys** — the MCP can't revoke it for you.

### 2. Add the server

**Claude Desktop** — edit `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "svmmon": {
      "command": "npx",
      "args": ["-y", "svmmon-mcp"],
      "env": { "SVMMON_API_KEY": "svm_your_key_here" }
    }
  }
}
```

**Claude Code:**

```bash
claude mcp add svmmon -e SVMMON_API_KEY=svm_your_key_here -- npx -y svmmon-mcp
```

### 3. Ask

> *Generate 5 hooks for my Marcus profile and make a slideshow from the best one.*

---

## Tools

| Tool | What it does |
|---|---|
| `get_usage` | Full usage: tier + plan, slideshows used/cap, AI credits, rerolls, shorts/face-swap caps, account caps, per-account TikTok inbox slots. |
| `list_profiles` | Your profiles with `id`, `name`, `niche`, `ready`, `missing`, `tiktok_linked`. Only `ready` profiles can generate. |
| `list_presets` | Valid `preset_id` values for slideshow generation. |
| `generate_hooks` | Scored hook candidates for a profile. Spends AI credits, so it is **confirm-gated** (see below). May return fewer than requested if your AI-credit cap is hit. |
| `generate_slideshow` | Generates ONE slideshow (consumes one from your monthly cap — **not idempotent**, **confirm-gated**). Returns a 24h download link; optionally delivers to TikTok/Telegram. |
| `generate_image` | Studio image generation on your own provider key (BYOK — **not idempotent**, **confirm-gated**). |
| `generate_video` | Studio video generation on your own provider key (BYOK — **not idempotent**, **confirm-gated**). |
| `recreate_slideshow` | Remake a public TikTok slideshow in one of your profile voices. Costs **2 slideshows + 2 AI credits** (**confirm-gated**). Async: returns a `job_id`, then poll. |
| `get_recreate_status` | Poll a recreation by `job_id`. Free. Returns the recreated hook and slides once complete. |
| `cancel_recreate` | Abandon an in-flight recreation (**confirm-gated**). Not a refund — see below. |
| `list_slideshows` | Your recent slideshows. |
| `get_slideshow` | Fetch a slideshow + a fresh 1h download link by id. |
| `list_collections` | Your image collections with per-collection image-fatigue health tiers. |
| `get_collection` | One collection's images, with optional 10-min signed URLs so a vision agent can inspect them. |
| `get_brain` | Your personal brain for a profile — patterns, voice DNA, next-hook directions (Growth+). |
| `get_community_brain` | The anonymized community brain — what's working across accounts. |
| `get_performance` | Post performance — views/likes/shares/comments, day-1 + final. |
| `get_tiktok_insights` | Live TikTok profile + recent-video stats (Growth+). |
| `list_studio_providers` | Studio model catalog + which of your provider keys unlock what. |
| `list_studio_history` | Recent studio generations (metadata; provider source URLs may be expired). |
| `list_studio_saves` | Your saved studio generations. |
| `list_connections` | Your connected TikTok accounts + live connection health (needs_reconnect, connection_error). |
| `list_automations` | Your automations — active state, schedule, delivery mode, hook source, hook count, last run status. |
| `get_automation` | One automation's full detail by id. |
| `get_schedule` | Your posting schedule — every slot's time, days, timezone, and which automation fires it. |
| `get_profile` | One profile's full detail — bio, audience, tone, CTA, hashtags, readiness, linked accounts/automations. |
| `get_profile_hooks` | A profile's hook library — text, status, source, used_count, virality_score. |
| `get_trending` | Globally trending TikTok posts (not account-specific) — optional hashtag/days filter. |

### Write tools

Every write tool is **two-step confirm-gated**: the first call returns a preview of the exact consequence and cost and does nothing; you must call again with `confirm: true` to execute. Surface the preview to the user before confirming.

The four `generate_*` tools above are confirm-gated the same way, because they spend money — a slideshow slot, AI credits, or your own provider credits. They also need a **write-scoped** API key, exactly like the tools in this table.

### Recreate is asynchronous

`recreate_slideshow` is the one tool that does not finish in a single call. It costs **2 slideshows + 2 AI credits** (double a normal generate, because it scrapes the source post and runs a vision read on top of writing the deck) and takes 1-4 minutes, so it returns a `job_id` immediately rather than polling inline — a client-side tool timeout mid-poll would otherwise lose the only handle on a run that may already have spent quota.

- Poll `get_recreate_status` with that `job_id` every ~10 seconds. Never call `recreate_slideshow` again to check on a running job; that starts a second paid recreation.
- Only one recreation runs at a time per account, shared with the dashboard. A second start returns 429 and spends nothing.
- A failure with `error.status` **422** means the URL was not a slideshow, and that case **never billed**. Other failures are refunded automatically.
- **`cancel_recreate` is not a refund.** It only stops the run if the worker has not reached its charge checkpoint. Land it later and the credits are already spent.

| Tool | What it does |
|---|---|
| `upload_images` | Upload base64 images (max 20) into an owned collection. Counts against your image-storage cap. |
| `add_hooks` | Add manual hooks (max 50) to a profile's hook library. |
| `remove_hook` | Permanently delete one hook from a profile's library (**irreversible**). |
| `update_profile` | Edit a profile's safe voice/CTA/hashtag/product fields. Preview shows a current → new diff. |
| `deliver_slideshow` | Re-post an already-generated slideshow to TikTok/Telegram — **no** AI call and **no** monthly quota spent. Uses a TikTok inbox slot. |
| `run_automation` | Run an automation now — **spends 1 slideshow + AI credits** and posts LIVE. Cannot be undone. |

---

## Configuration

| Env var | Required | Default | Notes |
|---|---|---|---|
| `SVMMON_API_KEY` | Yes | — | Your `svm_` key. Read from env only — never passed on the command line. |
| `SVMMON_BASE_URL` | No | `https://app.svmmonapp.com` | Override only for self-host/staging. |

---

## Troubleshooting

- **"key is missing, invalid, or revoked" (401)** — Set `SVMMON_API_KEY` to a current key from Settings → API Keys.
- **"requires an active subscription" (403)** — Subscribe at app.svmmonapp.com/subscribe. Any active paid plan works.
- **"a usage cap was reached" (402)** — You hit your monthly slideshow or AI-credit cap. Run `get_usage`.
- **"Rate limited" (429)** — Wait the suggested time if one is shown; otherwise it's a daily AI limit that resets at midnight UTC. The message tells you which.

---

## Versioning

`1.x` targets the Svmmon `/api/v1` contract. A breaking API change (`/api/v2`) would ship as `2.x`.

## Security

This package handles a live, cost-bearing credential. It reads the key from the environment only, never logs it, never puts it in process arguments, and never echoes it in errors. It performs no auto-retries on cost-burning calls. Report security issues to support@svmmonapp.com.

## License

MIT