# CarouselMCP

An [MCP](https://modelcontextprotocol.io) server that generates a ready-to-post Instagram
carousel — a "notebook paper" style set of PNG slides — from nothing but a topic string.
Deployed as a single AWS Lambda function behind a public Function URL, with generated images
stored in S3.

## What it does

One tool, `generate_skill_carousel`, takes a `topic` and returns a finished carousel:

```json
{
  "name": "generate_skill_carousel",
  "arguments": { "topic": "python libraries every data engineer should know" }
}
```

A single AI call — Gemini or Claude, whichever key is available — does all the creative work at
once:

- **Picks the layout itself.** Most topics get the default **list** layout: a hook slide, four
  grid pages of items, and a closing slide (6 slides, up to 32 items total). A genuine two-sided
  topic ("Claude pros and cons", "remote work advantages and disadvantages") is automatically
  routed to the **pros_cons** layout instead — hook, a green PROS slide, a red CONS slide, a
  verdict slide, a recap slide, and closing. This is a semantic decision by the model, not
  keyword matching on the topic string.
- **Decides how many items the topic actually supports** — it won't pad a thin topic out to a
  fixed count.
- **Grounds the content in a real web search** (Google Search via Gemini, or Claude's built-in
  `web_search` tool) instead of writing from the model's own unverified memory.

Every icon is a built-in flat vector glyph — there's no AI image generation anywhere in the
pipeline, and none is needed. No background image, hero photo, reference image, or custom
theme/colors are accepted as input; the paper-texture background, fonts, and doodle accents are
all fixed. That's a deliberate trim, not a missing feature — `topic` (plus an optional API key
override) is the entire input surface.

## Requirements

- **One of** `GEMINI_API_KEY` or `ANTHROPIC_API_KEY` (env var, or pass `geminiApiKey` /
  `claudeApiKey` per call to override). Gemini is tried first if both are present. If neither is
  available or both fail, it falls back to placeholder text rather than failing the whole call.
  - Note: Claude has no image-generation API and isn't used for one here — it's only ever used
    for the text content, same as Gemini's role in this pipeline.
- **`OUTPUT_BUCKET`** — an S3 bucket the function can write PNGs to (defaults to `my-custom-mcp`
  in code; override for your own bucket).
- **`MCP_API_KEY`** — shared secret every caller must send. Fails closed: a missing or wrong key
  is rejected with `401` before any model call or S3 write happens, so a bad key never costs
  anything.
- **Bundled fonts.** Lambda has no system fonts, and image rendering needs real font files —
  `fonts/NotoSans-Regular.ttf`, `fonts/NotoSans-Bold.ttf`, and `fonts/fonts.conf` are committed in
  this repo and must ship inside the deployment package, with `FONTCONFIG_PATH=/var/task/fonts`
  set as an environment variable.

## Deploying

### Option A — one command, via AWS SAM

```bash
sam build --use-container
sam deploy --guided
```

**`--use-container` matters here** — `sharp` (the image library this uses) ships a native binary
compiled for a specific OS/architecture. Building without a container compiles against whatever
machine you're running `sam build` on; building in a container cross-compiles against Lambda's
actual Linux runtime, avoiding a broken/mismatched native binary at runtime.

`--guided` prompts for the stack name, region, and the two parameters (`GeminiApiKey` /
`AnthropicApiKey` — provide at least one; both are `NoEcho`) on first run, then remembers your
answers in `samconfig.toml`.

### Option B — manual, via the Lambda console

1. `npm install`.
2. Zip the folder's **contents** (not the folder itself) — `index.mjs`, `node_modules`,
   `package.json`, `package-lock.json`, and the `fonts/` folder all need to sit at the zip's top
   level.
3. **Create function** → author from scratch → Node.js 22+ → upload the zip.
4. **Configuration → General configuration**: raise Timeout (this one's deployed at ~2 minutes)
   and Memory (deployed at 256 MB — image compositing needs more headroom than plain text
   generation).
5. **Configuration → Environment variables**: `MCP_API_KEY`, `OUTPUT_BUCKET`, `FONTCONFIG_PATH`
   (`/var/task/fonts`), and at least one of `GEMINI_API_KEY` / `ANTHROPIC_API_KEY`.
6. **Permissions**: attach `s3:GetObject`, `s3:PutObject`, `s3:PutObjectAcl`, and
   `s3:DeleteObject` on your output bucket — the function reads, writes, and can clean up its own
   generated objects.
7. **Configuration → Function URL**: create one with Auth type `NONE`. `MCP_API_KEY`, checked
   inside the handler, is the real gate — `NONE` here only means AWS isn't checking IAM
   signatures.

## Testing it directly

```bash
curl -s https://<your-function-url> \
  -H "x-api-key: <MCP_API_KEY>" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl -s https://<your-function-url> \
  -H "x-api-key: <MCP_API_KEY>" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"generate_skill_carousel","arguments":{"topic":"python libraries every data engineer should know"}}}'
```

The response includes both a text summary and `structuredContent` with the topic, slide count,
and the direct S3 URLs for each generated PNG.

## Connecting an MCP client

```bash
claude mcp add --transport http carousel https://<your-function-url> \
  --header "x-api-key: <MCP_API_KEY>"
```

## Project structure

```
index.mjs   — everything: carousel generation, image rendering, S3 I/O, JSON-RPC dispatch
fonts/      — fonts bundled into the deployment package (no system fonts on Lambda)
package.json
```

## Security note

`MCP_API_KEY`, `GEMINI_API_KEY`, and `ANTHROPIC_API_KEY` are all plain environment variables —
never hardcode them in `index.mjs`. Rotate all three if this function's configuration was ever
shown on screen (a demo, a screen recording).