# Beansmile Deck MCP

> An MCP server that lets any AI agent generate on-brand Beansmile HTML decks
> (presentation slides). It packages the Beansmile deck design system — voice,
> tokens, and slide templates — into MCP tools, resources, and a prompt.

This file is written for an AI agent / MCP client. If a user pasted this URL and asked
you to "connect" or "set up" this MCP, configure the server below into the user's client,
then tell them how to verify it. After it's connected, follow the deck workflow at the
bottom to actually build decks.

## Connection

- **Endpoint**: `https://deck-mcp.beansmile.ai/mcp`
- **Transport**: `streamable-http` (HTTP)
- **Auth**: header `Authorization: Bearer <YOUR_TOKEN>` on every request to `/mcp`
- **Server name to register**: `beansmile-deck`
- **Public assets**: `/_assets/*` (fonts, CSS, brand assets) are public and need no token.
  Only `/mcp` (POST/GET/DELETE) requires the Bearer token.

### Getting a token

The user must register and get an API Key first:
1. Go to `https://deck-mcp.beansmile.ai/account/`, sign up with email + password.
2. Verify the email via the link sent to them — this issues their API Key.
3. The API Key is shown on the account page (and can be regenerated there). Use it as `<YOUR_TOKEN>`.

If the user has not done this yet, point them to the account page before configuring.

### Add to a client

Replace `<YOUR_TOKEN>` with the user's API Key in every snippet below.

**Claude Code**

```
claude mcp add --transport http beansmile-deck https://deck-mcp.beansmile.ai/mcp \
  --header "Authorization: Bearer <YOUR_TOKEN>"
```

**Generic MCP client (JSON)**

```json
{
  "mcpServers": {
    "beansmile-deck": {
      "type": "http",
      "url": "https://deck-mcp.beansmile.ai/mcp",
      "headers": { "Authorization": "Bearer <YOUR_TOKEN>" }
    }
  }
}
```

**OpenClaw (小龙虾)** — edit `~/.openclaw/openclaw.json` (create it if missing), add under
`mcp.servers`, then restart OpenClaw (or run `openclaw doctor --fix`):

```json
{
  "mcp": {
    "servers": {
      "beansmile-deck": {
        "url": "https://deck-mcp.beansmile.ai/mcp",
        "transport": "streamable-http",
        "headers": { "Authorization": "Bearer <YOUR_TOKEN>" }
      }
    }
  }
}
```

**Hermes (爱马仕)** — edit `~/.hermes/config.yaml`, add under `mcp_servers`, then run
`/reload-mcp` in a Hermes chat and verify with `hermes mcp test beansmile-deck`:

```yaml
mcp_servers:
  beansmile-deck:
    url: "https://deck-mcp.beansmile.ai/mcp"
    headers:
      Authorization: "Bearer <YOUR_TOKEN>"
```

## Tools

- `get_deck_design_guide()` — the full deck authoring guide: voice & tone, the 1920×1080
  slide canvas, background variants, type and component classes, visual rules, do/don'ts.
  Read this before building.
- `get_deck_tokens(theme?)` — design tokens as JSON: brand color, color ramps, deck
  background values, type scale, spacing, radii, shadows, motion. `theme` defaults to `beansmile`.
- `list_themes()` — available deck visual themes (skins): id, name, description.
- `list_slide_templates()` — the 13 Beansmile slide templates: id, title, description,
  and when to use each.
- `get_slide_template(template_id)` — raw HTML for one slide template, with placeholder
  comments left to fill.
- `create_deck(title, slides?, lang?, theme?)` — assembles a complete deck `index.html`
  from an ordered list of slide template ids, with page numbers and asset URLs wired up;
  returns the HTML. `lang` defaults to `zh-CN`; `theme` defaults to `beansmile`.

## Prompt

- `build-beansmile-deck(topic?, audience?)` — primes the workflow for building an on-brand deck.

## Resources

- `beansmile-deck://guide` (text/markdown) — the full deck authoring guide.
- `beansmile-deck://tokens` (application/json) — design tokens.
- `beansmile-deck://example/aida-yun-geo` (text/html) — a reference 22-slide deck built with this system.
- `beansmile-deck://template/{id}` (text/html) — HTML for one slide template (ids from `list_slide_templates`).

## Workflow — build a deck

1. Call `get_deck_design_guide` to absorb the voice and visual rules.
2. Call `list_slide_templates` and pick an ordered set of templates that tells the story.
3. Call `create_deck` with the title and the ordered slide list — you get the assembled HTML.
4. Write the HTML to a `.html` file and fill in each `<!-- ... -->` placeholder with real content.
5. Open it in a browser to present: arrow keys to page, press **F** for fullscreen.