How do I use hearthstone-decks-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@hearthstone-decks-mcp decode this deck code: AAECAZ8FBugE7QXUBfcF4gXtBQwBAfcC5wP5A/4D5wWJBpkH4wfXCOsE7QX3BQAA" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

hearthstone-decks-mcp

npm version License: MIT Node.js Version

一个基于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接口

工具列表

parse_deck_code - 解析卡组代码
- 参数：
  - deckCode (string, 必需): 炉石传说卡组代码
  - includeStats (boolean, 可选): 是否包含统计信息，默认为true
search_cards - 搜索卡牌
- 参数：
  - cardName (string, 必需): 要搜索的卡牌名称
  - limit (integer, 可选): 返回结果数量限制，默认为10
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格式：

字符串ID (如 CS2_029): 这是卡牌的唯一字符串标识符
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

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

更新日志

v1.0.0

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

注意事项

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

常见问题

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

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

Q: 搜索不到某些卡牌？

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

Q: 图片无法显示？

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