bling-bag

Bling Bag

为你的机器人赋予身份。

你的机器人有名字了。现在为它赋予个性、外观和背景故事。

转动转盘，看看会得到什么——也可以在 bling.json 文件中编写自己的身份。

---

你将获得什么

五种 MCP 工具和两个身份池：

WOW — 古怪的办公室职员

随机生成一个古怪的办公室职员机器人：姓名、职位、办公桌布置、习惯、咖啡仪式，以及可直接截图分享的卡片。99/99 项测试通过，完整的稀有度引擎，包含 13 个加权特征池。

Legends — 历史人物

使用相同的引擎，但换个世界观。生成一位担任荒诞企业职务的历史人物——担任敌意收购专家的 Julius Caesar、实验室安全部门头号通缉犯 Marie Curie、地区经理（法国及周边地区）Napoleon。

向 roll_identity 传入 variant: "legends" 即可使用。默认值为 "wow"。

---

安装

前置条件

• Node.js 20 或更高版本
• 兼容 MCP 的客户端（Claude Code、Claude Desktop、Codex、Cursor 等）

添加程序包

npm install bling-bag

也可以按需运行，无需安装——MCP 客户端可通过 npx bling-bag 直接启动它（参见下方的客户端配置）。

用于开发（修改源代码）

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

生成可运行的服务 dist/index.js。

将其接入 MCP 客户端

此服务使用 stdio 传输——客户端会将其作为子进程启动，而非通过网络端口启动。

Claude Code

将其添加到 Claude Code MCP 配置中（位置因版本而异）：

{
  "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", "[email protected]"]

开发模式调用（从本地克隆运行）

如果你已克隆此代码库并希望直接从 dist/ 运行，请使用：

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

如果未设置 BLING_PATH，服务会在其工作目录中查找 ./bling.json。

配置解析顺序

服务按以下顺序解析 bling 配置路径：

1. --bling <path> CLI 参数（优先级最高）
2. BLING_PATH 环境变量
3. 服务工作目录中的 ./bling.json（默认）

---

bling.json — 机器人的身份文件

以下三个字段为必填项：name、personality（包含 tone、formality、humor），以及 theme（包含作为 #RRGGBB 十六进制字符串的 primary_color 和 accent_color）。

最简示例

{
  "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: "..." } 内容，指出缺失或格式错误的字段——Agent 可以据此自行修正。

---

典型 Agent 工作流

工作流 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

---

工具参考

工具	读/写	幂等	描述
get_identity	读取（磁盘）	是	返回已配置的 bling.json 身份信息
get_theme_for_platform	读取（磁盘）	是	针对平台格式化样式。参数：platform ∈ {terminal, web, slack, discord, ide}
roll_identity	修改内存缓存	否	生成一位随机 WOW 角色，并评定稀有度
save_last_roll	写入（磁盘）	否	将最近一次抽取结果保存到 bling.json（会先创建 <path>.bak）
get_rarity_report	读取（内存）	是	返回最近一次抽取结果的分享卡片文本

所有工具都会同时返回 content[].text（JSON 字符串化内容）和 structuredContent（已解析的对象）。错误会以 isError: true 和 { error: string } 格式的内容返回。

---

WOW（奇葩办公室员工）——有趣之处

随机抽取系统旨在打造收藏体验：

• 13 个加权池，共 465 个条目——姓名、职位、习惯、咖啡仪式、身高、配饰等
• 每个池分为 5 个稀有度档位——普通（50%）、少见（30%）、稀有（15%）、传奇（4%）、神话（1%）
• 根据稀有度评分计算出 5 个角色等级：
  • 档案文员（50% 的抽取结果）
  • 团队主管（30%）
  • 中层经理（14%）
  • 高管（5%）
  • HR 警告过我们（1%）
• 命名角色——手工创作的独一无二角色出现概率约为 0.5%，始终归类为“HR 警告过我们”
• HOMUNCULUS 框架——每次抽取都会将段落包装成一张机密文件分享卡片，其中包含对象 ID、群组（星期）、等级、录入日期和标记（例如 请勿联系）

分布经过实证测试：tests/mystery_box.test.ts 中的 10k 次抽取测试会根据规范目标强制执行 ±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

检查脚本

script/ 下的两个 Node ESM 辅助脚本，无需启动 MCP 服务即可检查 WOW 引擎（这些脚本仅包含在克隆的仓库中——不会随 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