Bling Bag — MCP-сервер для идентификации и визуального оформления ботов

Одна личность, множество интерфейсов. Дайте своему ИИ-агенту имя, характер, внешний вид и причудливую предысторию офисного работника, которую он сможет последовательно демонстрировать в Claude Code, Claude Desktop, плагинах IDE, терминалах, веб-приложениях, Slack и Discord.

Статус: Рабочий MVP. 5 инструментов MCP, 13 пулов характеристик (465 взвешенных записей), полноценный движок редкости. 94/94 тестов пройдены.

Что этот MCP дает агенту

Пять инструментов, разделенных на две группы:

Идентификация и оформление (чтение настроек бота)

• get_identity — возвращает полную личность бота (имя, характер, внешний вид, цвета темы)

• get_theme_for_platform — возвращает оформление, отформатированное под платформу (ANSI-коды, CSS-переменные, цвета для эмбедов в Slack/Discord и т. д.)

WOW — Weird Office Workers (генератор случайных личностей)

• roll_identity — генерирует нового случайного офисного работника (одна из 13 характеристик, выбранных из взвешенных пулов, с оценкой редкости и оформлением в виде карточки для скриншота)

• get_rarity_report — возвращает отформатированную карточку для шеринга (заголовок + абзац + футер) для последней генерации

• save_last_roll — сохраняет последнюю генерацию как постоянную личность бота (bling.json) с автоматическим созданием резервной копии существующей конфигурации

Установка

Предварительные требования

• Node.js 20 или новее

• MCP-совместимый клиент (Claude Code, Claude Desktop, Codex, Cursor и т. д.)

Добавление пакета

npm install bling-bag

Или запустите его по требованию без установки — MCP-клиенты могут запускать его напрямую через npx bling-bag (см. конфигурацию клиента ниже).

Для разработки (изменение исходного кода)

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

Создает запускаемый сервер в dist/index.js.

Подключение к вашему MCP-клиенту

Сервер использует stdio transport — клиенты запускают его как дочерний процесс, а не через сетевой порт.

Claude Code

Добавьте в конфигурацию MCP для Claude Code (расположение зависит от версии):

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

npx -y bling-bag скачивает и запускает последнюю версию без необходимости отдельного шага установки.

Claude Desktop

Аналогично, в claude_desktop_config.json:

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

Закрепление версии (рекомендуется для продакшена)

Чтобы избежать автоматического получения будущих релизов, закрепите конкретную версию:

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

Запуск в режиме разработчика (из локального клона)

Если вы клонировали репозиторий и хотите запускать напрямую из dist/, используйте:

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

Если BLING_PATH не задан, сервер ищет ./bling.json в своей рабочей директории.

Порядок разрешения конфигурации

Сервер разрешает путь к конфигурации bling в следующем порядке:

1. Аргумент CLI --bling <path> (наивысший приоритет)

2. Переменная окружения BLING_PATH

3. ./bling.json в рабочей директории сервера (по умолчанию)

bling.json — файл личности бота

Требуются три поля: name, personality (с параметрами tone, formality, humor) и theme (с primary_color и accent_color в виде шестнадцатеричных строк #RRGGBB).

Минимальный пример

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

Полный пример (со всеми необязательными разделами)

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

Правила валидации

• name — непустая строка

• personality.tone, personality.formality, personality.humor — непустые строки

• theme.primary_color, theme.accent_color — должны соответствовать ^#[0-9A-Fa-f]{6}$ (никаких сокращений #RGB, отсутствие # недопустимо)

Ошибки валидации возвращаются как isError: true со структурированным телом { error: "..." }, указывающим на отсутствующее или неправильно сформированное поле — агенты могут исправлять их самостоятельно.

Типичные сценарии использования агентом

Сценарий A — принятие настроенной личности

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

Сценарий B — генерация новой случайной личности

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

Справочник инструментов

Все инструменты возвращают как content[].text (JSON-строка), так и structuredContent (разобранный объект). Ошибки возвращаются с isError: true и телом { error: string }.

WOW (Weird Office Workers) — почему это интересно

Система случайной генерации создана для коллекционирования:

• 13 взвешенных пулов, 465 записей — имена, должности, привычки, кофейные ритуалы, рост, аксессуары и т. д.

• 5 уровней редкости для каждого пула — Обычный (50%), Необычный (30%), Редкий (15%), Легендарный (4%), Мифический (1%)

• 5 уровней персонажей, вычисляемых на основе оценки редкости:

  • Клерк (50% генераций)

  • Тимлид (30%)

  • Мидл-менеджер (14%)

  • Топ-менеджер (5%)

  • "HR нас предупреждал" (1%)

• Именные персонажи — созданные вручную уникальные персонажи появляются с вероятностью ~0,5%, всегда классифицируются как "HR нас предупреждал"

• Рамка HOMUNCULUS — каждая генерация оборачивает абзац в карточку секретного документа с ID субъекта, когортой (день недели), уровнем, датой поступления и флагом (например, Не контактировать)

Распределение проверено эмпирически: тест из 10 тыс. генераций в tests/mystery_box.test.ts обеспечивает допуск ±2% от целевых показателей.

Пример вывода

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

Разработка

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

Скрипты для инспекции

Два вспомогательных ESM-скрипта Node в папке scripts/ позволяют изучить движок WOW без запуска MCP-сервера (они включены только в клонированный репозиторий — они не поставляются в пакете 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

Структура проекта

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

Лицензия

MIT