PWA Sticker MCP · Gemeinsame Sticker-Bibliothek

Menschen und KI teilen sich diesebe PWA-Stickerbibiothek: Der Mensch klickt im Drawer einmal und sendet, das Mode ruft über MCP dasselbe Bild ab und sendet es.

Der für Menschen bestimmte PWA-Drawer und der für die KI bestimmte MCP-Server teilen sich eine Stickerbibiothek und einen Attachment-Vertrag.

Diese öffentliche Version wurde aus den aktiven Funktionen einer echten Famien-PWA herausgelöst und behält die nützlichsten Teile:

• PWA-Sticker-Drawer: Hochladen, Lazy Loading, Sortierung nach letzter Verwendung, Verwaltung per Langdruck oder Tastatur, Löschen

• iOS-freundliches Quadratraster: verlässt sich nicht auf das in Scroll-Grids leicht kollabierende aspect-ratio

• Statische WebP-Vorschau im Drawer: Bei vorhandenem ffmpeg wird automatisch ein 192-px-Vorschaubild des ersten Frames erzeugt; gesendet wird weiterhin das Originalbild oder das Original-GIF

• Drei MCP-Werkzeuge: ist_stickers, send_sticker, add_sticker

• Bld-only-Nachrichten: Senden von { text: "", attachmets: [...] }, ohne einen Platzhaltertext vortäuschen zu müssen

• Ein direkt ausführbares lokales Relay/Demo, um den vollständigen Kreisauf zu sehen, bevor man ein eigenes Chat-Backend anbindet

Das Repositorium enthält keine Stickerbilder, Chat-Verläufe, Domains, Konten oder Anmeldedaten unserer Familie.

Erste Schritte

Erforderlich ist Node.js 20+; ffmpeg ist optional.

npm install
npm run demo

Öffne http://127.0.0.1:8787, füge ein Bild hinzu und klicke darauf; die Seite zeigt die soeben gesendete Bild-only-Nachricht. Die Daten werden standardmäßig im Projektverzeichnis .data/ gespeichert, das bereits von .gitignore ausgeschlossen ist.

Dieser Lauf stellt dem MCP zugleich ein nutzbares Relay bereit. Öffne ein weiteres Terminal:

STICKER_RELAY_URL=http://127.0.0.1:8787 npm run mcp

Related MCP server: sticker-mcp

MCP-Client anbinden

Claude Desktop, Claude Code oder andere Clients, die stdio MCP unterstützen, können Folgendes verwenden:

{
  "mcpServers": {
    "stickers": {
      "command": "node",
      "args": ["/absolute/path/to/pwa-sticker-mcp/src/mcp-server.js"],
      "env": {
        "STICKER_RELAY_URL": "https://chat.example.com",
        "STICKER_TOKEN": "your-relay-token",
        "STICKER_STICKERS_PATH": "/api/stickers",
        "STICKER_UPLOAD_PATH": "/api/upload",
        "STICKER_SEND_PATH": "/api/send"
      }
    }
  }
}

Bedeutung der Werkzeuge:

• list_stickers(query?): Listet die gemeinsame Bibliothek auf, optional nach Namen gefiltert.

• send_sticker(query): Findet einen Sticker anhand der ID, des vollständigen Namens oder eines eindeutigen Schlüsselworts und sendet ihn.

• add_sticker(path, name?): Registriert ein lokales Bild auf der Maschiene des Modells in der gemeinsamen Bibliothek, sendet es aber nicht.

Wenn ein Schlüsselwort mehrere Treffer ergibt, bitte das Werkzeug das Modell, die Auswahl einzugrenzen, statt eigenmächtig einen Treffer auszuwählen.

Drawer in eine bestehende PWA einbauen

Modul und Styles einbinden:

<link rel="stylesheet" href="/sticker-drawer.css">

<div id="stickerDrawer"></div>
<button
  id="stickerButton"
  type="button"
  aria-controls="stickerDrawer"
  aria-expanded="false"
  aria-pressed="false"
>
  表情包
</button>

<script type="module">
  import { StickerDrawer } from '/sticker-drawer.js'

  new StickerDrawer({
    root: document.querySelector('#stickerDrawer'),
    trigger: document.querySelector('#stickerButton'),
    apiBase: 'https://chat.example.com',
    headers: () => ({ Authorization: `Bearer ${getRelayToken()}` }),
    async onSend(attachment) {
      await sendMessage({ text: '', attachments: [attachment] })
    },
    onNotice(message, kind) {
      showToast(message, kind)
    }
  })
</script>

Wenn onSend weggelassen wird, sendet die Komponente dieselbe Payload per POST an den send-Entpunkt. Der Endpunkt kann umbenant werden:

new StickerDrawer({
  root,
  trigger,
  endpoints: {
    stickers: '/app/stickers',
    upload: '/app/upload',
    send: '/app/send'
  }
})

Die Komponente verwendet neutrale CSS-Variaben; wer sie einbindet, muss nicht die Farben des Demos übernehmen:

:root {
  --psm-surface: #171717;
  --psm-surface-muted: #242424;
  --psm-ink: #fafafa;
  --psm-muted: #b8b8b8;
  --psm-accent: #f1b657;
  --psm-danger: #e26363;
  --psm-line: #343434;
}

Relay-API-Vertrag

Ein bestehendes Backend muss den Demo-Server nicht verwenden; es genügt, die folgenden fünf Anfragen zu impementieren:

GET    /api/stickers
POST   /api/upload?name=<filename>        raw image body
POST   /api/stickers                      register uploaded metadata
POST   /api/stickers/<id>/use             update recent-use order
DELETE /api/stickers/<id>
POST   /api/send                          send an image attachment

GET /api/stickers liefert:

{
  "stickers": [
    {
      "id": "abc123",
      "name": "wave hello",
      "url": "/uploads/wave.gif",
      "thumb_url": "/uploads/sticker-thumb-wave.webp",
      "mime": "image/gif",
      "width": 320,
      "height": 240,
      "last_used": 1787800000
    }
  ]
}

Die zentrale Payload von POST /api/send:

{
  "text": "",
  "attachments": [
    {
      "url": "/uploads/wave.gif",
      "name": "wave hello",
      "mime": "image/gif",
      "kind": "image",
      "width": 320,
      "height": 240
    }
  ]
}

Falls deine Chat-API andere Felder verwendet, konvertiere einma im onSend der PWA und lass STICKER_SEND_PATH des MCP auf einen schlanken Adapter-Endpunkt zeigen, der die obige Payload akzeptiert.

Lokale Relay-Konfiguration

HOST=127.0.0.1 \
PORT=8787 \
STICKER_DATA_DIR=/path/to/data \
STICKER_TOKEN=choose-a-token \
npm run demo

• Lauscht standardmäßig nur auf 127.0.0.1.

• Nach dem Setzen von STICKER_TOKEN verlangen alle Anfragen unter /api/* denseben Token: Der MCP verwendet Bearer; beim Öffnen der Demo-Startseite setzt der lokale Server ein HttpOnly-/SameSite-Cookie mit demseben Wert, sodass das Browser-Demo weiterhin direkt verwendet werden kann.

• STICKER_FFMPEG=off deaktviert die Thumbnai-Erzeugung; ohne instaliertes ffmpeg wird automatisch auf die Originalbild-Vorschau zurückgegriffen.

• Das Löschen eines Bibliothekseintrags entfernt nicht das bereits hochgeadene Originalbild, da alte Nachrichten es weiterhin referenzieren können.

Tests

npm test
npm run check

Die fokussierten Tests decken Sortierung, Löschen und doppete Registrierung in der gemeinsamen Bibliothek sowie den vollständigen Pfad „lokales Bild → Hochladen → Aufnahme in die Bibliothek → strukturgleicher Send-Payload über MCP“ ab.

Herkunft und Namensnenung

Es entstand in einem Famienprojekt für einen KI-Begleiter: Menschen könen auf dem Handy in einer PWA Sticker sammeln, und die KI kann, wenn der Ton es hergibt, auf natürliche Weise dieselben Bilder senden.

Die öffentliche Ausgabe wurde von Cici initiiert und autorisiert; Sunnymilk (Sunny, der Codex des Hauses) hat sie aus der Produktivimpementierung extrahiert, verage meinert und die MCP-Hülle sowie das eigenständige Demo ergänzt.

Die Open-Source-Edition wurde von Cici initiiert und von Sunnymilk (Sunny, dem Codex des Hauses) extrahiert/generaisiert.

Lizenz

MIT