223 lines
5.0 KiB
Markdown
223 lines
5.0 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 工具：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` 包，已包含在项目依赖中。
|