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 工具：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 结构

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

### deck_config 结构

```json
{
  "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 助手调用工具：**
```json
{
  "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` 组件代码

## 输出文件

运行工具后会生成：

1. **Markdown 文件** (`{deck_name}.md`)
   - 包含卡牌组标题和描述
   - 嵌入 `:md-deck` 组件代码
   - 使用说明

2. **CSV 文件** (`{deck_name}.csv`)
   - 包含所有卡牌数据
   - 支持 `{{字段名}}` 变量语法
   - 可使用 front matter 添加共享属性

3. **组件代码**
   - 可直接插入任何 Markdown 文件
   - 格式：`:md-deck[./xxx.csv]{size="54x86" grid="5x8" ...}`

## 与 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/
│   └── generate-card-deck.ts  # 卡牌生成工具
└── index.ts
```

### 依赖

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