fix: mcp

2026-03-18 12:08:28 +08:00
parent eecf429a20
commit 62aff91a86
8 changed files with 1241 additions and 118 deletions
@@ -1,6 +1,6 @@
 # MCP 服务器使用说明

-TTRPG Tools 提供了一个 MCP (Model Context Protocol) 服务器，用于与 AI 助手集成，自动化生成卡牌内容。
+TTRPG Tools 提供了一个 MCP (Model Context Protocol) 服务器，用于与 AI 助手集成，自动化生成和管理卡牌内容。

 ## 命令结构

@@ -79,11 +79,15 @@ ttrpg mcp generate-card-deck \
  --grid "3x4"
 ```

-## MCP 工具：generate_card_deck
+## MCP 工具

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

-### 工具参数
+### 快捷工具
+
+#### `generate_card_deck` - 一站式生成卡牌组
+
+快速生成完整的卡牌组，包括 Markdown 文件、CSV 数据文件和组件配置。

 | 参数 | 类型 | 必需 | 说明 |
 |------|------|------|------|
@@ -94,8 +98,41 @@ ttrpg mcp generate-card-deck \
 | `deck_config` | object | ✗ | md-deck 组件配置 |
 | `description` | string | ✗ | 卡牌组描述 |

-### card_template 结构
+### 核心工具

+#### `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": [
@@ -105,84 +142,171 @@ ttrpg mcp generate-card-deck \
      "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 小时"]
-      }
-    ]
+  "deck": {
+    "size": "54x86",
+    "grid": "5x8",
+    "bleed": 1,
+    "padding": 2,
+    "shape": "rectangle",
+    "layers": "name:1,2-3,12",
+    "back_layers": "back:1,2-8,12"
  }
 }
 ```

-**工具返回：**
- 生成的 Markdown 文件路径
- 生成的 CSV 文件路径
- `:md-deck` 组件代码
+#### `deck_card_crud` - 卡牌 CRUD 操作

-## 输出文件
+卡牌的创建、读取、更新、删除操作，支持批量操作。

-运行工具后会生成：
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `csv_file` | string | ✓ | CSV 文件路径 |
+| `action` | string | ✓ | 操作类型：`create` \| `read` \| `update` \| `delete` |
+| `cards` | object\|array | ✗ | 卡牌数据（单张或数组） |
+| `label` | string\|array | ✗ | 要操作的卡牌 label（用于 read/update/delete） |

-1. **Markdown 文件** (`{deck_name}.md`)
-   - 包含卡牌组标题和描述
-   - 嵌入 `:md-deck` 组件代码
-   - 使用说明
+**卡牌数据结构：**
+```json
+{
+  "label": "1",
+  "name": "火球术卷轴",
+  "type": "法术",
+  "cost": "3",
+  "description": "造成 5d6 火焰伤害"
+}
+```

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

-3. **组件代码**
-   - 可直接插入任何 Markdown 文件
-   - 格式：`:md-deck[./xxx.csv]{size="54x86" grid="5x8" ...}`
+```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 集成

@@ -213,7 +337,13 @@ src/cli/
 │   ├── compile.ts
 │   └── mcp.ts          # MCP 命令入口
 ├── tools/
-│   └── generate-card-deck.ts  # 卡牌生成工具
+│   ├── frontmatter/
+│   │   ├── read-frontmatter.ts
+│   │   └── write-frontmatter.ts
+│   ├── card/
+│   │   └── card-crud.ts
+│   ├── ensure-deck-preview.ts
+│   └── generate-card-deck.ts
 └── index.ts
 ```