546 lines
13 KiB
Markdown
546 lines
13 KiB
Markdown
# MCP 服务器使用说明
|
||
|
||
TTRPG Tools 提供了一个 MCP (Model Context Protocol) 服务器，用于与 AI 助手集成，自动化生成和管理卡牌内容。
|
||
|
||
## 命令结构
|
||
|
||
```bash
|
||
ttrpg mcp [command]
|
||
```
|
||
|
||
### 子命令
|
||
|
||
#### 1. `mcp serve` - 启动 MCP 服务器
|
||
|
||
启动 MCP 服务器，供 AI 助手连接使用。
|
||
|
||
```bash
|
||
# 使用 stdio 传输（默认）
|
||
ttrpg mcp serve
|
||
|
||
# 指定传输方式
|
||
ttrpg mcp serve stdio
|
||
```
|
||
|
||
**MCP 客户端配置示例：**
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"ttrpg-card-generator": {
|
||
"command": "node",
|
||
"args": ["path/to/ttrpg-tools/dist/cli/index.js", "mcp", "serve"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 2. `mcp generate-card-deck` - 快速生成卡牌组
|
||
|
||
通过命令行快速生成卡牌组，无需 MCP 客户端。
|
||
|
||
```bash
|
||
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` |
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
# 生成基础魔法物品卡牌
|
||
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 文件路径 |
|
||
|
||
**返回示例：**
|
||
```json
|
||
{
|
||
"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 结构：**
|
||
```json
|
||
{
|
||
"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） |
|
||
|
||
**卡牌数据结构：**
|
||
```json
|
||
{
|
||
"label": "1",
|
||
"name": "火球术卷轴",
|
||
"type": "法术",
|
||
"cost": "3",
|
||
"description": "造成 5d6 火焰伤害"
|
||
}
|
||
```
|
||
|
||
**使用示例：**
|
||
|
||
```json
|
||
// 创建单张卡牌
|
||
{
|
||
"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 | ✗ | 描述（可选） |
|
||
|
||
**返回示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "预览文件已创建",
|
||
"preview_url": "http://localhost:3000/#/content/cards.md"
|
||
}
|
||
```
|
||
|
||
## CSV 文件格式
|
||
|
||
CSV 文件使用 YAML frontmatter 定义模板和配置：
|
||
|
||
```csv
|
||
---
|
||
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：**
|
||
|
||
```json
|
||
{
|
||
"jsonrpc": "2.0",
|
||
"id": 1,
|
||
"method": "resources/list"
|
||
}
|
||
```
|
||
|
||
**读取 Resource：**
|
||
|
||
```json
|
||
{
|
||
"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 | ✗ | 游戏主题/类型（如：奇幻、科幻、恐怖等） |
|
||
|
||
**使用示例：**
|
||
|
||
```json
|
||
{
|
||
"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 | ✗ | 卡牌主题/描述 |
|
||
|
||
**使用示例：**
|
||
|
||
```json
|
||
{
|
||
"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 | ✗ | 卡牌用途（如：桌面游戏、印刷、在线预览等） |
|
||
|
||
**使用示例：**
|
||
|
||
```json
|
||
{
|
||
"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 预览和编译：
|
||
|
||
```bash
|
||
# 预览卡牌内容
|
||
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` 包，已包含在项目依赖中。
|