mcp-bling

mcp-bling 是一个用于给 AI 智能体赋予持久身份与跨平台视觉风格的开源项目，同时提供随机身份生成能力，带有稀有度分级和可分享卡片。

用途

为机器人提供身份：不仅是名称，还包括个性、外观与背景故事。用户可以随机抽取身份，也可以通过 bling.json 文件自行编写身份。

主要能力

项目提供五个 MCP 工具和两套身份池：

WOW — Weird Office Workers（怪诞办公室打工人）随机生成古怪的办公室打工人机器人，包含姓名、职位、办公桌配置、习惯、咖啡仪式，以及适合截图的分享卡片。该项目宣称拥有 99/99 测试、完整的稀有度引擎和 13 个加权特质池。
Legends — Historical Figures（历史人物）使用相同引擎但不同世界观，随机生成历史人物担任荒诞的企业角色，例如 Julius Caesar 担任 Hostile Takeover Specialist、Marie Curie 担任 Lab Safety's Most Wanted、Napoleon 担任 Regional Manager（France & Surrounding Areas）。在 roll_identity 中传入 variant 参数为 "legends" 即可使用该池，默认值为 "wow"。

使用方式

环境要求

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

安装与运行

可以添加安装包，也可以无需安装按需运行——MCP 客户端可通过 npx bling-bag 直接启动它。构建后在 dist/index.js 生成可运行的服务器。

接入 MCP 客户端

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

添加到 Claude Code MCP 配置（位置因版本而异）： npx -y bling-bag 会下载并运行最新版本，无需单独安装步骤。

claude_desktop_config.json 中配置形状相同。若不想自动获取未来版本，可固定特定版本。若已克隆仓库并希望直接从 dist/ 运行，可使用相应方式。若未设置 BLING_PATH，服务器会在其工作目录中查找 ./bling.json。

配置解析顺序

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

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

bling.json — 机器人身份文件

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

校验规则：

name — 非空字符串
personality.tone、personality.formality、personality.humor — 非空字符串
theme.primary_color、theme.accent_color — 必须匹配 ^#[0-9A-Fa-f]{6}$（不支持简写 #RGB，不可缺失 #）

校验错误会以 isError: true 返回，并带有结构化的 { error: "..." } 内容，指出缺失或格式错误的字段，智能体可以据此自行修正。

典型智能体流程

流程 A — 采用已配置的身份流程 B — 生成全新的随机身份

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

WOW（Weird Office Workers）的特别之处

随机抽取系统为可收集性而设计：

13 个加权池，465 个条目——姓名、职位、习惯、咖啡仪式、身高、配饰等
每个池有 5 档稀有度——Common (50%)、Uncommon (30%)、Rare (15%)、Legendary (4%)、Mythic (1%)
根据稀有度分数计算 5 个角色层级：Filing Clerk（50% 的抽取结果）、Team Lead（30%）、Middle Manager（14%）、C-Suite（5%）、HR Warned Us About（1%）
Named Subjects——手工编写的唯一角色以约 0.5% 概率出现，始终归类为 "HR Warned Us About"
HOMUNCULUS 框架——每次抽取都将段落包裹在带有 subject ID、cohort（星期几）、tier、ingestion date 和标记（如 Do Not Contact）的机密文档分享卡片中
分布经过实证测试：tests/mystery_box.test.ts 中的 1 万次抽取测试按 ±2 个百分点容差对照规格目标进行验证。

检查脚本

scripts/ 下有两个 Node ESM 辅助脚本，可让用户在不启动 MCP 服务器的情况下检查 WOW 引擎（这些仅包含在克隆的仓库中——不会随 npm install bling-bag 包发布）。

适用场景与限制

适用场景：为 AI 智能体赋予个性化身份与视觉风格，生成随机角色用于娱乐、演示或内容创作。限制：需要 Node.js 20+ 与兼容 MCP 的客户端；服务器使用 stdio 传输；检查脚本仅存在于克隆仓库中；其他具体限制暂未提供。