Random Tables MCP Server

随机表 MCP 服务

从手动翻阅资料书，到费力处理嵌套的 Excel 公式，我试过各种随机表解决方案——这正是我构建 MCP Random Tables 的原因：我一直想要一个灵活的生成工具。

这个 MCP（Model Context Protocol） 服务连接了不同的使用场景：导入你的表格，以便与大模型交互；也可以使用独立脚本，实现无需消耗 token 的高效体验。无论采用哪种方式，六边形架构都能让随机生成保持井然有序、易于维护，并在灵感枯竭时随时派上用场。

项目概览

我的随机表之旅对许多人来说可能并不陌生——从实体书籍和骰子起步，逐渐转向带公式的电子表格，如今又开始探索大模型领域的各种可能。这个服务是这段旅程的集大成之作，旨在灵活处理从简单查询到复杂嵌套表格的各种需求，满足现代城主的期待。

为什么采用六边形架构？因为随着我自己的需求从手动查询发展到程序化生成，我明白了：让核心逻辑与访问方式相互独立，才是长久发展的关键：

• 关注点分离：无论以何种方式使用，表格定义和掷骰逻辑都能保持纯粹
• 可测试性：无需启动完整环境，即可验证每条随机生成规则
• 灵活性：今天用于大模型交互，明天用于独立脚本——核心系统可以灵活适应，而无需破坏现有功能
• 可维护性：随着生态系统变化，你在创建表格上的投入仍能得到保护

我正在积极开发功能部分提到的基于脚本的工具，确保你可以在有无大模型的情况下使用这个系统——让你能够针对不同情况自由选择合适的方式，同时利用同样强大的表格结构。

功能

• 创建随机表只需几秒，并随时更新
• 掷骰后即可立即获得任意表格的结果
• 关联表格，并通过强大的模板支持将它们连接起来
• 定义基于范围的条目，用于掷骰驱动的表格
• 设置权重以微调条目的概率
• 管理可复用内容的独立掷骰模板
• 选择访问方式：MCP 资源 或 工具（切换方式请参阅环境变量部分）

可用工具

表格工具

• 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 工具 - 表格和模板掷骰功能 - 掷骰表格并解析模板
• 本地工具 - 掷骰器 - JavaScript 控制台应用，可使用服务端逻辑掷骰表格或解析模板，无需使用大模型
• 本地工具 - 简单文本导入 - 控制台应用扩展，可从文本文件（权重均为 1）或 CSV 文件（包含名称、描述和权重格式）创建表格

真实示例

注意：为便于阅读，以下示例使用简化的表格 ID（例如 "gold-quantities"）。在实际实现中，表格 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" 表格上掷骰一次。

多次掷骰：

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

在 "items" 表格上掷骰 3 次，结果以逗号分隔。

自定义分隔符：

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

在 "monsters" 表格上掷骰两次，结果以 "||" 分隔。

嵌套表格示例

以下是串联表格的方法：

{
  "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 Resources 还是 Tools（默认值：false）

  • 设置为 true 时：使用 TableResource 和 TemplateResource 访问表格和模板
  • 未设置或设置为其他值时：使用 GetTableTool 和 GetTemplateTool，而非资源

这样可以兼容可能无法全面支持 MCP Resources 的大模型客户端。

开发

# 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/ - 测试整个系统

贡献

有想法或发现了 Bug？提交一个 issue，让我们聊聊——欢迎提交 PR！更多详情请参阅贡献指南。

许可证

本项目采用 MIT License 发布。