# digital-fireplace-mcp

> Brought to you by **[Good Feels](https://shop.getgoodfeels.com)** · _shop.getgoodfeels.com_

An MCP server (and a self-hosted gallery) for **34 embeddable pixel-art digital fireplaces**.

Each fireplace is a single-file HTML page that renders a tiny living scene — a stone hearth, a CRT yule log, a sparkler, a slow-burning joint, a phoenix egg, a plasma reactor — and pins a small Good Feels attribution to the bottom-right. Embed any of them with one `<iframe>` snippet, anywhere.

```
classic-hearth   wood-stove       campfire         joint-tray
yule-log         crystal-cave     space-stove      tiki-torch
lava-lamp        cabin-window     mystic-brazier   jack-o-lantern
menorah          birthday-candle  sparkler         new-years
bonfire-beach    forge-anvil      sun-disc         volcano
aurora           dragon-mouth     phoenix-egg      lightsaber
solar-flare      welding-arc      gas-stove        furnace-coal
tea-light        match-strike     cigar-ashtray    incense
bong-cherry      firefly-jar
```

CC0. Take it, fork it, theme it, ship it.

---

## What's in the box

- **`public/fireplaces/*.html`** — 34 self-contained fireplace pages
- **`public/lib/fire.js`** — the shared fire engine (Doom 1993 fire algorithm + 7 swappable palettes + a `FireCrackle` WebAudio synth)
- **`public/lib/chrome.js`** — shared sponsor footer + tap-to-start audio gate
- **`public/index.html`** — "The Hearth Picker" gallery, a live grid of all 34 with embed code modal
- **`public/server.js`** — minimal Node static server (no framework deps)
- **`src/index.ts`** — MCP server exposing 7 tools

## Quick start

```bash
# Install + build
npm install
npm run build

# Run the static gallery on http://127.0.0.1:4700
npm run serve

# Run the MCP server (stdio)
npm start
```

Open <http://127.0.0.1:4700> to browse the picker. Click any tile's **embed** button to get a turnkey iframe snippet for your own site.

## Embed anywhere

```html
<iframe
  src="https://your-host/fireplaces/joint-tray.html"
  width="800" height="500"
  frameborder="0"
  allow="autoplay"
  title="Good Feels · digital fireplace"
  style="border:none;"
></iframe>
<!-- brought to you by Good Feels · shop.getgoodfeels.com -->
```

## MCP tools

Wire into your Claude Code, Cursor, or any MCP-compatible client by adding to its `mcpServers` config:

```json
"digital-fireplace": {
  "command": "node",
  "args": ["/absolute/path/to/digital-fireplace-mcp/dist/index.js"],
  "type": "stdio",
  "env": { "FIREPLACE_SERVER_URL": "http://127.0.0.1:4700" }
}
```

| Tool | What it does |
|---|---|
| `fireplace_list_styles` | Catalog of all 34 fireplaces with mood, palette, tags, URL |
| `fireplace_get_html` | Raw HTML for one fireplace (optionally bundled with `fire.js` / `chrome.js` for self-hosting) |
| `fireplace_get_embed_code` | Turnkey `<iframe>` snippet with sponsor comment |
| `fireplace_get_url` | Live URL for a specific fireplace |
| `fireplace_random` | Surprise pick |
| `fireplace_get_gallery_url` | URL of the picker grid |
| `fireplace_recommend` | Free-form vibe → top-3 matches by tag scoring |

Example: _"recommend a fireplace for a winter night sci-fi stream"_ → `crystal-cave`, `space-stove`, `aurora`.

## How the fire engine works

The shared `PixelFire` class implements the classic Doom 1993 fire algorithm. For every pixel from bottom row to top, it copies from the row below with a small random horizontal offset and decays the palette index by 0–3. The hot source row at the bottom plus randomized decay produces a beautiful living flame that costs almost nothing to render.

Each fireplace picks a palette and (optionally) a mask + custom source row to shape the fire. Crystal Cave uses a cool blue palette. Plasma Reactor masks the fire to a circle. Gas Stove punches 12 hot zones into the source row to make discrete jets. Sun Disc and Solar Flare use a mostly-white solar palette.

Some fireplaces (`lava-lamp`, `aurora`, `lightsaber`, `firefly-jar`, `joint-tray`, `bong-cherry`, `incense`, `match-strike`, `birthday-candle`, `new-years`) use entirely custom CSS / canvas particle systems instead — picked when the Doom-fire approach didn't fit the subject.

## Palettes

`hearth` · `crystal` · `ember` · `mystic` · `plasma` · `tiki` · `lava` · `forge` · `gas` · `saber` · `solar` · `aurora`

Add your own to `public/lib/fire.js`. Each is just an array of `[r, g, b]` triples ordered cold→hot.

## Sponsor

Every fireplace renders a small fixed-position attribution linking to **<https://shop.getgoodfeels.com>**. The gallery hub also has a banner sponsor button. Both are baked into the chrome and present on every page.

If you fork this and want to remove or replace the sponsor with your own, edit `public/lib/chrome.js` (one file, ~120 lines).

## License

CC0 1.0 Universal — public domain. See `LICENSE`. The fire algorithm itself was published by Fabien Sanglard / id Software in 1993 and is also widely-shared.

## Credits

Built by [@mhoydich](https://github.com/mhoydich) · sponsored by [Good Feels](https://shop.getgoodfeels.com).

Doom-fire algorithm (1993) — Fabien Sanglard's [reverse-engineering writeup](https://fabiensanglard.net/doom_fire_psx/) is the canonical reference.