MCP 服务器

MCPGTCG

An MCP server for the Genius Invokation TCG simulator that allows AI models to interact with the game through a structured interface. It provides comprehensive tools for querying game states, accessing indexed card data, and executing gameplay actions like elemental tuning and character selection.

README

MCPGTCG - 七圣召唤 MCP 实现

为七圣召唤模拟器提供的 MCP (Model Context Protocol) 实现，使 AI 能够通过 MCP 接口与游戏交互并实现自动打牌功能。

开源发布模型（推荐）

本项目采用分层发布，降低对模拟器深度魔改的维护成本：

core：MCP 协议、工具、序列化、索引能力（本包的 src/）
adapter：最小注入点（将 AI IO / state listener 接到模拟器）
patch：对上游模拟器的显式补丁文件（patches/*.patch）

这样可以在公开 MCP 与 Skills 的同时，把对客户端改动保持为可审计、可回放、可替换。

发布文档

兼容矩阵：COMPATIBILITY.md
补丁指南：PATCHING.md
贡献指南：CONTRIBUTING.md
补丁目录说明：patches/README.md
Skills 发布指南：../../../.opencode/skills/README.md
图片资源策略：docs/ASSET_POLICY.md

项目结构

MCPGTCG/
├── src/
│   ├── mcp/
│   │   ├── MCPProtocol.ts    # MCP 协议常量和消息构建器
│   │   ├── MCPServer.ts       # MCP 服务器实现
│   │   └── MCPToolHandler.ts  # MCP 工具处理器
│   ├── AIClientPlayerIO.ts    # AI 玩家 IO 实现
│   ├── GameStateListener.ts   # 游戏状态监听器
│   ├── GameStateSerializer.ts # 游戏状态序列化器
│   ├── card-index/            # 卡牌索引构建与查询
│   └── index.ts                # 主入口文件
├── examples/
│   └── integration.ts          # 集成示例
├── package.json
├── tsconfig.json
└── tsup.config.ts

核心组件

1. MCPProtocol

定义了 MCP 协议的常量、接口和消息构建函数，支持 JSON-RPC 2.0 通信。

2. MCPServer

MCP 服务器的核心实现，使用标准输入/输出进行通信，处理来自客户端的请求。

3. MCPToolHandler

定义并处理所有可用的 MCP 工具，包括：

状态查询：get_game_state, get_screen_state, get_available_commands
信息查询：get_character_info, get_card_info
游戏操作：choose_action, elemental_tuning, choose_active, reroll_dice, switch_hands, select_card

4. AIClientPlayerIO

实现了 CancellablePlayerIO 接口，用于与游戏进行交互，缓存通知和等待 RPC 请求响应。

5. GameStateListener

监听游戏状态变化，在游戏暂停时捕获当前状态和突变。

6. GameStateSerializer

将游戏状态序列化为可通过 MCP 传输的格式。

7. Card Index

从 @gi-tcg/data 源码注释构建卡牌索引（definitionId/name/description/contentHash），并提供检索、解析、映射校验能力，降低 AI 在 ID 与卡牌效果之间错配的概率。

快速开始

图片资源说明（重要）

仓库默认不包含卡图二进制文件（packages/standalone/public/card_images/）。

目的：精简仓库体积与拉取时间。
方式：用户自行从模拟器项目图床/CDN 下载。
参考：docs/ASSET_POLICY.md
下载脚本：scripts/download-card-images.sh、scripts/download-card-images.ps1

1. 安装依赖

cd MCPGTCG
bun install

2. 构建项目

bun run build

3. 类型检查

bun run check

4. 构建卡牌索引

bun run build:card-index

索引输出到 packages/mcp/.cache/card_index.latest.json。

与七圣召唤集成

建议优先采用“补丁集成”方式（见 PATCHING.md），而不是长期维护完整 Fork。

示例命令：

bash packages/mcp/scripts/apply-standalone-patch.sh packages/mcp/patches/<patch-file>.patch

基本集成示例

import { setupMCPGame, startMCPServerAndGame } from "@gi-tcg/mcp";
import { Version } from "@gi-tcg/core";

// 设置游戏
const { game, cleanup } = await setupMCPGame(
  deck0Code,  // 玩家0的牌组代码
  deck1Code,  // 玩家1的牌组代码
  Version.V6_3_0,  // 游戏版本
  0  // AI 玩家位置
);

// 或者同时启动 MCP 服务器和游戏
await startMCPServerAndGame(
  deck0Code,
  deck1Code,
  Version.V6_3_0,
  0
);