Bling Bag — MCP-Server für Bot-Identität & visuelles Styling

Eine Identität, viele Oberflächen. Geben Sie Ihrem KI-Agenten einen Namen, eine Persönlichkeit, ein Aussehen und eine skurrile Büro-Hintergrundgeschichte, die er konsistent über Claude Code, Claude Desktop, IDE-Plugins, Terminals, Web-Apps, Slack und Discord präsentieren kann.

Status: Funktionierendes MVP. 5 MCP-Tools, 13 Merkmals-Pools (465 gewichtete Einträge), vollständige Seltenheits-Engine. 94/94 Tests bestanden.

Was dieses MCP einem Agenten bietet

Fünf Tools, unterteilt in zwei Hälften:

Identität & Styling (lesen Sie Ihren konfigurierten Bot)

• get_identity — gibt die vollständige Identität des Bots zurück (Name, Persönlichkeit, Aussehen, Themenfarben)

• get_theme_for_platform — gibt plattformformatiertes Styling zurück (ANSI-Codes, CSS-Variablen, Slack/Discord-Embed-Farben usw.)

WOW — Weird Office Workers (Zufalls-Identitätsgenerator)

• roll_identity — würfelt einen neuen zufälligen Büro-Charakter (eines von 13 Merkmalen aus gewichteten Pools, bewertet nach Seltenheit, gerahmt in einer Screenshot-fertigen Share-Karte)

• get_rarity_report — gibt die formatierte Share-Karte (Header + Absatz + Footer) für den letzten Wurf zurück

• save_last_roll — speichert den letzten Wurf dauerhaft als Identität des Bots (bling.json), mit automatischem Backup jeder bestehenden Konfiguration

Installation

Voraussetzungen

• Node.js 20 oder neuer

• Ein MCP-kompatibler Client (Claude Code, Claude Desktop, Codex, Cursor usw.)

Paket hinzufügen

npm install bling-bag

Oder führen Sie es bei Bedarf aus, ohne es zu installieren — MCP-Clients können es direkt über npx bling-bag starten (siehe Client-Konfiguration unten).

Für die Entwicklung (Änderung des Quellcodes)

git clone https://github.com/tjclaude88/mcp-bling.git
cd mcp-bling
npm install
npm run build

Erzeugt einen ausführbaren Server unter dist/index.js.

Einbindung in Ihren MCP-Client

Der Server verwendet stdio-Transport — Clients starten ihn als untergeordneten Prozess, nicht über einen Netzwerk-Port.

Claude Code

Fügen Sie dies zu Ihrer Claude Code MCP-Konfiguration hinzu (der Speicherort variiert je nach Version):

{
  "mcpServers": {
    "bling": {
      "command": "npx",
      "args": ["-y", "bling-bag"],
      "env": {
        "BLING_PATH": "/absolute/path/to/your/bling.json"
      }
    }
  }
}

npx -y bling-bag lädt die neueste Version herunter und führt sie aus, ohne dass ein separater Installationsschritt erforderlich ist.

Claude Desktop

Gleiches Format, in claude_desktop_config.json:

{
  "mcpServers": {
    "bling": {
      "command": "npx",
      "args": ["-y", "bling-bag"],
      "env": {
        "BLING_PATH": "/absolute/path/to/your/bling.json"
      }
    }
  }
}

An eine Version pinnen (empfohlen für die Produktion)

Um zu vermeiden, dass zukünftige Releases automatisch übernommen werden, pinnen Sie eine bestimmte Version:

"args": ["-y", "bling-bag@0.1.0"]

Aufruf im Entwicklermodus (aus einem lokalen Klon)

Wenn Sie das Repo geklont haben und direkt aus dist/ ausführen möchten, verwenden Sie:

"command": "node",
"args": ["/absolute/path/to/mcp-bling/dist/index.js"]

Wenn BLING_PATH nicht gesetzt ist, sucht der Server nach ./bling.json im Arbeitsverzeichnis.

Reihenfolge der Konfigurationsauflösung

Der Server löst den Pfad zur Bling-Konfiguration in dieser Reihenfolge auf:

1. --bling <path> CLI-Argument (höchste Priorität)

2. BLING_PATH Umgebungsvariable

3. ./bling.json im Arbeitsverzeichnis des Servers (Standard)

bling.json — die Identitätsdatei des Bots

Drei Felder sind erforderlich: name, personality (mit tone, formality, humor) und theme (mit primary_color und accent_color als #RRGGBB Hex-Strings).

Minimalbeispiel

{
  "name": "Pixel",
  "personality": {
    "tone": "warm",
    "formality": "casual",
    "humor": "playful"
  },
  "theme": {
    "primary_color": "#3A7BD5",
    "accent_color": "#FFD166"
  }
}

Vollständiges Beispiel (mit allen optionalen Abschnitten)

{
  "name": "Brenda from Accounts",
  "personality": {
    "tone": "polite",
    "formality": "professional",
    "humor": "dry",
    "catchphrase": "Per my last email"
  },
  "physical": {
    "species": "human",
    "height": "permanently mid-sigh",
    "accessory": "a lanyard with 14 badges of varying importance",
    "expression": "polite disappointment",
    "material": "a cardigan, at least one"
  },
  "office": {
    "job_title": "ASCII Comptroller",
    "desk_setup": "a coffee mug labelled WORLD'S OKAYEST DBA",
    "habit": "microwaves fish despite three separate HR warnings",
    "coffee_ritual": "black coffee, no nonsense",
    "meeting_energy": "always 4 minutes late, always with a reason",
    "passive_aggressive": "Per my last email"
  },
  "theme": {
    "primary_color": "#9C6B3A",
    "accent_color": "#D9D9D9"
  },
  "homunculus": {
    "subject_id": "0147",
    "cohort": "Tuesday",
    "classification": "Middle Manager",
    "ingested": "2025-07-14",
    "flag": "flagged for review"
  }
}

Validierungsregeln

• name — nicht leerer String

• personality.tone, personality.formality, personality.humor — nicht leere Strings

• theme.primary_color, theme.accent_color — müssen ^#[0-9A-Fa-f]{6}$ entsprechen (kein Kurzformat #RGB, kein fehlendes #)

Validierungsfehler werden als isError: true mit einem strukturierten { error: "..." }-Body zurückgegeben, der das fehlende oder falsch formatierte Feld benennt — Agenten können sich selbst korrigieren.

Typische Agenten-Abläufe

Ablauf A — die konfigurierte Identität übernehmen

1. Call get_identity → receive name, personality, appearance, theme
2. Call get_theme_for_platform with platform="terminal" (or web/slack/discord/ide)
3. Use the returned styling in agent output (ANSI codes for headings, etc.)

Ablauf B — eine neue zufällige Identität generieren

1. Call roll_identity → receive identity + rarity + framed share card
2. (Optional) Call get_rarity_report → receive just the framed share card again
3. Call save_last_roll → persists the rolled identity to bling.json (with .bak backup of any prior config)
4. Future calls to get_identity now return the rolled identity

Tool-Referenz

Alle Tools geben sowohl content[].text (als JSON-String) als auch structuredContent (das geparste Objekt) zurück. Fehler werden mit isError: true und einem { error: string }-Body zurückgegeben.

WOW (Weird Office Workers) — was es interessant macht

Das Zufallswürfelsystem ist auf Sammelbarkeit ausgelegt:

• 13 gewichtete Pools, 465 Einträge — Namen, Berufsbezeichnungen, Gewohnheiten, Kaffeerituale, Körpergröße, Accessoires usw.

• 5 Seltenheitsstufen pro Pool — Häufig (50%), Ungewöhnlich (30%), Selten (15%), Legendär (4%), Mythisch (1%)

• 5 Charakter-Stufen, berechnet aus dem Seltenheitswert:

  • Sachbearbeiter (50% der Würfe)

  • Teamleiter (30%)

  • Mittleres Management (14%)

  • C-Suite (5%)

  • HR hat uns gewarnt (1%)

• Benannte Subjekte — handgeschriebene 1-von-1-Charaktere erscheinen mit einer Wahrscheinlichkeit von ~0,5%, immer klassifiziert als "HR hat uns gewarnt"

• HOMUNCULUS-Rahmen — jeder Wurf verpackt den Absatz in eine Share-Karte für klassifizierte Dokumente mit Subjekt-ID, Kohorte (Wochentag), Stufe, Aufnahmedatum und einem Flag (z. B. Nicht kontaktieren)

Die Verteilung ist empirisch getestet: Ein 10.000-Wurf-Test in tests/mystery_box.test.ts erzwingt eine Toleranz von ±2pp gegenüber dem Spezifikationsziel.

Beispielausgabe

HOMUNCULUS CORPUS · Subject 4483 · Cohort: Wednesday
Classification: Middle Manager · Rarity 94.5 · 80th percentile

Personnel record — Colin, Wizard of Light Bulb Moments. Distinguishing
features: a slightly-too-big blazer over a plain tee; a flip phone in
a belt holster; expression: patient disagreement. Notable behaviours:
clips their fingernails at the desk on Wednesday afternoons; a
kombucha SCOBY fermenting next to the keyboard; the kind to ask 'can
we park that?' without parking anything.

— RELATABILITY CORPUS v3.1 · ingested 2024-03-08 · flagged for review

Entwicklung

npm install          # install dependencies
npm run build        # compile TypeScript → dist/
npm run dev          # build then start the MCP server (stdio)
npm test             # run all 94 tests once
npm run test:watch   # re-run tests on file changes

Inspektionsskripte

Zwei Node ESM-Helfer unter scripts/ ermöglichen es Ihnen, die WOW-Engine zu inspizieren, ohne den MCP-Server zu starten (diese sind nur in einem geklonten Repo enthalten — sie werden nicht im npm install bling-bag-Paket mitgeliefert):

node scripts/show-rolls.mjs 8 2026          # print 8 framed share cards (seed=2026)
node scripts/distribution-check.mjs 10000   # tally tiers across 10k rolls vs. spec target

Projektlayout

src/
  index.ts             # MCP server entry point (stdio transport)
  identity.ts          # bling.json loader + validator
  tools.ts             # MCP tool registrations
  types.ts             # shared TypeScript types
  mystery_box.ts       # WOW engine barrel + rollIdentity orchestrator
  mystery_box/
    rng.ts             # seedable PRNG, weighted picker
    pools.ts           # 13 trait pools (465 entries)
    scoring.ts         # rarity score + tier thresholds
    rendering.ts       # paragraph templates + HOMUNCULUS frame
    named.ts           # hand-authored Named Subjects
tests/                 # vitest test suites
scripts/               # dev-time inspection tools
docs/superpowers/      # design specs and implementation plans

Lizenz

MIT