ttrpg-tools/docs/mcp.md

# 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_ensure_preview` - 确保 Markdown 预览文件存在

确保 CSV 对应的 Markdown 预览文件存在，如果不存在则创建。

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

## 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 内容（可选，支持 `{{字段名}}` 语法）

## 工作流示例

### 创建新卡牌组

1. **定义模板**：调用 `deck_frontmatter_write` 创建 CSV 和 frontmatter
2. **创建预览**：调用 `deck_ensure_preview` 创建 Markdown 预览文件
3. **添加卡牌**：调用 `deck_card_crud`（action=create）添加卡牌

### 修改现有卡牌组

1. **读取模板**：调用 `deck_frontmatter_read` 获取当前配置
2. **读取卡牌**：调用 `deck_card_crud`（action=read）获取卡牌数据
3. **修改卡牌**：调用 `deck_card_crud`（action=update）更新卡牌
4. **更新预览**：调用 `deck_ensure_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` 包，已包含在项目依赖中。