什么是 Scryfall MTG 卡牌查询？

Scryfall MTG 卡牌查询技能为 AI 智能体提供了一个强大的接口，用于与《万智牌》行业标准数据库 Scryfall API 进行交互。通过此集成，用户可以查询海量的卡牌数据，包括官方规则文本（oracle text）、法术力消耗、合法性以及实时市场价格。该技能专为使用 Openclaw Skills 的开发者和爱好者设计，简化了将 MTG 情报引入自动化工作流的过程。

利用此技能，智能体可以处理复杂的卡牌查找，从简单的名称搜索到基于游戏机制、艺术家或稀有度的复杂过滤查询。它会自动处理速率限制和自定义请求头等技术要求，确保在构建以卡牌为核心的应用时获得无缝体验。

下载入口:https://github.com/openclaw/skills/tree/main/skills/santidev95/scryfall-cards

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

Scryfall MTG 卡牌查询 应用场景

• 构建 AI 驱动的组牌助手，根据特定的法术力消耗或力量/防御力比例推荐卡牌。
• 创建自动价格追踪器，监控特定卡牌以美元（USD）或欧元（EUR）计价的市场价值。
• 开发赛制合法性检查工具，确保牌表符合标准、摩登或指挥官赛制的规则。
• 将卡牌原画和官方规则文本引用集成到社区聊天机器人或研究工具中。

1. 当检测到与《万智牌》相关的查询（如对卡牌名称或特定属性的请求）时，AI 智能体会触发该技能。
2. 技能使用 Scryfall 搜索语法构建针对性的 API 请求，支持精确匹配或模糊名称查找。
3. 请求被发送至 Scryfall API，带有专门的 User-Agent，并内置 50-100ms 的延迟以遵守速率限制策略。
4. 解析返回的 JSON 负载，提取高优先级字段，如规则文本、图像链接和价格数据。
5. 对于复杂卡牌（如双面牌或分拆牌），技能会遍历 card_faces 数组以提供完整信息。

Scryfall MTG 卡牌查询 配置指南

要在 Openclaw Skills 中开始使用此技能，请确保您的环境已配置为执行 Python 脚本。基础访问无需 API 密钥。

# 按名称搜索卡牌
python3 scripts/scryfall_search.py search "lightning bolt"

# 使用模糊匹配查找卡牌
python3 scripts/scryfall_search.py named --fuzzy "jac bele"

# 使用特定过滤器获取随机卡牌
python3 scripts/scryfall_search.py random --query "t:dragon"

请确保您的实现包含强制性请求头：User-Agent: OpenClawMTGSkill/1.0 和 Accept: application/json。

Scryfall MTG 卡牌查询 数据架构与分类体系

该技能将卡牌数据整理为结构化格式，以便于提取。以下是 Openclaw Skills 集成优先处理的主要字段：

name: scryfall-mtg
description: "Search and retrieve Magic: The Gathering card data using the Scryfall API. Use this skill when the user asks about MTG cards, wants to search for cards by name, type, color, mana cost, oracle text, set, or any other card attribute. Also use for getting card images, prices, rulings, legality information, or random cards. Triggers include mentions of MTG, Magic, Magic: The Gathering, card names, deck building questions, or requests for card information."

Scryfall MTG Card Search

Search for Magic: The Gathering cards using the Scryfall API.

API Overview

Base URL: https://api.scryfall.com

Required Headers:

headers = {
    "User-Agent": "OpenClawMTGSkill/1.0",
    "Accept": "application/json"
}

Rate Limiting: Insert 50-100ms delay between requests (max 10 req/sec).

Core Endpoints

Search Cards

GET /cards/search?q={query}

Parameters:

• q (required): Fulltext search query
• unique: cards|art|prints (default: cards)
• order: name|set|released|rarity|color|usd|tix|eur|cmc|power|toughness|edhrec|penny|artist|review
• dir: auto|asc|desc
• page: Page number for pagination

Named Card Lookup

GET /cards/named?exact={name}
GET /cards/named?fuzzy={name}

Use fuzzy for partial matches (e.g., "jac bele" → "Jace Beleren"). Add &set={code} to limit to specific set.

Random Card

GET /cards/random
GET /cards/random?q={query}

Card by ID

GET /cards/{id}
GET /cards/{set_code}/{collector_number}

Autocomplete

GET /cards/autocomplete?q={partial_name}

Returns up to 20 card name suggestions.

Search Syntax Reference

See references/search_syntax.md for the complete search syntax guide.

Quick examples:

• c:red pow=3 - Red cards with power 3
• t:merfolk t:legend - Legendary merfolk
• o:"draw a card" - Cards with "draw a card" in text
• cmc=3 r:rare - 3-mana rares
• e:dom - Cards from Dominaria
• f:standard - Standard legal cards
• usd<1 - Cards under $1

Implementation

Use the provided script for common operations:

python3 scripts/scryfall_search.py search "lightning bolt"
python3 scripts/scryfall_search.py named --exact "Black Lotus"
python3 scripts/scryfall_search.py random
python3 scripts/scryfall_search.py random --query "t:dragon"

Or make direct API calls with proper headers and rate limiting.

Card Object Key Fields

When displaying card info, prioritize these fields:

• name, mana_cost, type_line
• oracle_text, power, toughness
• image_uris.normal (for card image)
• prices.usd, prices.usd_foil
• legalities (format legality)
• set_name, rarity

For double-faced cards, check card_faces array.

Error Handling

• 404: Card not found
• 422: Invalid search query
• 429: Rate limited (wait and retry)

Always validate responses have object field; if object: "error", check details for message.