hypercross
/
ttrpg-tools
2
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ttrpg-tools/docs/mcp.md

13 KiB
Raw Blame History

MCP 服务器使用说明

TTRPG Tools 提供了一个 MCP (Model Context Protocol) 服务器，用于与 AI 助手集成，自动化生成和管理卡牌内容。

命令结构

ttrpg mcp [command]

子命令

1. mcp serve - 启动 MCP 服务器

启动 MCP 服务器，供 AI 助手连接使用。

# 使用 stdio 传输（默认）
ttrpg mcp serve

# 指定传输方式
ttrpg mcp serve stdio

MCP 客户端配置示例：

{
  "mcpServers": {
    "ttrpg-card-generator": {
      "command": "node",
      "args": ["path/to/ttrpg-tools/dist/cli/index.js", "mcp", "serve"]
    }
  }
}

2. mcp generate-card-deck - 快速生成卡牌组

通过命令行快速生成卡牌组，无需 MCP 客户端。

ttrpg mcp generate-card-deck --name "卡牌名称" --output "./输出目录" [选项]

选项：

选项 说明 默认值
--name <name> 卡牌组名称（必需） -
--output <dir> 输出目录（必需） -
-c, --count <number> 卡牌数量 10
--fields <fields> 字段列表（逗号分隔） name,type,cost,description
--description <desc> 卡牌组描述 -
--size <size> 卡牌尺寸 54x86
--grid <grid> 网格布局 5x8

示例：

# 生成基础魔法物品卡牌
ttrpg mcp generate-card-deck --name "魔法物品" --output "./content"

# 生成自定义 NPC 卡牌
ttrpg mcp generate-card-deck \
  --name "NPC Cards" \
  --output "./content/npcs" \
  --count 20 \
  --fields "name,class,level,background" \
  --description "快速生成游戏中的 NPC 角色"

# 生成塔罗牌组
ttrpg mcp generate-card-deck \
  --name "Tarot Deck" \
  --output "./content/tarot" \
  --count 22 \
  --fields "name,number,meaning" \
  --size "70x120" \
  --grid "3x4"

MCP 工具

通过 MCP 协议，AI 助手可以调用以下工具：

快捷工具

generate_card_deck - 一站式生成卡牌组

快速生成完整的卡牌组，包括 Markdown 文件、CSV 数据文件和组件配置。

参数 类型 必需 说明
deck_name string ✓ 卡牌组名称
output_dir string ✓ 输出目录路径
card_count number ✗ 卡牌数量（默认：10）
card_template object ✗ 卡牌模板定义
deck_config object ✗ md-deck 组件配置
description string ✗ 卡牌组描述

核心工具

deck_frontmatter_read - 读取 CSV frontmatter

读取 CSV 文件的 frontmatter（包含模板定义和 deck 配置）。

参数 类型 必需 说明
csv_file string ✓ CSV 文件路径

返回示例：

{
  "fields": [
    { "name": "name", "description": "卡牌名称" },
    { "name": "type", "description": "卡牌类型" }
  ],
  "deck": {
    "size": "54x86",
    "grid": "5x8"
  }
}

deck_frontmatter_write - 写入 CSV frontmatter

写入或更新 CSV 文件的 frontmatter（模板定义和 deck 配置）。

参数 类型 必需 说明
csv_file string ✓ CSV 文件路径
frontmatter object ✓ 要写入的 frontmatter 数据
merge boolean ✗ 是否合并现有 frontmatter（默认 true）

frontmatter 结构：

{
  "fields": [
    {
      "name": "字段名称（英文，用于 CSV 列名）",
      "description": "字段描述",
      "examples": ["示例值 1", "示例值 2"]
    }
  ],
  "deck": {
    "size": "54x86",
    "grid": "5x8",
    "bleed": 1,
    "padding": 2,
    "shape": "rectangle",
    "layers": "name:1,2-3,12",
    "back_layers": "back:1,2-8,12"
  }
}

deck_card_crud - 卡牌 CRUD 操作

卡牌的创建、读取、更新、删除操作，支持批量操作。

参数 类型 必需 说明
csv_file string ✓ CSV 文件路径
action string ✓ 操作类型：create | read | update | delete
cards object|array ✗ 卡牌数据（单张或数组）
label string|array ✗ 要操作的卡牌 label（用于 read/update/delete）

卡牌数据结构：

{
  "label": "1",
  "name": "火球术卷轴",
  "type": "法术",
  "cost": "3",
  "description": "造成 5d6 火焰伤害"
}

使用示例：

// 创建单张卡牌
{
  "csv_file": "./content/magic-items.csv",
  "action": "create",
  "cards": {
    "label": "1",
    "name": "火球术卷轴",
    "type": "法术",
    "cost": "3",
    "description": "造成 5d6 火焰伤害"
  }
}

// 批量创建卡牌
{
  "csv_file": "./content/magic-items.csv",
  "action": "create",
  "cards": [
    { "name": "火球术卷轴", "type": "法术", "cost": "3" },
    { "name": "治疗药水", "type": "物品", "cost": "2" }
  ]
}

// 读取所有卡牌
{
  "csv_file": "./content/magic-items.csv",
  "action": "read"
}

// 读取指定卡牌
{
  "csv_file": "./content/magic-items.csv",
  "action": "read",
  "label": ["1", "2"]
}

// 更新卡牌
{
  "csv_file": "./content/magic-items.csv",
  "action": "update",
  "cards": { "label": "1", "cost": "4" }
}

// 删除卡牌
{
  "csv_file": "./content/magic-items.csv",
  "action": "delete",
  "label": ["1", "2"]
}

deck_preview - 保存并预览卡牌组

保存 CSV 对应的 Markdown 预览文件并打开浏览器预览。

参数 类型 必需 说明
csv_file string ✓ CSV 文件路径
md_file string ✗ Markdown 文件路径（可选，默认与 CSV 同名）
title string ✗ 标题（可选，默认从 CSV 文件名推断）
description string ✗ 描述（可选）

返回示例：

{
  "success": true,
  "message": "预览文件已创建",
  "preview_url": "http://localhost:3000/#/content/cards.md"
}

CSV 文件格式

CSV 文件使用 YAML frontmatter 定义模板和配置：

---
fields:
  - name: name
    description: 卡牌名称
  - name: type
    description: 卡牌类型
    examples: [物品，法术，生物]
  - name: cost
    description: 费用
  - name: description
    description: 效果描述
deck:
  size: 54x86
  grid: 5x8
  bleed: 1
  padding: 2
---
label,name,type,cost,description
1，火球术卷轴，法术，3，造成 5d6 火焰伤害
2，治疗药水，物品，2，恢复 2d4+2 生命值

Frontmatter 说明

  • fields: 字段定义列表
    • name: 字段名称（英文，用于 CSV 列名）
    • description: 字段描述
    • examples: 示例值列表（可选）
  • deck: Deck 配置
    • size: 卡牌尺寸，格式 "宽 x 高"（单位 mm）
    • grid: 网格布局，格式 "列 x 行"
    • bleed: 出血边距（mm）
    • padding: 内边距（mm）
    • shape: 卡牌形状（rectangle, circle, hex, diamond）
    • layers: 正面图层配置
    • back_layers: 背面图层配置

CSV 数据说明

  • label: 卡牌标签（唯一标识，用于查找和修改）
  • 其他列：由 frontmatter 中的 fields 定义
  • body: 卡牌 body 内容（可选，支持 {{字段名}} 语法）

MCP Resources

MCP 服务器提供以下 Resources，包含 TTRPG Tools 的文档和参考材料：

ttrpg-docs://csv - CSV 编写说明

名称： csv.md
标题： CSV 编写说明
描述： TTRPG Tools CSV 文件格式说明，包括 Front Matter、字段定义、变量语法等

内容包含：

  • YAML Front Matter 结构（fields、deck、自定义属性）
  • 数据类型（word、paragraph、number、symbol、symbol_list）
  • 字段功能（identify、compare、flavor、rule）
  • CSV 数据格式和特殊字符处理
  • 变量语法（{{prop}}）
  • 分组支持
  • 完整示例（魔法物品、随机遭遇表、NPC 名录）

ttrpg-docs://markdown - Markdown 编写说明

名称： markdown.md
标题： Markdown 编写说明
描述： TTRPG Tools Markdown 扩展语法和组件用法说明

内容包含：

  • 基础语法（GFM、marked-alert、marked-directive）
  • 指令语法格式
  • 图标语法（:[icon-name]）
  • 组件库：
    • :md-dice - 骰子组件
    • :md-link - 链接组件
    • :md-bg - 背景组件
    • :md-pins - 标记组件
    • :md-table - 表格组件
    • :md-deck - 卡牌组件
    • :md-yarn-spinner - 叙事线组件
    • :md-token - 代币组件
    • :md-commander - 命令追踪器
  • YAML 标签
  • Mermaid 图表
  • 警告/提示块
  • 文件引用规则
  • 样式定制

使用示例

列出所有 Resources：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/list"
}

读取 Resource：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "resources/read",
  "params": {
    "uri": "ttrpg-docs://csv"
  }
}

MCP Prompts

MCP 服务器提供以下 Prompts，用于引导用户完成卡牌设计工作流：

design-card-game - 设计卡牌游戏

引导用户设计新的卡牌游戏系统，定义卡牌模板和字段结构。

参数：

参数 类型 必需 说明
deck_name string ✗ 卡牌组名称
output_dir string ✗ 输出目录（相对路径）
game_theme string ✗ 游戏主题/类型（如：奇幻、科幻、恐怖等）

使用示例：

{
  "name": "design-card-game",
  "arguments": {
    "deck_name": "魔法物品",
    "output_dir": "./content",
    "game_theme": "奇幻"
  }
}

返回内容：

Prompt 会返回一个对话式的引导流程，帮助 AI 助手了解：

  1. 卡牌类型（角色卡、物品卡、法术卡等）
  2. 核心机制（费用系统、稀有度、阵营等）
  3. 卡牌信息字段

并提供常见配置的示例参考。

populate-deck - 填充卡牌内容

为已有的卡牌组生成和填充卡牌内容。

参数：

参数 类型 必需 说明
csv_file string ✗ CSV 文件路径
card_count number ✗ 要生成的卡牌数量
theme string ✗ 卡牌主题/描述

使用示例：

{
  "name": "populate-deck",
  "arguments": {
    "csv_file": "./content/magic-items.csv",
    "card_count": 20,
    "theme": "火焰主题法术"
  }
}

返回内容：

Prompt 会引导 AI 助手：

  1. 读取现有卡牌模板结构
  2. 选择生成方式（随机/主题化/手动/扩展现有）
  3. 生成符合主题的卡牌内容

setup-deck-display - 配置卡牌显示

引导用户配置卡牌的显示参数（尺寸、布局、样式等）。

参数：

参数 类型 必需 说明
csv_file string ✗ CSV 文件路径
usage string ✗ 卡牌用途（如：桌面游戏、印刷、在线预览等）

使用示例：

{
  "name": "setup-deck-display",
  "arguments": {
    "csv_file": "./content/magic-items.csv",
    "usage": "桌面游戏"
  }
}

返回内容：

Prompt 会引导 AI 助手配置：

  1. 卡牌尺寸（桥牌尺寸、标准尺寸、塔罗尺寸等）
  2. 网格布局（每张 A4 纸的排列）
  3. 出血边距、内边距
  4. 卡牌形状
  5. 图层配置（自动排版文字）

工作流示例

创建新卡牌组

  1. 设计模板：调用 design-card-game Prompt 引导设计字段结构
  2. 定义模板：调用 deck_frontmatter_write 创建 CSV 和 frontmatter
  3. 创建预览：调用 deck_preview 创建 Markdown 预览文件
  4. 填充内容：调用 populate-deck Prompt 引导生成卡牌内容
  5. 添加卡牌：调用 deck_card_crud（action=create）添加卡牌
  6. 配置显示：调用 setup-deck-display Prompt 配置显示参数
  7. 保存配置：调用 deck_frontmatter_write 更新 deck 配置

修改现有卡牌组

  1. 读取模板：调用 deck_frontmatter_read 获取当前配置
  2. 读取卡牌：调用 deck_card_crud（action=read）获取卡牌数据
  3. 修改卡牌：调用 deck_card_crud（action=update）更新卡牌
  4. 更新预览：调用 deck_preview 更新 Markdown 文件

快捷生成

直接调用 generate_card_deck 一站式生成完整卡牌组。

与 TTRPG Tools 集成

生成的卡牌组可以直接使用 TTRPG Tools 预览和编译：

# 预览卡牌内容
ttrpg serve ./content

# 编译为静态网站
ttrpg compile ./content -o ./dist

开发说明

添加新的 MCP 工具

  1. 在 src/cli/tools/ 目录创建工具模块
  2. 在 src/cli/commands/mcp.ts 中注册工具
  3. 实现 ListToolsRequestSchema 和 CallToolRequestSchema 处理器

代码结构

src/cli/
├── commands/
│   ├── serve.ts
│   ├── compile.ts
│   └── mcp.ts          # MCP 命令入口
├── tools/
│   ├── frontmatter/
│   │   ├── read-frontmatter.ts
│   │   └── write-frontmatter.ts
│   ├── card/
│   │   └── card-crud.ts
│   ├── ensure-deck-preview.ts
│   └── generate-card-deck.ts
└── index.ts

依赖

MCP 服务器使用 @modelcontextprotocol/sdk 包，已包含在项目依赖中。