Random Tables MCP Server

Random Tables MCP サーバー

ソースブックを手作業でめくる方法から、入れ子になった Excel の数式との格闘まで、あらゆるランダムテーブルの解決策を試してきました。だからこそ、ずっと欲しかった柔軟な生成ツールとして MCP Random Tables を作りました。

この MCP（Model Context Protocol） サーバーは、異なる世界をつなぎます。LLM とのやり取りに使うテーブルを追加することも、単体スクリプトを使ってトークンを消費せずに効率よく利用することもできます。いずれの場合も、六角形アーキテクチャによってランダム生成が整理され、保守しやすく、ひらめきが枯れたときにもすぐ使える状態に保たれます。

プロジェクト概要

私のランダムテーブルとの付き合いは、多くの方にとっておなじみかもしれません。物理書籍とサイコロから始まり、数式入りのスプレッドシートを経て、今では LLM の可能性を探っています。このサーバーはその道のりの集大成として作られており、単純な検索から複雑な入れ子のテーブルまで、現代の GM にふさわしい柔軟性を備えて対応します。

六角形アーキテクチャを採用した理由は何でしょうか。手動での検索からプログラムによる生成へと自分のニーズが変化するなかで、アクセス方法からコアロジックを分離しておくことが、長く使い続ける鍵だと学んだからです。

• 関心の分離：どのような方法で利用しても、テーブル定義とロールのロジックはそのまま保たれます
• テスト容易性：環境全体を起動せずに、ランダム生成の各ルールを検証できます
• 柔軟性：今は LLM とのやり取りに使い、明日は単体スクリプトに使うといったように、コアシステムを壊すことなく適応できます
• 保守性：エコシステムが変化しても、テーブル作成にかけた労力は保護されます

機能セクションで紹介しているスクリプトベースのツールにも現在取り組んでいます。LLM の有無にかかわらずこのシステムを利用できるようにし、同じ強力なテーブル構造を活用しながら、状況に応じて適切な方法を自由に選べるようにしています。

機能

• ランダムテーブルを数秒で作成し、最新の状態に保ちます
• あらゆるテーブルで結果をすぐにロールします
• 強力なテンプレートサポートでテーブルをリンクします
• サイコロベースのテーブル向けに範囲指定のエントリーを定義します
• エントリーに重みを設定して確率を調整します
• 再利用可能なコンテンツとして単体のロールテンプレートを管理します
• アクセス方式として MCP Resources または Tools を選択します（切り替え方法については、環境変数セクションをご覧ください）

利用可能なツール

テーブルツール

• create_table - 初期エントリーを任意で含めて、新しいランダムテーブルを作成します
• roll_on_table - 指定したテーブルでロールし、結果を返します
• update_table - 既存のテーブル（名前、説明、エントリー）を更新します
• list_tables - 利用可能なテーブルをメタデータとともに一覧表示します
• get_table - 指定したテーブルの詳細を取得します

テンプレートツール

• create_template - 新しいロールテンプレートを作成します
• get_template - ID を指定してロールテンプレートを取得します
• list_templates - 利用可能なすべてのロールテンプレートを一覧表示します
• update_template - 既存のロールテンプレートを更新します
• delete_template - ID を指定してロールテンプレートを削除します
• evaluate_template - テーブルへのすべての参照を解決して、ロールテンプレートを評価します

ツールとリソースの切り替え方法については、環境変数セクションをご覧ください。

利用可能なリソース

テーブルリソース

• table://{tableId} - 指定したテーブルにアクセスします
• tables:// - すべてのテーブルの一覧にアクセスします

テンプレートリソース

• template://{id} - 指定したロールテンプレートにアクセスします
• templates:// - すべてのロールテンプレートの一覧にアクセスします

主なユースケース

• RPG の遭遇生成：テーブルトーク RPG のランダムな遭遇を生成します
• 戦利品の生成：動的な宝物やアイテムのドロップを作成します
• NPC の生成：性格特性、装備、動機を備えた複雑な NPC を作成します
• ストーリーのプロンプト生成：創作のプロンプトやプロットのきっかけを生成します
• 再利用可能なテンプレート：複数のテーブルで使用できる単体テンプレートを作成します

機能チェックリスト

• MCP ツール - テーブルの CRUD - ランダムテーブルの作成、読み取り、更新、削除
• MCP ツール - テンプレートの CRUD - ロールテンプレートの作成、読み取り、更新、削除
• MCP ツール - テーブルとテンプレートのロール関数 - テーブルでロールし、テンプレートを解決
• ローカルツール - Roller - LLM を使わずに、サーバーのロジックを使ってテーブルでロールしたり、テンプレートを解決したりする JavaScript コンソールアプリ
• ローカルツール - シンプルなテキストの取り込み - テキストファイル（重み 1 で均等）または CSV ファイル（名前、説明、重みの形式）からテーブルを作成する、コンソールアプリの拡張機能

実際の使用例

注：以下の例では、読みやすさのために「gold-quantities」のような簡略化したテーブル ID を使用しています。実際の実装では、テーブル ID は UUID（例：「b2cf46a1-1884-4492-8770-d1b7e796355d」）です。テンプレート構文の構造には厳密なルールがあり、正確に従う必要があります。さらに詳しい例については、シンプルな遭遇ガイドとネストされた財宝ガイドをご覧ください。

シンプルな遭遇テーブル

さまざまな遭遇の種類に重みを付けた項目を使って、森での遭遇テーブルを作成します。

{
  "name": "Low-Mid Level Forest Encounters",
  "description": "A varied table of forest encounters for low to mid-level adventurers",
  "entries": [
    {
      "content": "A pack of 2-4 wolves emerges from the underbrush, hungry and territorial",
      "weight": 4
    },
    {
      "content": "Hidden pit trap covered by branches and leaves (10 ft deep, 1d6 damage)",
      "weight": 3
    },
    {
      "content": "Mischievous sprites swap one random item from each character's pack with forest debris",
      "weight": 2
    },
    {
      "content": "A dryad's tree is being cut down by loggers - she pleads for help",
      "weight": 1
    }
  ]
}

重みが大きい（4）遭遇は、まれな遭遇（1）よりも発生しやすくなります。

ネストされた財宝システム

相互に連携する複数のテーブルを使って、包括的な財宝生成システムを作成します。

{
  "name": "Treasure Types",
  "description": "Parent table for different types of treasure",
  "entries": [
    {
      "content": "{{Gold::gold-quantities}}",
      "weight": 1
    },
    {
      "content": "{{Gemstone::gemstones}}",
      "weight": 1
    },
    {
      "content": "{{Weapon::weapons}} that is {{Quirk::weapon-quirks}}",
      "weight": 1
    }
  ]
}

このテーブルでロールすると、他のテーブル（gold-quantities、gemstones、weapons、weapon-quirks）への参照が自動的に解決され、「金貨の入った袋」や「内なる炎で輝く剣」のような、豊かで変化に富んだ結果が生成されます。

テンプレートシステム

テンプレートシステムでは、他のテーブルを参照することで、複雑でネストされたランダム生成システムを作成できます。テンプレートでは、柔軟な構文で二重の波括弧を使用します。

{{reference-title::table-id::table-name::roll-number::separator}}

各要素の意味は次のとおりです。

• reference-title：参照のタイトル（省略可）
• table-id：ロールするテーブルの ID
• table-name：読みやすさのためのテーブル名（省略可）
• roll-number：ロールする回数（デフォルト：1）
• separator：複数回のロール結果を区切る文字列（デフォルト：「, 」）

基本的な例

単純な参照：

{
  "content": "{{::currency}}"
}

「currency」テーブルで 1 回ロールします。

複数回のロール：

{
  "content": "{{::items::Items::3}}"
}

「items」テーブルで 3 回ロールし、結果をカンマで区切ります。

カスタム区切り文字：

{
  "content": "{{::monsters::Monsters::2::||}}"
}

「monsters」テーブルで 2 回ロールし、結果を「||」で区切ります。

ネストされたテーブルの例

次のようにテーブルを連鎖させることができます。

{
  "name": "Treasure",
  "description": "Random treasure found in dungeons",
  "entries": [
    {
      "content": "{{::currency}}",
      "weight": 3
    },
    {
      "content": "{{::items::Items::3}} worth {{::currency}}",
      "weight": 2
    }
  ]
}

このテーブルでロールすると、システムは参照先のテーブルでロールし、テンプレートを自動的に解決します。

単独のテンプレート

複数のテーブルで再利用できる、単独のテンプレートを作成することもできます。

{
  "name": "NPC Description",
  "description": "Template for generating NPC descriptions",
  "template": "A {{::appearance}} {{::race}} {{::class}} who {{::personality}}"
}

これらのテンプレートはテーブルとは独立して管理できるため、コンテンツをよりモジュール化し、再利用しやすくできます。

要件

• Node.js（v20 以降）
• npm

インストール

Claude Desktop との連携

MCP Random Tables サーバーを Claude Desktop と連携するには、claude_desktop_config.json ファイルにサーバー設定を追加する必要があります。

{
  "mcpServers": {
    "random-tables": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "random-tables-mcp"],
      "env": {} // Empty object uses default values
    }
  }
}

空の env オブジェクトを使用すると、サーバーはデフォルト値（DATA_DIR='./data'、CAN_USE_RESOURCE='false'）を使用します。これらの値を変更する場合は、明示的に指定してください。

{
  "mcpServers": {
    "random-tables": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "random-tables-mcp"],
      "env": {
        "DATA_DIR": "/path/to/your/preferred/data/directory",
        "CAN_USE_RESOURCE": "true"
      }
    }
  }
}

手動インストール

# Clone the repository
git clone https://github.com/MikeORed/random-tables-mcp
cd random-tables-mcp

# Install dependencies
npm install

# Build the project
npm run build

環境変数

サーバーは、次の環境変数を使って設定できます。

• DATA_DIR：テーブルデータを保存するディレクトリ（デフォルト：./data）

• CAN_USE_RESOURCE：特定の機能で MCP リソースとツールのどちらを使用するかを制御します（デフォルト：false）

  • true に設定した場合：テーブルとテンプレートへのアクセスに TableResource と TemplateResource を使用します
  • 未設定またはその他の値の場合：リソースの代わりに GetTableTool と GetTemplateTool を使用します

これにより、MCP リソースを完全にはサポートしていない LLM クライアントとの互換性が得られます。

開発

# Run in development mode
npm run dev

# Run tests
npm test

# Build the project
npm run build

# Run the built project
npm start

トラブルシューティング – 問題が発生した場合は、ここから始めましょう。

よくある問題：

1. Claude Desktop にサーバーが表示されない

   • 設定ファイルの構文を確認してください
   • パスが絶対パスで、正しいことを確認してください
   • 設定を変更した後は、Claude Desktop を再起動してください

2. ツールの実行に失敗する

   • Claude Desktop のログを次の場所で確認してください：

     • macOS：~/Library/Logs/Claude/mcp*.log
     • Windows：%APPDATA%\\Claude\\logs\\mcp*.log

ドキュメント

包括的なドキュメントは、docs ディレクトリで確認できます：

• ガイドと例 - テーブルの例と使用シナリオ
• 開発者向けドキュメント - アーキテクチャの詳細、拡張ポイント、実装上の判断

プロジェクト構成

/
├── docs/                # Documentation for users and developers
├── src/                 # Source code
│   ├── domain/          # Core domain entities and value objects
│   ├── ports/           # Interface definitions for primary and secondary ports
│   ├── useCases/        # Application use cases and service implementations
│   ├── adapters/        # Primary and secondary adapters
│   │   ├── primary/     # Adapters that drive the application (MCP server)
│   │   └── secondary/   # Adapters driven by the application (persistence, RNG)
│   └── index.ts         # Application entry point
├── test/                # Test files
│   ├── unit/            # Unit tests for individual components
│   ├── integration/     # Tests for component interactions
│   └── e2e/             # End-to-end tests
└── scripts/             # Build and utility scripts

テスト

このプロジェクトでは、テストに Jest を使用しています。次のコマンドでテストを実行できます：

npm test

テスト基準

テスト配置の基準：

• すべてのテストは test/ ディレクトリに配置し、src/ ディレクトリの構成を反映させてください。
• たとえば、src/adapters/secondary/rng/DefaultRandomNumberGenerator.ts のテストは、test/unit/adapters/secondary/rng/DefaultRandomNumberGenerator.test.ts に配置してください。

テストの種類：

• 単体テスト：test/unit/ - 各コンポーネントを個別にテストします
• 統合テスト：test/integration/ - コンポーネント間の連携をテストします
• エンドツーエンドテスト：test/e2e/ - システム全体をテストします

コントリビューション

アイデアやバグがあれば、イシューを作成して話し合いましょう。PR も歓迎します。詳しくはコントリビューションガイドをご覧ください。

ライセンス

このプロジェクトはMIT ライセンスの下で公開されています。