5.0 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 工具：generate_card_deck

通过 MCP 协议，AI 助手可以调用 generate_card_deck 工具生成卡牌组。

工具参数

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

card_template 结构

{
  "fields": [
    {
      "name": "字段名称（英文，用于 CSV 列名）",
      "description": "字段描述",
      "examples": ["示例值 1", "示例值 2"]
    }
  ],
  "examples": [
    {
      "字段名称": "值 1",
      "字段名称 2": "值 2"
    }
  ]
}

deck_config 结构

{
  "size": "54x86",
  "grid": "5x8",
  "bleed": 1,
  "padding": 2,
  "shape": "rectangle",
  "layers": "name:1,2-3,12 desc:1,4-8,10",
  "back_layers": "back:1,2-8,12"
}

使用示例（AI 助手）

用户请求：

帮我生成一个魔法物品卡牌组，包含 15 张卡牌，字段有名称、稀有度、效果描述

AI 助手调用工具：

{
  "deck_name": "魔法物品",
  "output_dir": "./content",
  "card_count": 15,
  "card_template": {
    "fields": [
      {
        "name": "name",
        "description": "物品名称",
        "examples": ["火球术卷轴", "治疗药水", "隐形斗篷"]
      },
      {
        "name": "rarity",
        "description": "稀有度",
        "examples": ["稀有", "普通", "珍贵"]
      },
      {
        "name": "effect",
        "description": "效果描述",
        "examples": ["造成 5d6 火焰伤害", "恢复 2d4+2 生命值", "隐身 1 小时"]
      }
    ]
  }
}

工具返回：

生成的 Markdown 文件路径
生成的 CSV 文件路径
:md-deck 组件代码

输出文件

运行工具后会生成：

Markdown 文件 ({deck_name}.md)
- 包含卡牌组标题和描述
- 嵌入 :md-deck 组件代码
- 使用说明
CSV 文件 ({deck_name}.csv)
- 包含所有卡牌数据
- 支持 {{字段名}} 变量语法
- 可使用 front matter 添加共享属性
组件代码
- 可直接插入任何 Markdown 文件
- 格式：:md-deck[./xxx.csv]{size="54x86" grid="5x8" ...}

与 TTRPG Tools 集成

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

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

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

开发说明

添加新的 MCP 工具

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

代码结构

src/cli/
├── commands/
│   ├── serve.ts
│   ├── compile.ts
│   └── mcp.ts          # MCP 命令入口
├── tools/
│   └── generate-card-deck.ts  # 卡牌生成工具
└── index.ts

依赖

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

5.0 KiB Raw Blame History Unescape Escape