内容
# 闪耀背包
> 给你的机器人一个身份。
你的机器人有一个名字。现在给它一个个性、外貌和背景故事。
转动轮盘，看看你会得到什么——或者在 `bling.json` 文件中编写自己的内容。
[](https://www.npmjs.com/package/bling-bag)
[](https://glama.ai/mcp/servers/tjclaude88/mcp-bling)
---
## 你会得到什么
五个 MCP 工具和两个身份池：
### WOW — 古怪的办公室职员
随机生成一个古怪的办公室职员机器人：姓名、职位、办公桌设置、习惯、咖啡仪式和一个截图-ready的分享卡。99/99 测试，完整的稀有度引擎，13 个加权特征池。
### 传奇 — 历史人物
相同的引擎，不同的宇宙。随机生成一个历史人物在荒谬的公司角色中——尤利乌斯·凯撒作为敌对收购专家，居里夫人作为实验室安全最想要的，拿破仑作为区域经理（法国及周边地区）。
将 `variant: "legends"` 传递给 `roll_identity` 以使用它。默认为 `"wow"`。
---
## 安装
### 先决条件
- Node.js 20 或更高版本
- 一个与 MCP 兼容的客户端（Claude Code、Claude Desktop、Codex、Cursor 等）
### 添加包
```bash
npm install bling-bag
```
或在不安装的情况下按需运行 — MCP 客户端可以通过 `npx bling-bag` 直接启动它（参见下面的客户端配置）。
#### 用于开发（修改源代码）
```bash
git clone https://github.com/tjclaude88/mcp-bling.git
cd mcp-bling
npm install
npm run build
```
在 `dist/index.js` 处生成一个可运行的服务器。
### 将其连接到您的 MCP 客户端
服务器使用 **stdio 传输** — 客户端将其作为子进程启动，而不是通过网络端口。
#### Claude Code
将以下内容添加到您的 Claude Code MCP 配置中（位置因版本而异）：
```json
{
"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` 中：
```json
{
"mcpServers": {
"bling": {
"command": "npx",
"args": ["-y", "bling-bag"],
"env": {
"BLING_PATH": "/absolute/path/to/your/bling.json"
}
}
}
}
```
#### 固定到版本（推荐用于生产）
为了避免自动获取未来的版本，请固定一个特定的版本：
```json
"args": ["-y", "bling-bag@0.1.0"]
```
#### 开发模式调用（从本地克隆）
如果您克隆了仓库并想直接从 `dist/` 运行，请使用：
```json
"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`**（带有 `primary_color` 和 `accent_color` 作为 `#RRGGBB` 十六进制字符串）。
### 最小示例
```json
{
"name": "Pixel",
"personality": {
"tone": "warm",
"formality": "casual",
"humor": "playful"
},
"theme": {
"primary_color": "#3A7BD5",
"accent_color": "#FFD166"
}
}
```
### 完整示例（包含所有可选部分）
```json
{
"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. 调用 get_identity → 接收名称、个性、外貌、主题
2. 调用 get_theme_for_platform，参数为 platform="terminal"（或 web/slack/discord/ide）
3. 在代理输出中使用返回的样式（ANSI 代码用于标题等）
```
### 流程 B — 生成新的随机身份
```
1. 调用 roll_identity → 接收身份 + 稀有度 + 框架分享卡
2. （可选）调用 get_rarity_report → 接收仅分享卡文本
3. 调用 save_last_roll → 将滚动的身份持久化到 bling.json（备份任何之前的配置）
4. 未来的 get_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%）
- 人力资源警告我们关于（1%）
- **命名主题** — 手工编写的 1-of-1 角色以约 0.5% 的概率出现，始终归类为“人力资源警告我们关于”
- **HOMUNCULUS 框架** — 每个滚动都将段落包装在机密文件分享卡中，带有主题 ID、队列（星期几）、等级、摄入日期和标志（例如 *请勿联系*）
分布经过实证测试：`tests/mystery_box.test.ts` 中的 10k 次滚动测试强制执行 ±2pp 容差以对抗规范目标。
### 示例输出
```
HOMUNCULUS CORPUS · 主题 4483 · 队列：星期三
分类：中层管理人员 · 稀有度 94.5 · 80th 百分位
人事记录 — Colin, 灯泡时刻的巫师。显著特征：
略大一点的西装外套配平淡的 T 恤；腰带夹层中的翻盖手机；
表情：耐心的不同意。值得注意的行为：
在星期三下午修剪指甲；在键盘旁边发酵 kombucha SCOBY；
那种会问“我们可以把那辆车停在哪里吗？”而没有停车任何东西的人。
— RELATABILITY CORPUS v3.1 · 摄入 2024-03-08 · 标记为审查
```
---
## 开发
```bash
npm install # 安装依赖
npm run build # 编译 TypeScript → dist/
npm run dev # 构建然后启动 MCP 服务器（stdio）
npm test # 运行所有 94 个测试一次
npm run test:watch # 在文件更改时重新运行测试
```
### 检查脚本
`scripts/` 下的两个 Node ESM 帮助程序允许您在不启动 MCP 服务器的情况下检查 WOW 引擎（这些仅在克隆的仓库中包含 — 它们 **不** 包含在 `npm install bling-bag` 包中）：
```bash
node scripts/show-rolls.mjs 8 2026 # 打印 8 张框架分享卡（种子=2026）
node scripts/distribution-check.mjs 10000 # 在 10k 次滚动中统计等级与规范目标的对比
```
### 项目布局
```
src/
index.ts # MCP 服务器入口点（stdio 传输）
identity.ts # bling.json 加载器 + 验证器
tools.ts # MCP 工具注册
types.ts # 共享 TypeScript 类型
mystery_box.ts # WOW 引擎桶 + rollIdentity 协调器
mystery_box/
rng.ts # 可种子的 PRNG，加权选择器
pools.ts # 13 个特征池（465 个条目）
scoring.ts # 稀有度评分 + 等级阈值
rendering.ts # 段落模板 + HOMUNCULUS 框架
named.ts # 手工编写的命名主题
tests/ # vitest 测试套件
scripts/ # 开发时检查工具
docs/superpowers/ # 设计规格和实现计划
```
---
## 许可证
MIT
