Bling-bag
The Bling-bag server lets you give your bot a personality, appearance, and backstory via a custom config or randomly generated identity.
get_identity: Retrieve the bot's full configured identity frombling.json(name, personality, quirks, appearance, theme colors).get_theme_for_platform: Get styling formatted for a specific platform —terminal(ANSI),web(CSS variables),slack,discord, oride— based on the bot's theme.roll_identity: Generate a random "Weird Office Worker" identity with name, job title, desk habits, coffee ritual, rarity score, tier, and a screenshot-ready share card. Supports alegendsvariant for historical figures in absurd corporate roles.save_last_roll: Persist the most recently rolled identity tobling.json, automatically backing up any existing config to<path>.bak.get_rarity_report: Retrieve the formatted plain-text share card for the most recent roll, including the HOMUNCULUS frame with subject ID, cohort, tier, rarity score, and flags.
Generates Discord embed colors and platform-formatted styling for bot identities, enabling consistent visual presentation of AI agents in Discord environments.
Generates Slack embed colors and platform-formatted styling for bot identities, enabling consistent visual presentation of AI agents in Slack workspaces.
Bling Bag
Give your bot an identity.
Your bot has a name. Now give it a personality, a look, and a backstory.
Roll the wheel and see what you get — or write your own in a bling.json file.
What you get
Five MCP tools and two identity pools:
WOW — Weird Office Workers
Roll a random quirky office-worker bot: name, job title, desk setup, habits, coffee ritual, and a screenshot-ready share card. 99/99 tests, full rarity engine, 13 weighted trait pools.
Legends — Historical Figures
Same engine, different universe. Roll a historical figure in an absurd corporate role — Julius Caesar as Hostile Takeover Specialist, Marie Curie as Lab Safety's Most Wanted, Napoleon as Regional Manager (France & Surrounding Areas).
Pass variant: "legends" to roll_identity to use it. Default is "wow".
Related MCP server: PLTM-Claude
Install
Prerequisites
Node.js 20 or later
An MCP-compatible client (Claude Code, Claude Desktop, Codex, Cursor, etc.)
Add the package
npm install bling-bagOr run it on-demand without installing — MCP clients can launch it directly via npx bling-bag (see client config below).
For development (modifying the source)
git clone https://github.com/<github-user>/mcp-bling.git
cd mcp-bling
npm install
npm run buildProduces a runnable server at dist/index.js.
Wire it into your MCP client
The server uses stdio transport — clients launch it as a child process, not over a network port.
Claude Code
Add to your Claude Code MCP config (location varies by version):
{
"mcpServers": {
"bling": {
"command": "npx",
"args": ["-y", "bling-bag"],
"env": {
"BLING_PATH": "/absolute/path/to/your/bling.json"
}
}
}
}npx -y bling-bag downloads and runs the latest version without requiring a separate install step.
Claude Desktop
Same shape, in claude_desktop_config.json:
{
"mcpServers": {
"bling": {
"command": "npx",
"args": ["-y", "bling-bag"],
"env": {
"BLING_PATH": "/absolute/path/to/your/bling.json"
}
}
}
}Pinning to a version (recommended for production)
To avoid picking up future releases automatically, pin a specific version:
"args": ["-y", "bling-bag@0.1.0"]Developer-mode invocation (from a local clone)
If you've cloned the repo and want to run from dist/ directly, use:
"command": "node",
"args": ["/absolute/path/to/mcp-bling/dist/index.js"]If BLING_PATH is not set, the server looks for ./bling.json in its working directory.
Config resolution order
The server resolves the bling config path in this order:
--bling <path>CLI argument (highest priority)BLING_PATHenvironment variable./bling.jsonin the server's working directory (default)
bling.json — the bot's identity file
Three fields are required: name, personality (with tone, formality, humor), and theme (with primary_color and accent_color as #RRGGBB hex strings).
Minimum example
{
"name": "Pixel",
"personality": {
"tone": "warm",
"formality": "casual",
"humor": "playful"
},
"theme": {
"primary_color": "#3A7BD5",
"accent_color": "#FFD166"
}
}Full example (with all optional sections)
{
"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"
}
}Validation rules
name— non-empty stringpersonality.tone,personality.formality,personality.humor— non-empty stringstheme.primary_color,theme.accent_color— must match^#[0-9A-Fa-f]{6}$(no shorthand#RGB, no missing#)
Validation errors come back as isError: true with a structured { error: "..." } body that names the missing or malformed field — agents can self-correct.
Typical agent flows
Flow A — adopt the configured identity
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.)Flow B — generate a fresh random identity
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 identityTool reference
Tool | Read/Write | Idempotent | Description |
| read (disk) | yes | Returns the configured bling.json identity |
| read (disk) | yes | Platform-formatted styling. Args: |
| mutates in-memory cache | no | Generates a random WOW character with rarity scoring |
| write (disk) | no | Persists the most-recent roll to bling.json (creates |
| read (in-memory) | yes | Returns the share-card text for the most-recent roll |
All tools return both content[].text (JSON-stringified) and structuredContent (the parsed object). Errors come back with isError: true and a { error: string } body.
WOW (Weird Office Workers) — what makes it interesting
The random-roll system is built for collectibility:
13 weighted pools, 465 entries — names, job titles, habits, coffee rituals, height, accessories, etc.
5 rarity bands per pool — Common (50%), Uncommon (30%), Rare (15%), Legendary (4%), Mythic (1%)
5 character tiers computed from rarity score:
Filing Clerk (50% of rolls)
Team Lead (30%)
Middle Manager (14%)
C-Suite (5%)
HR Warned Us About (1%)
Named Subjects — hand-authored 1-of-1 characters appear at ~0.5% probability, always classified as "HR Warned Us About"
HOMUNCULUS frame — every roll wraps the paragraph in a classified-document share card with subject ID, cohort (weekday), tier, ingestion date, and a flag (e.g. Do Not Contact)
Distribution is empirically tested: a 10k-roll test in tests/mystery_box.test.ts enforces ±2pp tolerance against the spec target.
Example output
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 reviewDevelopment
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 changesInspection scripts
Two Node ESM helpers under scripts/ let you inspect the WOW engine without booting the MCP server (these are included only in a cloned repo — they are not shipped in the npm install bling-bag package):
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 targetProject layout
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 plansLicense
MIT
Available Tools
5 toolsget_identityGet Bot IdentityARead-onlyIdempotent
Get the bot's full identity from bling.json — name, personality, quirks, appearance, and theme colours. Returns the configured identity (hand-written or saved from a roll). Errors if bling.json is missing or invalid.
Inputs: no named parameters.
get_rarity_reportGet WOW Rarity ReportARead-onlyIdempotent
Return the formatted share card (lore header, paragraph, lore footer) for the most-recent WOW roll. The report is plain text designed to be screenshotted directly. Errors if no roll has happened this session.
Inputs: no named parameters. Returns: report, error
get_theme_for_platformGet Theme for PlatformARead-onlyIdempotent
Get platform-specific styling for the bot. Supported platforms: terminal (returns ANSI escape codes), web (CSS variables), slack, discord, ide. Unknown platforms get the raw hex theme colours.
Inputs: platform (required).
roll_identityRoll a WOW IdentityA
WOW — Weird Office Workers. Roll a fresh random bot identity: a quirky office-worker character with a rarity score and a screenshot-ready share card. Stores the roll for save_last_roll and get_rarity_report.
Inputs: no named parameters. Returns: identity, rarity, paragraph, framed, +1 more
save_last_rollSave Last WOW Roll to bling.jsonADestructive
Persist the most-recent WOW roll by writing it to the configured bling.json path. If a file already exists at that path it is first copied to .bak so user-tuned configs are recoverable. Returns the backup path (or null if the target was new).
Inputs: no named parameters. Returns: ok, written_to, backup, error
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose: get_identity retrieves a saved identity, get_rarity_report provides a formatted report of the latest roll, get_theme_for_platform returns platform-specific styling, roll_identity generates a new random identity, and save_last_roll persists the latest roll. There is no overlap in functionality, making tool selection straightforward for an agent.
All tool names follow a consistent verb_noun pattern with snake_case, such as get_identity, get_rarity_report, get_theme_for_platform, roll_identity, and save_last_roll. This uniformity enhances readability and predictability across the toolset.
With 5 tools, the server is well-scoped for managing bot identities and related operations. Each tool serves a specific role in the identity lifecycle, from creation to retrieval and persistence, without being overly sparse or bloated.
The toolset provides complete coverage for the bot identity domain: roll_identity for creation, get_identity and get_rarity_report for retrieval, save_last_roll for persistence, and get_theme_for_platform for styling. There are no obvious gaps, supporting full agent workflows from generation to configuration.
Maintenance
Related MCP Connectors
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Hosted MCP server for live public-data APIs and Skills for AI agents.
Shared memory and mail for your AI agents. Verified with Claude Code; other MCP clients in testing.
Related MCP Servers
- FlicenseAqualityCmaintenanceMCP server for Being — a Personality Runtime that gives AI agents persistent memory, personality, and relationships. Enables any MCP-compatible client (Claude, OpenClaw, Cursor, etc.) to connect with a Being that remembers, grows, and maintains its own identity across sessions.101-
- AlicenseNot gradedqualityCmaintenanceAn MCP server that gives Claude Desktop persistent memory, self-awareness, epistemic hygiene, and genuine agency across conversations with a typed memory system, embedding-based semantic search, a 3-judge memory jury, and a real-time dashboard.7MIT
- AlicenseAqualityDmaintenanceOne MCP that turns Claude Code into your whole dev stack by swallowing other MCP servers, delegating to Codex & Gemini on your CLI subscriptions, remembering projects in a searchable knowledge graph, and carrying setup across sessions — secret-free by design.234MIT
- AlicenseNot gradedqualityCmaintenanceServe your personal work-style manual as an MCP server so AI surfaces load the same single source of truth about your identity and preferences.MIT