Random Tables

@pipeworx/random-tables

Pipeworx 原创的可组合随机表，适用于桌面游戏和叙事游戏——遭遇、战利品、天气、意外状况、NPC 特征、剧情钩子、酒馆场景、传闻和聚居地怪癖；支持递归解析嵌套的 {{table:<id>}} 引用，也支持调用方提供自定义表。无需密钥、无上游依赖、无 COGS。

属于 Pipeworx——一个将 AI Agent 连接到 1872+ 个实时数据源的 MCP 网关。这是一个独立的非官方集成，与上游提供方无关联、未获其认可，也未由其发布。

工具

• roll_table(table, count?, seed?, session_id?) — 从内置表中随机抽取 1 到 20 个条目。返回原始条目文本和完全解析后的文本（展开嵌套的 {{table:<id>}} 引用）。可通过 seed 重现结果。
• roll_custom_table(entries, count?, seed?) — 从你提供的表中随机抽取（[{text, weight?}]）；条目也可以像内置表一样引用内置表。
• list_random_tables(genre?) — 列出每个内置表的 ID、标题、类型和条目数；可选按 fantasy | scifi | modern 筛选。
• get_random_table(table) — 完整获取一个内置表，未经解析（原始条目文本，因此可见其中写明的任何 {{table:<id>}} 引用）。

内置表

encounters_fantasy、encounters_scifi、encounters_modern、loot、weather、complication、npc_personality、npc_secret、npc_occupation、plot_hook、tavern、rumour、settlement_quirk、npc_full（由 npc_personality + npc_occupation + npc_secret 嵌套组成的完整句子，是嵌套引用的示例）。

带类型标签的表（encounters_*、loot、tavern）分别采用奇幻、科幻或现代风格；其余表不限定类型，适用于 list_random_tables 的任何类型筛选条件。

嵌套引用

条目文本中可以嵌入 {{table:<id>}}，系统会从该表中按权重随机抽取一个条目并替换进去，最多递归嵌套 6 层。引用未知表 ID 或发生循环（表通过一系列其他引用最终引用自身）时，会明确报错并指出出错的 ID 或完整引用链，绝不会静默截断或替换为空。roll_custom_table 的调用方自定义条目也可以用相同方式引用内置表，但不能引用同一自定义表中的其他条目（自定义表没有可供引用的 ID）。

随机性与可重现性

所有随机抽取工具都接受可选的 seed；实际使用的种子始终会返回（位于 meta.seed），无论你是否提供种子。同样的种子和参数会产生相同的结果。这些工具用于生成内容，而非占卜——不存在需要与解读区分开的单独“含义”层；表中的文本就是结果，你在游戏中如何使用它由你决定。

会话

roll_table 中的 session_id 可在多次调用之间实现不重复抽取——适用于你不希望同一件战利品或同一条传闻在会话进行期间重复出现的情况。此功能仅托管环境支持，依赖网关的共享 KV（injectCacheKv: true）；npm 独立包没有 KV，因此在那里传入 session_id 的调用会返回 session_supported: false，并改为执行普通的带种子抽取（无论运行环境如何，不传 session_id 时所有工具都能正常工作）。

没有单独的“开启会话”工具。首次为某个表调用时，在 session_id 中传入任意字符串——响应会明确告知是否延续了现有会话，或是否需要开启新会话，并提供下次调用时应复用的实际 session_id。完全省略 session_id，即可执行普通的独立加权抽取（最常见的用法；无需 KV）。roll_custom_table 不支持会话——会话只跟踪内置表，因为内置表有稳定的 ID 和大小，可用于标识会话。

身份验证

无需密钥。

数据源

Pipeworx 原创内容。没有上游 API，也没有第三方数据。每张表和每个条目都是为这个数据包编写的——没有任何内容复制、自商业桌面角色扮演游戏产品、资料集或补充材料中改写或改编。

其他须知

• 零行结果会明确报错，而不是静默返回空列表：未知的表 ID、未知的类型筛选条件、未知或循环的嵌套引用，或 roll_custom_table 中为空或无效的 entries 数组，都会抛出具体错误并列出有效集合，而不是返回 [] 或 {}。
• roll_table 的默认 count 为 1；两种投掷工具的上限均为 20。
• roll_custom_table 最多接受调用方提供的 500 个条目。

快速开始

添加到你的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "random-tables": {
      "url": "https://gateway.pipeworx.io/random-tables/mcp"
    }
  }
}

此端点实际提供的内容

对 https://gateway.pipeworx.io/random-tables/mcp 调用 tools/list，会返回上表中的工具，以及 Pipeworx 共享元工具——ask_pipeworx、discover_tools、search_within、remember/recall，以及网关全局工具集中的其他工具。因此，你看到的工具数量会多于此表所列：目前，单个数据包端点除了列出该数据包自身的工具，还会列出约 30 个共享工具。连接的 initialize 响应会说明其确切范围，是当天情况的权威依据。

这是有意为之，并非意外的多路复用。元工具让限定范围的连接也能回答此数据包未涵盖的问题——通过 ask_pipeworx 跨整个目录路由——无需再添加第二个 MCP 服务。目前无法在不包含这些工具的情况下挂载数据包端点；如果额外的架构信息占用的上下文比路由带来的价值更大，不如只连接一次完整网关，而不是连接多个数据包端点。

也可以连接完整的 Pipeworx 网关，以直接列出所有数据包的工具，而不只是此数据包的工具：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

两个 URL 都连接到同一个网关和相同的 1872+ 个数据源。唯一的区别是直接列出哪个数据包的工具；通过任一端点，ask_pipeworx 都能访问所有工具。

没有 MCP 客户端？通过 HTTP 调用

curl -X POST https://gateway.pipeworx.io/v1/tools/roll_table \
  -H 'Content-Type: application/json' \
  -d '{"table":"npc_full","count":2,"seed":"pw-smoke-1"}'

首次调用无需账户。查看任意工具：GET https://gateway.pipeworx.io/v1/tools/roll_table。查找工具：向 https://gateway.pipeworx.io/v1/tools/search_packs 发送 POST 请求，参数为 {"query":"..."}。

独立运行（无需网关账户）

此软件包也可以作为本地 stdio MCP 服务运行——无需 Pipeworx 账户，也无需经过网关往返：

{
  "mcpServers": {
    "random-tables": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-random-tables"]
    }
  }
}

或者直接运行以确认服务已启动：

npx -y @pipeworx/mcp-random-tables

它通过 stdin/stdout 使用 MCP 通信，并为此数据包自身的工具响应 initialize/tools/list/tools/call——不包含上文网关连接提供的共享元工具。数据源相同，工具相同，但没有 ask_pipeworx 路由。

使用 ask_pipeworx

你也可以用通俗英语提问，而不是直接调用工具——在上文的数据包端点和完整网关上都可以使用：

ask_pipeworx({ question: "your question about Random Tables data" })

网关会自动选择合适的工具并填入参数。

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT