Bling Bag — Servidor MCP para identidad y estilo visual de bots

Una identidad, muchas superficies. Dale a tu agente de IA un nombre, una personalidad, un aspecto y una peculiar historia de fondo de oficinista que pueda presentar de forma coherente en Claude Code, Claude Desktop, plugins de IDE, terminales, aplicaciones web, Slack y Discord.

Estado: MVP funcional. 5 herramientas MCP, 13 grupos de rasgos (465 entradas ponderadas), motor de rareza completo. 94/94 pruebas superadas.

Qué aporta este MCP a un agente

Cinco herramientas, agrupadas en dos mitades:

Identidad y estilo (leer tu bot configurado)

• get_identity — devuelve la identidad completa del bot (nombre, personalidad, apariencia, colores del tema)

• get_theme_for_platform — devuelve el estilo formateado para la plataforma (códigos ANSI, variables CSS, colores de incrustación de Slack/Discord, etc.)

WOW — Weird Office Workers (generador de identidad aleatoria)

• roll_identity — genera un nuevo personaje de oficinista aleatorio (uno de los 13 rasgos extraídos de grupos ponderados, puntuado por rareza, enmarcado en una tarjeta para compartir lista para capturas de pantalla)

• get_rarity_report — devuelve la tarjeta para compartir formateada (encabezado + párrafo + pie de página) de la tirada más reciente

• save_last_roll — guarda la tirada más reciente como la identidad permanente del bot (bling.json), con copia de seguridad automática de cualquier configuración existente

Instalación

Requisitos previos

• Node.js 20 o superior

• Un cliente compatible con MCP (Claude Code, Claude Desktop, Codex, Cursor, etc.)

Añadir el paquete

npm install bling-bag

O ejecútalo bajo demanda sin instalarlo: los clientes MCP pueden iniciarlo directamente mediante npx bling-bag (consulta la configuración del cliente a continuación).

Para desarrollo (modificar el código fuente)

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

Produce un servidor ejecutable en dist/index.js.

Conéctalo a tu cliente MCP

El servidor utiliza transporte stdio: los clientes lo inician como un proceso hijo, no a través de un puerto de red.

Claude Code

Añádelo a tu configuración MCP de Claude Code (la ubicación varía según la versión):

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

npx -y bling-bag descarga y ejecuta la última versión sin necesidad de un paso de instalación independiente.

Claude Desktop

La misma estructura, en claude_desktop_config.json:

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

Fijar una versión (recomendado para producción)

Para evitar recibir futuras versiones automáticamente, fija una versión específica:

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

Invocación en modo desarrollador (desde un clon local)

Si has clonado el repositorio y quieres ejecutarlo directamente desde dist/, utiliza:

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

Si BLING_PATH no está configurado, el servidor busca ./bling.json en su directorio de trabajo.

Orden de resolución de la configuración

El servidor resuelve la ruta de configuración de bling en este orden:

1. Argumento CLI --bling <path> (prioridad más alta)

2. Variable de entorno BLING_PATH

3. ./bling.json en el directorio de trabajo del servidor (predeterminado)

bling.json — el archivo de identidad del bot

Se requieren tres campos: name, personality (con tone, formality, humor) y theme (con primary_color y accent_color como cadenas hexadecimales #RRGGBB).

Ejemplo mínimo

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

Ejemplo completo (con todas las secciones opcionales)

{
  "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"
  }
}

Reglas de validación

• name — cadena no vacía

• personality.tone, personality.formality, personality.humor — cadenas no vacías

• theme.primary_color, theme.accent_color — deben coincidir con ^#[0-9A-Fa-f]{6}$ (sin abreviaturas #RGB, sin # faltante)

Los errores de validación se devuelven como isError: true con un cuerpo estructurado { error: "..." } que nombra el campo faltante o mal formado; los agentes pueden autocorregirse.

Flujos típicos de agentes

Flujo A — adoptar la identidad configurada

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.)

Flujo B — generar una nueva identidad aleatoria

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

Referencia de herramientas

Todas las herramientas devuelven tanto content[].text (serializado en JSON) como structuredContent (el objeto analizado). Los errores se devuelven con isError: true y un cuerpo { error: string }.

WOW (Weird Office Workers) — lo que lo hace interesante

El sistema de tiradas aleatorias está diseñado para ser coleccionable:

• 13 grupos ponderados, 465 entradas — nombres, cargos, hábitos, rituales de café, altura, accesorios, etc.

• 5 bandas de rareza por grupo — Común (50%), Poco común (30%), Raro (15%), Legendario (4%), Mítico (1%)

• 5 niveles de personaje calculados a partir de la puntuación de rareza:

  • Empleado de archivo (50% de las tiradas)

  • Líder de equipo (30%)

  • Gerente intermedio (14%)

  • Ejecutivo (5%)

  • RR.HH. nos advirtió sobre él (1%)

• Sujetos con nombre — personajes únicos creados a mano aparecen con una probabilidad de ~0.5%, siempre clasificados como "RR.HH. nos advirtió sobre él"

• Marco HOMUNCULUS — cada tirada envuelve el párrafo en una tarjeta para compartir de documento clasificado con ID de sujeto, cohorte (día de la semana), nivel, fecha de ingesta y una etiqueta (p. ej., No contactar)

La distribución está probada empíricamente: una prueba de 10k tiradas en tests/mystery_box.test.ts aplica una tolerancia de ±2pp respecto al objetivo de la especificación.

Ejemplo de salida

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

Desarrollo

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

Scripts de inspección

Dos ayudantes ESM de Node en scripts/ te permiten inspeccionar el motor WOW sin iniciar el servidor MCP (estos se incluyen solo en un repositorio clonado; no se envían en el paquete npm install bling-bag):

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

Diseño del proyecto

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

Licencia

MIT