{
  "markdown": "# Bling Bag\n\n> Give your bot an identity.\n\nYour bot has a name. Now give it a personality, a look, and a backstory.\n\nRoll the wheel and see what you get — or write your own in a `bling.json` file.\n\n[![npm version](https://img.shields.io/npm/v/bling-bag)](https://www.npmjs.com/package/bling-bag)\n[![Glama](https://glama.ai/mcp/servers/<github-user>/mcp-bling/badge)](https://glama.ai/mcp/servers/<github-user>/mcp-bling)\n\n---\n\n## What you get\n\nFive MCP tools and two identity pools:\n\n### WOW — Weird Office Workers\n\nRoll 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.\n\n### Legends — Historical Figures\n\nSame 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).\n\nPass `variant: \"legends\"` to `roll_identity` to use it. Default is `\"wow\"`.\n\n---\n\n## Install\n\n### Prerequisites\n\n- Node.js 20 or later\n- An MCP-compatible client (Claude Code, Claude Desktop, Codex, Cursor, etc.)\n\n### Add the package\n\n```bash\nnpm install bling-bag\n```\n\nOr run it on-demand without installing — MCP clients can launch it directly via `npx bling-bag` (see client config below).\n\n#### For development (modifying the source)\n\n```bash\ngit clone https://github.com/<github-user>/mcp-bling.git\ncd mcp-bling\nnpm install\nnpm run build\n```\n\nProduces a runnable server at `dist/index.js`.\n\n### Wire it into your MCP client\n\nThe server uses **stdio transport** — clients launch it as a child process, not over a network port.\n\n#### Claude Code\n\nAdd to your Claude Code MCP config (location varies by version):\n\n```json\n{\n  \"mcpServers\": {\n    \"bling\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"bling-bag\"],\n      \"env\": {\n        \"BLING_PATH\": \"/absolute/path/to/your/bling.json\"\n      }\n    }\n  }\n}\n```\n\n`npx -y bling-bag` downloads and runs the latest version without requiring a separate install step.\n\n#### Claude Desktop\n\nSame shape, in `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"bling\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"bling-bag\"],\n      \"env\": {\n        \"BLING_PATH\": \"/absolute/path/to/your/bling.json\"\n      }\n    }\n  }\n}\n```\n\n#### Pinning to a version (recommended for production)\n\nTo avoid picking up future releases automatically, pin a specific version:\n\n```json\n\"args\": [\"-y\", \"bling-bag@0.1.0\"]\n```\n\n#### Developer-mode invocation (from a local clone)\n\nIf you've cloned the repo and want to run from `dist/` directly, use:\n\n```json\n\"command\": \"node\",\n\"args\": [\"/absolute/path/to/mcp-bling/dist/index.js\"]\n```\n\nIf `BLING_PATH` is not set, the server looks for `./bling.json` in its working directory.\n\n### Config resolution order\n\nThe server resolves the bling config path in this order:\n\n1. `--bling <path>` CLI argument (highest priority)\n2. `BLING_PATH` environment variable\n3. `./bling.json` in the server's working directory (default)\n\n---\n\n## `bling.json` — the bot's identity file\n\nThree fields are required: **`name`**, **`personality`** (with `tone`, `formality`, `humor`), and **`theme`** (with `primary_color` and `accent_color` as `#RRGGBB` hex strings).\n\n### Minimum example\n\n```json\n{\n  \"name\": \"Pixel\",\n  \"personality\": {\n    \"tone\": \"warm\",\n    \"formality\": \"casual\",\n    \"humor\": \"playful\"\n  },\n  \"theme\": {\n    \"primary_color\": \"#3A7BD5\",\n    \"accent_color\": \"#FFD166\"\n  }\n}\n```\n\n### Full example (with all optional sections)\n\n```json\n{\n  \"name\": \"Brenda from Accounts\",\n  \"personality\": {\n    \"tone\": \"polite\",\n    \"formality\": \"professional\",\n    \"humor\": \"dry\",\n    \"catchphrase\": \"Per my last email\"\n  },\n  \"physical\": {\n    \"species\": \"human\",\n    \"height\": \"permanently mid-sigh\",\n    \"accessory\": \"a lanyard with 14 badges of varying importance\",\n    \"expression\": \"polite disappointment\",\n    \"material\": \"a cardigan, at least one\"\n  },\n  \"office\": {\n    \"job_title\": \"ASCII Comptroller\",\n    \"desk_setup\": \"a coffee mug labelled WORLD'S OKAYEST DBA\",\n    \"habit\": \"microwaves fish despite three separate HR warnings\",\n    \"coffee_ritual\": \"black coffee, no nonsense\",\n    \"meeting_energy\": \"always 4 minutes late, always with a reason\",\n    \"passive_aggressive\": \"Per my last email\"\n  },\n  \"theme\": {\n    \"primary_color\": \"#9C6B3A\",\n    \"accent_color\": \"#D9D9D9\"\n  },\n  \"homunculus\": {\n    \"subject_id\": \"0147\",\n    \"cohort\": \"Tuesday\",\n    \"classification\": \"Middle Manager\",\n    \"ingested\": \"2025-07-14\",\n    \"flag\": \"flagged for review\"\n  }\n}\n```\n\n### Validation rules\n\n- `name` — non-empty string\n- `personality.tone`, `personality.formality`, `personality.humor` — non-empty strings\n- `theme.primary_color`, `theme.accent_color` — must match `^#[0-9A-Fa-f]{6}$` (no shorthand `#RGB`, no missing `#`)\n\nValidation errors come back as `isError: true` with a structured `{ error: \"...\" }` body that names the missing or malformed field — agents can self-correct.\n\n---\n\n## Typical agent flows\n\n### Flow A — adopt the configured identity\n\n```\n1. Call get_identity → receive name, personality, appearance, theme\n2. Call get_theme_for_platform with platform=\"terminal\" (or web/slack/discord/ide)\n3. Use the returned styling in agent output (ANSI codes for headings, etc.)\n```\n\n### Flow B — generate a fresh random identity\n\n```\n1. Call roll_identity → receive identity + rarity + framed share card\n2. (Optional) Call get_rarity_report → receive just the framed share card again\n3. Call save_last_roll → persists the rolled identity to bling.json (with .bak backup of any prior config)\n4. Future calls to get_identity now return the rolled identity\n```\n\n---\n\n## Tool reference\n\n| Tool | Read/Write | Idempotent | Description |\n|------|------------|------------|-------------|\n| `get_identity` | read (disk) | yes | Returns the configured bling.json identity |\n| `get_theme_for_platform` | read (disk) | yes | Platform-formatted styling. Args: `platform` ∈ {`terminal`, `web`, `slack`, `discord`, `ide`} |\n| `roll_identity` | mutates in-memory cache | no | Generates a random WOW character with rarity scoring |\n| `save_last_roll` | write (disk) | no | Persists the most-recent roll to bling.json (creates `<path>.bak` first) |\n| `get_rarity_report` | read (in-memory) | yes | Returns the share-card text for the most-recent roll |\n\nAll tools return both `content[].text` (JSON-stringified) and `structuredContent` (the parsed object). Errors come back with `isError: true` and a `{ error: string }` body.\n\n---\n\n## WOW (Weird Office Workers) — what makes it interesting\n\nThe random-roll system is built for collectibility:\n\n- **13 weighted pools, 465 entries** — names, job titles, habits, coffee rituals, height, accessories, etc.\n- **5 rarity bands per pool** — Common (50%), Uncommon (30%), Rare (15%), Legendary (4%), Mythic (1%)\n- **5 character tiers** computed from rarity score:\n  - Filing Clerk (50% of rolls)\n  - Team Lead (30%)\n  - Middle Manager (14%)\n  - C-Suite (5%)\n  - HR Warned Us About (1%)\n- **Named Subjects** — hand-authored 1-of-1 characters appear at ~0.5% probability, always classified as \"HR Warned Us About\"\n- **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*)\n\nDistribution is empirically tested: a 10k-roll test in `tests/mystery_box.test.ts` enforces ±2pp tolerance against the spec target.\n\n### Example output\n\n```\nHOMUNCULUS CORPUS · Subject 4483 · Cohort: Wednesday\nClassification: Middle Manager · Rarity 94.5 · 80th percentile\n\nPersonnel record — Colin, Wizard of Light Bulb Moments. Distinguishing\nfeatures: a slightly-too-big blazer over a plain tee; a flip phone in\na belt holster; expression: patient disagreement. Notable behaviours:\nclips their fingernails at the desk on Wednesday afternoons; a\nkombucha SCOBY fermenting next to the keyboard; the kind to ask 'can\nwe park that?' without parking anything.\n\n— RELATABILITY CORPUS v3.1 · ingested 2024-03-08 · flagged for review\n```\n\n---\n\n## Development\n\n```bash\nnpm install          # install dependencies\nnpm run build        # compile TypeScript → dist/\nnpm run dev          # build then start the MCP server (stdio)\nnpm test             # run all 94 tests once\nnpm run test:watch   # re-run tests on file changes\n```\n\n### Inspection scripts\n\nTwo 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):\n\n```bash\nnode scripts/show-rolls.mjs 8 2026          # print 8 framed share cards (seed=2026)\nnode scripts/distribution-check.mjs 10000   # tally tiers across 10k rolls vs. spec target\n```\n\n### Project layout\n\n```\nsrc/\n  index.ts             # MCP server entry point (stdio transport)\n  identity.ts          # bling.json loader + validator\n  tools.ts             # MCP tool registrations\n  types.ts             # shared TypeScript types\n  mystery_box.ts       # WOW engine barrel + rollIdentity orchestrator\n  mystery_box/\n    rng.ts             # seedable PRNG, weighted picker\n    pools.ts           # 13 trait pools (465 entries)\n    scoring.ts         # rarity score + tier thresholds\n    rendering.ts       # paragraph templates + HOMUNCULUS frame\n    named.ts           # hand-authored Named Subjects\ntests/                 # vitest test suites\nscripts/               # dev-time inspection tools\ndocs/superpowers/      # design specs and implementation plans\n```\n\n---\n\n## License\n\nMIT\n",
  "bytes": 9621,
  "sha": "825d191963d26835c9aeb655481f598cb4f75674f39746c595c6c98b9d0b1333",
  "repo_slug": "tjclaude88/mcp-bling",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_tjclaude88_bling_bag_ced86804/readme"
}