feat: mcp server!
This commit is contained in:
hyper
parent
834db72ec4
commit
7b68504b1e
|
|
@ -0,0 +1,222 @@
|
|||
# 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` 包，已包含在项目依赖中。
|
||||
|
|
@ -9,6 +9,7 @@ import { generateCardDeck, type GenerateCardDeckParams, type CardField } from '.
|
|||
|
||||
export interface MCPOptions {
|
||||
port?: string;
|
||||
cwd?: string;
|
||||
}
|
||||
|
||||
export const mcpCommand = new Command('mcp')
|
||||
|
|
@ -18,6 +19,7 @@ export const mcpCommand = new Command('mcp')
|
|||
.description('启动 MCP 服务器')
|
||||
.argument('[host]', '服务器地址', 'stdio')
|
||||
.option('-p, --port <port>', 'HTTP 端口（仅 HTTP 传输）', '3001')
|
||||
.option('--cwd <dir>', '工作目录（工具调用的相对路径基准）', process.cwd())
|
||||
.action(mcpServeAction)
|
||||
)
|
||||
.addCommand(
|
||||
|
|
@ -37,6 +39,11 @@ export const mcpCommand = new Command('mcp')
|
|||
* MCP 服务器启动处理函数
|
||||
*/
|
||||
async function mcpServeAction(host: string, options: MCPOptions) {
|
||||
// 切换到指定的工作目录
|
||||
const cwd = options.cwd || process.cwd();
|
||||
process.chdir(cwd);
|
||||
console.error(`MCP 服务器工作目录：${cwd}`);
|
||||
|
||||
// 动态导入 MCP SDK
|
||||
const { Server } = await import('@modelcontextprotocol/sdk/server/index.js');
|
||||
const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
|
||||
|
|
@ -73,7 +80,7 @@ async function mcpServeAction(host: string, options: MCPOptions) {
|
|||
},
|
||||
output_dir: {
|
||||
type: 'string',
|
||||
description: '输出目录路径',
|
||||
description: '输出目录路径（相对路径相对于 MCP 服务器工作目录）',
|
||||
},
|
||||
card_count: {
|
||||
type: 'number',
|
||||
|
|
@ -191,7 +198,7 @@ async function mcpServeAction(host: string, options: MCPOptions) {
|
|||
};
|
||||
}
|
||||
|
||||
// 生成卡牌组
|
||||
// 生成卡牌组（使用当前工作目录）
|
||||
const result = generateCardDeck(params);
|
||||
|
||||
return {
|
||||
|
|
|
|||
Loading…
Reference in New Issue