拳头游戏API MCP工具 - 增强版
一款全面的MCP（模型上下文协议）工具，通过Riot Games API访问《英雄联盟》、《团队战斗战术》、《符文之地传说》和《无畏契约》的实时玩家数据。
🎯 概述
这个增强版显著扩展了原始riot-games-api工具的功能，具体包括：
- 30多个新工具功能 按游戏/数据类型组织
- 更好的数据结构 按地区、平台和游戏进行清晰分类组织
- 向后兼容性 - 所有原始工具继续正常工作，无任何变化
- 《英雄联盟》全面支持 包括挑战赛、观众席、阶梯式参赛资格
- 团队战斗战术整合 带有比赛历史和排名信息
- 改进了错误处理 以及响应一致性
- 类型安全的实现 使用适当的字面量类型和类型提示
📋 架构
常量与类型定义
平台路由 （针对特定平台的终端节点）：
na→na1（北美洲）euw→euw1（欧洲西部）kr→kr（韩国）br→br1（巴西）las→la1（拉丁美洲南部）lan→la2（拉丁美洲北部）ru→ru（俄罗斯）tr→tr1火鸡jp→jp1(日本)oc→oc1（大洋洲）pbe→pbe1(PBE) 可以翻译为“（预生产环境）”或根据具体语境简化为“（预生产）”，其中PBE是Production Build Environment的缩写，指的是软件开发中的一个阶段，用于在正式生产环境之前进行测试和验证
区域路由 （针对如比赛、账户等区域性终端）：
americas- 北美洲、巴西、拉丁美洲europe- 欧洲，土耳其，俄罗斯asia-pacific- 韩国、日本、大洋洲sea- 东南亚
辅助函数
API请求函数：
riot_request()- 平台路由请求（召唤师、联赛、观战）riot_regional_request()- 按区域路由的请求（比赛、账户）
账户功能：
get_puuid()- 根据游戏名和标签获取PUUIDget_riot_account()- 获取完整的Riot账户信息
《英雄联盟》辅助人员：
get_summoner_by_puuid()- 通过PUUID获取召唤师资料get_rank_by_puuid()- 通过PUUID获取排名段位/积分get_top_champions()- 成为顶级精通冠军get_champion_map()- 获取冠军ID到名称的映射
团队战斗战术辅助工具
get_tft_summoner()- 获取TFT（英雄联盟云顶之弈）特定的召唤师数据
🛠️ 工具功能
《英雄联盟》工具
lol_get_player_summary(game_name, tag_line, platform="na", language="en_US")
获取完整的玩家资料概览，包括：
- 召唤师等级
- 单人队列排名（段位、等级、联赛点、胜负场数、胜率）
- 灵活排名（相同指标）
- 掌握数据排名前五的冠军
- 最近5场比赛的KDA（击杀/死亡/助攻比）、位置及结果
示例：
{
"gameName": "Air Coots",
"tagLine": "Prime",
"level": 113,
"soloRank": {
"tier": "PLATINUM",
"rank": "IV",
"lp": 0,
"wins": 14,
"losses": 16,
"winRate": 47
},
"topChampions": [
{
"champion": "Amumu",
"level": 39,
"points": 485781
}
],
"recentMatches": [...]
}lol_get_top_champions(game_name, tag_line, platform="na", language="en_US", count=5)
获取玩家使用熟练度点数排名最多的英雄列表。
最高可返现至 count 与……一同夺冠的冠军们：
- 冠军名称
- 掌握程度（1-7）
- 总掌握分数
lol_get_recent_matches(game_name, tag_line, platform="na", count=10)
获取最新比赛历史及详细统计数据：
- 比赛ID
- 冠军选手参赛
- 击杀/死亡/助攻数据
- 位置和车道
- 胜负结果
- 获得的金币
- CS（小黄人被杀数量）
lol_get_champion_mastery(game_name, tag_line, champion_name, platform="na", language="en_US")
获取特定英雄的详细掌握数据：
- 当前等级（1-7）
- 总分
- 晋级到下一个层次
- 最后游玩时间（ISO 8601 格式）
- 获得的代币
- 下个赛季里程碑要求
lol_get_match_details(match_id, puuid, platform="na")
获取全面的比赛统计数据：
- KDA（击杀/死亡/助攻比）击杀数、死亡数、助攻数、KDA（击杀-死亡-助攻）比
- 损坏对英雄和目标造成的总伤害（已承受）
- CS（可翻译为“计算机科学”或根据具体语境翻译为其他含义，如“化学科学”等，但在此通用翻译为“计算机科学”）小黄人被杀，每分钟经济差
- 金赚取和花费
- 愿景视野得分，放置/击杀守卫数
- 目标炮塔、主宰、龙、先知击杀（或“ Baron 杀”）
- 项目/物品所有项目均已构建完成
- 游戏信息时长、队列类型、游戏模式
lol_get_challenges(game_name, tag_line, platform="na")
获取英雄联盟挑战赛的玩家进度：
- 总挑战积分
- 按类别计分
- 个人挑战进度
lol_get_league_entries(tier, rank=None, platform="na", page=1)
获取特定等级/排名的阶梯排名条目：
- 召唤师名称和ID
- 当前等级/排名/积分（LP，League Points，通常指游戏或竞技中的积分系统）
- 胜负记录
- 胜率
- 分页支持（从第1页开始计数）
第三方： 铁、青铜、白银、黄金、铂金、钻石、大师、宗师、挑战者
注： 大师/特级大师/挑战者没有等级划分
lol_get_spectator(summoner_name, platform="na")
如果玩家当前正在比赛中，请获取实时游戏数据：
- 游戏类型和队列
- 游戏开始时间
- 所有参与者及其冠军
- 团队任务分配
团队战斗战术工具
tft_get_player_summary(game_name, tag_line, platform="na")
获取TFT（英雄联盟云顶之弈）玩家资料概览：
- 召唤师ID和PUUID
- 当前排名/胜场/负场
- 最近5场比赛的成绩及排名
tft_get_recent_matches(game_name, tag_line, platform="na", count=10)
获取包含阵容数据的TFT（战术足球游戏/团队竞技游戏等，具体根据上下文确定）对战历史：
- 比赛ID
- 安置；职位安排
- 剩余等级和金币
- 对玩家的总伤害
- 带有项目的特性（或特征）和单元
向后兼容性工具
这些工具保持了现有工作流的原始界面：
get_player_summary()- 原始LoL摘要（返回格式化字符串）get_top_champions_tool()- 原始顶级冠军（返回格式化字符串）get_recent_matches_tool()- 最近的比赛原始数据（返回格式化字符串）get_champion_mastery_tool()- 原始的冠军掌握度（返回字典）get_match_summary()- 原始比赛详情（返回字典）
全新 lol_ 并且 tft_ 带前缀的工具返回 JSON 字典，以便更好地进行程序访问。
🌍 平台支持
《英雄联盟》平台
- 北美（North America）
- EUW（Europe West）翻译为中文是“欧洲西部（服务器/赛区）”
- KR（韩国）
- BR（巴西）
- LAS（拉丁美洲南部）
- LAN（拉丁美洲北部）
- RU（俄罗斯）
- TR（土耳其）
- JP（日本）
- OC（大洋洲）
- PBE（公共测试环境）
区域测绘
americasNA（北美）、BR（巴西）、LAS（拉丁美洲服务器）、LAN（局域网）europeEUW（美国西区）、RU（俄罗斯）、TR（土耳其）asia-pacific韩国（KR）、日本（JP）、大洋洲（OC）sea东南亚服务器
🔄 错误处理
所有函数都返回一致的错误响应：
{
"error": "Description of what went wrong"
}常见的错误场景：
- 无效的玩家名称/标签 → “未找到玩家”
- 未找到冠军 → “未找到冠军 'XYZ'”
- “无数据可用”→“无法检索\[数据类型\]”
- API问题 → 函数返回None，已优雅捕获并处理
📊 响应格式
新工具返回结构化的JSON，其中包含：
- 标准字段:
gameName，tagLine，puuid（如适用） - 数据对象用于相关数据的嵌套结构
- 数值计算比率、百分比、每分钟统计数据已预先计算
- 时间戳转换为ISO 8601格式以提高可读性
- 一致的命名为保持一致性，使用驼峰命名法
🚀 使用示例
获取玩家的完整《英雄联盟》（League of Legends，简称LoL）资料
lol_get_player_summary("Air Coots", "Prime", platform="na")获取玩家的前10名最喜爱英雄
lol_get_top_champions("Air Coots", "Prime", count=10)获取所有最近的比赛（最多100场）
lol_get_recent_matches("Air Coots", "Prime", count=100)获取具体的比赛统计数据
lol_get_match_details("NA1_5367618281", "BbXxAcwGvo9Uke34fMRJcC4cNr-pjMI-VzhcAYIzcNCC7RTrJUPBlS2czu1JisWZzz3pBtM94Jp8hw")获取玩家的TFT（Teamfight Tactics，即《英雄联盟》中的战术小队游戏模式）段位及近期比赛记录
tft_get_player_summary("Air Coots", "Prime")
tft_get_recent_matches("Air Coots", "Prime", count=20)检查玩家是否在进行中的游戏中
lol_get_spectator("Air Coots")查看排名梯度表
lol_get_league_entries(tier="DIAMOND", rank="I", platform="na", page=1)📦 安装与设置
要求
- Python 3.13或更高版本
- httpx 版本 >= 0.28.1
- MCP（微控制器协议）版本大于等于1.6.0
- python-dotenv
环境设置
创建一个 .env 附上您的Riot API密钥文件：
RIOT_API_KEY=RGAPI-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx从以下网址获取您的API密钥：https://developer.riotgames.com/
运行该工具
python src/server.py🔐 API密钥安全
- API密钥已从（某处）加载
.env文件（包含在.gitignore) - 永远不要承诺
.env进行版本控制 - 定期更换密钥
- 在开发者门户中使用适当的关键限制
📝 数据类型参考
“Tier Enum”翻译成中文是“等级枚举”
IRON, BRONZE, SILVER, GOLD, PLATINUM, DIAMOND, MASTER, GRANDMASTER, CHALLENGER等级枚举
I, II, III, IV（不适用于硕士及以上学历）
语言
en_US, ko_KR, zh_CN, es_MX, fr_FR, it_IT, de_DE, pt_BR, ru_RU, ja_JP, zh_TW, es_ES🎯 性能注意事项
- 缓存冠军地图在首次获取后会被缓存
- 速率限制请遵守Riot的API速率限制（请查阅开发者门户）
- 异步所有函数均支持异步，以实现快速并发请求
- 超时所有API调用的超时时间为30秒
🔍 监控与调试
通过检查 Flask/ASGI 日志来启用调试输出：
RUST_LOG=debug python src/server.py🛣️ 未来改进方向
可能的补充内容：
- 《符文之地传说》端点（排名、比赛、卡组）
- 《Valorant》端点数据（比赛、排位赛、特工数据）
- 现场观众集成（自动更新）
- 比赛时间线数据（逐帧统计）
- 锦标赛数据（可通过API获取时）
- 战利品和库存端点
📚 资源
🤝 贡献
当添加新端点时：
- 遵循现有的代码结构
- 使用一致的命名（例如。，
game_get_function_name) - 包含全面的文档字符串
- 添加适当的错误处理
- 在多个平台/地区进行测试
- 更新此README文件
📄 许可证
请参阅仓库中的LICENSE文件
______________________________________________________________________
最后更新时间： 2025年1月2日 版本： 2.0.0 状态： 生产就绪