bling-bag

Bling Bag

ボットにアイデンティティを与えましょう。

ボットには名前があります。次は、個性や見た目、バックストーリーを与えましょう。

ホイールを回して結果を確認するか、bling.json ファイルに独自の内容を書きましょう。

---

得られるもの

5つの MCP ツールと2つのアイデンティティプールです。

WOW — 風変わりなオフィスワーカー

名前、役職、デスク周り、習慣、コーヒーのルーティン、スクリーンショット向けのシェアカードを備えた、個性的なオフィスワーカーボットをランダムに生成します。テストは99/99件に合格し、完全なレアリティエンジンと、重み付けされた13種類の特性プールを備えています。

Legends — 歴史上の人物

同じエンジンを、異なる世界で使います。ばかげた企業の役職に就いた歴史上の人物を生成します。敵対的買収スペシャリストのユリウス・カエサル、研究所の安全管理部門が最も指名手配するマリー・キュリー、地域マネージャー（フランスおよび周辺地域）のナポレオンなどです。

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 — ボットのアイデンティティファイル

必須フィールドは3つです。name、personality（tone、formality、humor を含む）、および theme（#RRGGBB 形式の16進数文字列で指定する 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 や、# の欠落は不可）

検証エラーは、欠落または形式不正のフィールド名を示す構造化された { error: "..." } 本文とともに isError: true として返されます。エージェントは自力で修正できます。

---

エージェントの典型的なフロー

フロー 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 の ID を返します
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（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%）
• 固有名付きの対象 — 手作業で作成された 1 点もののキャラクターが約 0.5% の確率で登場し、必ず「HR Warned Us About」に分類されます
• HOMUNCULUS フレーム — ロール結果ごとに、対象 ID、コホート（曜日）、ランク、取り込み日、フラグ（例：連絡禁止）を含む機密文書風のシェアカードで段落を囲みます

分布は実測テストで検証されています。tests/mystery_box.test.ts の 10,000 回ロールテストでは、仕様の目標値に対して ±2pp の許容範囲が適用されます。

出力例

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

検査スクリプト

scripts/ にある 2 つの 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