hearthstone-decks-mcp

一个基于Model Context Protocol (MCP)的炉石传说卡组解析服务器，可以解析卡组代码并返回详细的卡牌信息和封面图。

功能特性

• 🎯 卡组代码解析: 解析炉石传说卡组代码，返回详细的卡组信息
• 🔍 卡牌搜索: 根据卡牌名称搜索炉石传说卡牌
• 📋 卡牌详情: 根据卡牌ID获取详细的卡牌信息
• 🖼️ 封面图支持: 自动获取卡牌封面图URL
• 📊 统计信息: 提供卡组统计（法力值分布、稀有度统计等）
• 🔌 多传输方式: 支持标准输入输出、HTTP SSE、流式传输

安装

全局安装（推荐）

npm install -g hearthstone-decks-mcp

本地安装

npm install hearthstone-decks-mcp

快速开始

作为MCP服务器使用

在Cursor或其他支持MCP的客户端中配置：

{
  "mcpServers": {
    "hearthstone-decks": {
      "command": "npx",
      "args": ["hearthstone-decks-mcp"]
    }
  }
}

独立运行

标准输入输出模式（stdio）

npx hearthstone-decks-mcp
# 或者
hearthstone-decks-mcp

HTTP SSE模式

npx hearthstone-decks-mcp --transport=http
# 或者
hearthstone-decks-mcp --transport=http

命令行选项

• --transport=stdio - 使用标准输入输出模式（默认）
• --transport=http - 使用HTTP SSE模式

环境变量

# HTTP服务器配置
HTTP_PORT=3000          # HTTP服务器端口（默认3000）
HTTP_HOST=localhost     # HTTP服务器主机（默认localhost）

# 卡牌数据缓存配置
CARD_DATA_TTL=24        # 卡牌数据缓存时间（小时，默认24）

API接口

工具列表

1. parse_deck_code - 解析卡组代码

   • 参数：
     • deckCode (string, 必需): 炉石传说卡组代码
     • includeStats (boolean, 可选): 是否包含统计信息，默认为true

2. search_cards - 搜索卡牌

   • 参数：
     • cardName (string, 必需): 要搜索的卡牌名称
     • limit (integer, 可选): 返回结果数量限制，默认为10

3. get_card_info - 获取卡牌详情

   • 参数：
     • cardId (string, 必需): 炉石传说卡牌ID

HTTP API端点

当使用HTTP模式时，服务器提供以下端点：

• GET / - 测试页面
• GET /sse - Server-Sent Events端点
• GET /tools - 获取可用工具列表
• POST /tools/{toolName} - 调用指定工具
• GET /health - 健康检查

使用示例

1. 解析卡组代码

curl -X POST http://localhost:3000/tools/parse_deck_code \
  -H "Content-Type: application/json" \
  -d '{
    "deckCode": "AAECAZ8FBugE7QXUBfcF4gXtBQwBAfcC5wP5A/4D5wWJBpkH4wfXCOsE7QX3BQAA",
    "includeStats": true
  }'

2. 搜索卡牌

curl -X POST http://localhost:3000/tools/search_cards \
  -H "Content-Type: application/json" \
  -d '{
    "cardName": "火球术",
    "limit": 5
  }'

3. 获取卡牌详情

curl -X POST http://localhost:3000/tools/get_card_info \
  -H "Content-Type: application/json" \
  -d '{
    "cardId": "CS2_029"
  }'

返回数据格式

卡组解析结果

{
  "success": true,
  "data": {
    "meta": {
      "version": 1,
      "format": "Standard",
      "totalCards": 30,
      "deckCode": "AAECAZ8F..."
    },
    "heroes": [
      {
        "id": "HERO_04",
        "name": "乌瑟尔",
        "cardClass": "PALADIN",
        "imageUrl": "https://art.hearthstonejson.com/v1/render/latest/zhCN/512x/HERO_04.png"
      }
    ],
    "cards": [
      {
        "id": "CS2_088",
        "name": "守护者祝福",
        "cost": 1,
        "type": "SPELL",
        "cardClass": "PALADIN",
        "rarity": "COMMON",
        "count": 2,
        "imageUrl": "https://art.hearthstonejson.com/v1/render/latest/zhCN/512x/CS2_088.png"
      }
    ],
    "statistics": {
      "totalCards": 30,
      "totalUnique": 15,
      "manaCurve": [2, 4, 6, 8, 4, 3, 2, 1, 0, 0, 0],
      "rarities": {
        "COMMON": 14,
        "RARE": 8,
        "EPIC": 4,
        "LEGENDARY": 4
      },
      "cardTypes": {
        "MINION": 20,
        "SPELL": 8,
        "WEAPON": 2
      },
      "classes": {
        "PALADIN": 15,
        "NEUTRAL": 15
      }
    }
  }
}

数据源

• 卡牌数据: HearthstoneJSON API
• 卡牌封面图: HearthstoneJSON Render API

卡牌ID说明

炉石传说的卡牌有两种ID格式：

1. 字符串ID (如 CS2_029): 这是卡牌的唯一字符串标识符
2. DBF ID (如 315): 这是卡牌的数字标识符，用于卡组代码中

卡组代码解析时会获得DBF ID，然后通过映射关系找到对应的字符串ID和卡牌详细信息。

开发

从源码运行

git clone https://github.com/yinshawnrao/hearthstone-decks-mcp.git
cd hearthstone-decks-mcp
npm install
npm start

开发模式

npm run dev  # 使用nodemon自动重启

测试

npm test

技术栈

• Node.js - 运行时环境
• @modelcontextprotocol/sdk - MCP协议支持
• Express.js - HTTP服务器
• node-fetch - HTTP客户端
• Server-Sent Events - 实时通信

许可证

MIT License

贡献

欢迎提交Issue和Pull Request！

提交Issue

• 报告Bug
• 请求新功能
• 改进建议

提交Pull Request

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开Pull Request

更新日志

v1.0.0

• 初始版本发布
• 支持卡组代码解析
• 支持卡牌搜索
• 支持卡牌详情查询
• 支持HTTP和stdio传输模式
• 提供美观的测试界面

注意事项

1. 首次运行时会从HearthstoneJSON API下载卡牌数据，可能需要一些时间
2. 卡牌数据会缓存24小时（可配置）
3. 部分卡组代码可能需要最新的解析算法支持
4. 建议在生产环境中配置适当的缓存和错误处理

常见问题

Q: 卡组代码解析失败怎么办？

A: 请确保卡组代码是有效的炉石传说卡组代码，格式类似于 AAECAZ8F...

Q: 搜索不到某些卡牌？

A: 请检查卡牌名称是否正确，支持中文和英文名称搜索

Q: 图片无法显示？

A: 图片URL来自HearthstoneJSON，请检查网络连接和API可用性