AI导哈

宝可梦战斗模拟MCP服务器

一个提供宝可梦数据和战斗模拟能力的MCP服务器，适用于AI模型训练和游戏开发。

  • by d-sutariya
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 d-sutariya/PokeMCP

使用说明

宝可梦对战模拟MCP服务器

一个模型上下文协议（MCP）服务器，为AI模型提供访问宝可梦数据和战斗模拟功能。该项目展示了按照官方MCP设计模式全面实现MCP资源和工具的过程。

任务实施

根据MCP任务分配要求，该项目实现了两个主要组件：

第一部分：宝可梦数据资源 ✅

需求设计并实现一个MCP资源，该资源能够连接到公共的宝可梦数据集，并提供全面的信息。

实施： 我已使用Pokeapi.co的端点来获取资源（https://pokeapi.co/docs/v2#info）

@mcp.resource("pokemon://data/{pokemon_name}")
@log_resource_request
async def get_pokemon_data(pokemon_name: str) -> str:
    """Resource exposing Pokémon data to LLMs"""
    return await pokemon_resource.get_pokemon_data(pokemon_name)

数据泄露：

  • ✅ 基础属性 （生命值，攻击，防御，特攻，特防，速度）
  • ✅ 表示“正确”或“对”的意思。 类型 （火、水、草等）
  • ✅ 能力 （包括隐藏能力）
  • ✅ 可用动作 以及它们的影响
  • ✅ 进化信息 （物种数据）

第二部分：战斗模拟工具 ✅

需求设计并实现一个具备核心机制的宝可梦对战模拟MCP（可能是指“Model, Control, and Process”或类似概念，但在此上下文中具体含义可能根据项目而定，可灵活翻译为“模拟工具”或保持原样以体现特定技术语境）工具。

实施：

@mcp.tool()
@log_tool_request
async def simulate_battle(pokemon1_name: str, pokemon2_name: str) -> str:
    """Simulate a battle between two Pokémon"""
    result = await battle_sim.run_battle(pokemon1_name, pokemon2_name)
    return result

战斗机制已实现：

  • ✅ 类型有效性计算 附带全面的类型图表
  • ✅ 损伤计算 基于统计数据、招式威力、相同属性加成（STAB）以及属性相克效果
  • ✅ 回合顺序的确定 基于速度统计并进行平局处理
  • ✅ 状态效果麻痹、灼烧、中毒，具有适当的持续时间和效果
  • ✅ 详细的战斗日志 展示每个动作及其结果
  • ✅ 胜者决定（或称为“确定获胜者”） 基于HP（生命值/健康点）降至零

安装

设置视频指南（建议观看）

https://drive.google.com/file/d/13yiCGxU6ycq-W-NDUrTqIjQvIJgBa6IZ/view?usp=sharing 的中文翻译可以是：“谷歌云端硬盘中的文件链接（文件ID：13yiCGxU6ycq-W-NDUrTqIjQvIJgBa6IZ，通过分享方式访问）”。不过，通常我们不会直接翻译这样的URL链接，而是说明其用途或内容，比如：“这是一个指向谷歌云端硬盘中某个文件的链接，可以通过分享方式访问。” 如果需要具体说明该文件的内容，可以根据实际情况来翻译或描述

快速设置（推荐）

我们为所有平台提供自动化设置脚本。只需从项目根目录运行相应的脚本即可：

一键启动器（最简单）

Windows：

# Double-click or run in Command Prompt
setup-windows.bat

Linux/苹果电脑：

# Make executable and run
chmod +x setup-unix.sh
./setup-unix.sh

启动器将提示您选择 MCP Inspector 或 Claude Desktop 安装设置。

直接方法脚本

如果你知道想要使用哪种方法：

方法1：使用MCP Inspector（用于测试和开发）

Windows： setup-windows-mcpinspector.bat Linux/Mac： ./setup-unix-mcpinspector.sh

方法2：使用Claude桌面版（用于生产环境）

Windows： setup-windows-claude.bat Linux/Mac： ./setup-unix-claude.sh

脚本的作用

自动化脚本将：

  1. 检查并安装 uv 如果未安装，则安装包管理器
  2. 设置Python环境 并安装所有依赖项
  3. 配置MCP服务器 对于您选择的方法
  4. 启动服务器 具有适当的设置
  5. 提供明确的指示 对于下一步行动

手动安装（高级用户）

如果您更喜欢手动设置：

先决条件

  • Python 3.12 或更高版本
  • uv 包管理器

手动设置步骤

  1. 安装 uv （如果尚未安装）：
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Linux/Mac
curl -LsSf https://astral.sh/uv/install.sh | sh
  1. 初始化并设置项目:
# Install dependencies
uv sync
  1. 选择你的方法:

对于MCP检查员：

uv run mcp dev main.py

对于Claude Desktop：

# Install for Claude Desktop
uv run mcp install main.py

# Run the server
uv run main.py

# Download Claude Desktop: https://claude.ai/download
# Restart your machine
# Open Claude Desktop and test with: "Simulate battle between Pikachu and Charizard"

监控与调试

服务器日志所有服务器活动都被记录到 logs/server.log 包括：

  • API请求和响应
  • 战斗模拟详情
  • 错误信息和调试信息
  • 资源访问模式
# View real-time logs
tail -f logs/server.log

# Search for specific Pokémon battles
grep "simulate_battle" logs/server.log

# Check for errors
grep "ERROR" logs/server.log

示例查询

资源查询:

  • “给我显示关于皮卡丘的信息”
  • “喷火龙的属性和能力是什么？”
  • “告诉我关于妙蛙种子（Mewtwo）的招式和进化”

工具查询：

  • “模拟皮卡丘和喷火龙之间的战斗”
  • “谁会赢：超梦对战梦幻？”
  • “用巨钳蟹和草苗龟进行一场战斗模拟”

故障排除

常见问题

1. 脚本权限错误（Linux/Mac）

# If you get permission denied errors
chmod +x *.sh

2. UV安装问题

# Windows: Run PowerShell as Administrator
# Linux/Mac: Ensure curl is installed
sudo apt-get install curl  # Ubuntu/Debian

3. Claude Desktop 无法检测到服务器

  • 确保在运行Claude安装脚本后重启了您的计算机
  • 检查MCP服务器是否在后台运行
  • 验证Claude Desktop是否为最新版本

4. 端口已被占用

  • 停止任何现有的MCP服务器
  • 检查是否有其他应用程序正在使用相同的端口

已创建脚本文件

运行安装程序后，您的项目根目录中将包含以下文件：

  • setup-windows.bat - Windows 启动器
  • setup-unix.sh - Linux/Mac 启动器
  • setup-windows-mcpinspector.bat - Windows MCP Inspector 安装设置
  • setup-windows-claude.bat - Windows Claude 桌面版安装
  • setup-unix-mcpinspector.sh - Unix MCP 检查器设置
  • setup-unix-claude.sh - Unix Claude 桌面设置

遵循的MCP设计模式

此实现遵循官方MCP设计模式和最佳实践：

1. 资源模式

# Follows MCP resource URI scheme
@mcp.resource("pokemon://data/{pokemon_name}")
async def get_pokemon_data(pokemon_name: str) -> str:
    """Exposes Pokémon data following resource design pattern"""

2. 工具模式

# Follows MCP tool specification
@mcp.tool()
async def simulate_battle(pokemon1_name: str, pokemon2_name: str) -> str:
    """Tool interface with clear input/output specification"""

3. 日志记录和错误处理

@simple_log  # Consistent logging across all methods
async def fetch_pokemon(self, name: str) -> Dict[str, Any] | None:
    try:
        # Proper error handling and logging
        response = await client.get(url)
        if response.status_code == 200:
            log_debug(f"Successfully fetched data for {name}")
            return response.json()
        else:
            log_error(f"API request failed with status {response.status_code}")
            return None
    except Exception as e:
        log_error(f"Exception during API call: {str(e)}")
        return None

项目架构

PokMCP/
├── main.py                    # Main MCP server using FastMCP
├── models/
│   └── pokemon.py            # Pokémon data models (Pokemon, Move, Ability, etc.)
├── data/
│   └── pokemon_data.py       # API integration and data management
├── tools/
│   ├── battle_simulator.py   # Battle mechanics and simulation engine
│   └── pokemon_info.py       # Detailed Pokémon information tool
├── resources/
│   └── pokemon_resource.py   # MCP resource implementation
├── config/
│   ├── battle_config.py      # Battle mechanics configuration
│   └── game_config.py        # Game difficulty and settings
└── utils/
    └── logger.py             # Logging utilities

高级战斗机制

类型有效性系统

# Comprehensive type effectiveness chart
TYPE_EFFECTIVENESS = {
    "fire": {"water": 0.5, "grass": 2.0, "fire": 0.5, "electric": 1.0, "ice": 2.0},
    "water": {"fire": 2.0, "grass": 0.5, "water": 0.5, "electric": 1.0},
    # ... complete type chart with all 18 types
}

基于动作的战斗系统

# Uses actual Pokémon moves from API
async def select_pokemon_move(self, pokemon: Pokemon) -> Optional[MoveDetails]:
    """Select actual move with power, accuracy, and effects"""
    move_details = await self.get_move_details(selected_move.name)
    return move_details  # Contains power, accuracy, type, effects

# Realistic damage calculation
def calculate_damage_with_move(self, attacker, defender, move_details):
    base_damage = move_details.power or random.randint(20, 50)
    effectiveness = self.get_type_effectiveness(move_details.type_name, defender.types)
    stab = 1.5 if move_details.type_name in attacker.types else 1.0
    return int(base_damage * effectiveness * stab * random_variance)

API集成

使用的PokeAPI端点：

  • GET /pokemon/{name} - 神奇宝贝数据（属性、类型、特性、招式）
  • GET /move/{name} - 动作详情（威力、准确度、效果）
  • GET /move-ailment/{name} - 状态效果信息

数据处理：

# Comprehensive Pokémon model with all required data
@dataclass
class Pokemon:
    # Basic info and stats
    id: int
    name: str
    base_stats: Dict[str, int]
    
    # Battle mechanics
    hp: int
    max_hp: int
    types: List[PokemonType]
    abilities: List[Ability]
    moves: List[Move]
    
    # Status and battle state
    status: str = "normal"
    status_turns: int = 0

已完成的可交付成果 ✅

第一部分：MCP资源

  • ✅（勾选标记，表示正确、确认或已完成） 代码包含宝可梦数据资源的完整MCP服务器
  • ✅ 文档该资源通过（某种方式）公开了全面的宝可梦数据 pokemon://data/{name} 统一资源标识符（URIs）
  • ✅ 示例像“显示皮卡丘的属性”这样的大型语言模型（LLM）查询能够无缝访问资源

第二部分：战斗模拟工具

  • ✅ 代码遵循MCP工具规范的全面战斗模拟
  • ✅ 力学类型有效性、伤害计算、回合顺序、3+种状态效果
  • ✅ 集成通过MCP工具接口暴露，附带详细战斗日志

许可证

麻省理工学院许可证（MIT License）

相关 MCP