search_cards
Read-only
Search Magic: The Gathering cards using advanced query strings with support for pagination, sorting, and deduplication. Retrieve card data efficiently for applications or workflows based on specific criteria like type, color, power, or text.
Instructions
通过查询字符串搜索卡牌，支持分页和排序。
查询语法示例:
t:creature c:r(红色生物)pow>=5 or mv<2(力量大于等于5或法术力值小于2)o:"draw a card" -c:u(包含"抓一张牌"的非蓝色牌)(t:instant or t:sorcery) mv<=3(3费或以下的瞬间或法术)
分页参数:
page: 页码 (整数, 默认 1)page_size: 每页数量 (整数, 默认 20, 最大 100)
排序参数:
order: 按字段排序，逗号分隔。前缀-表示降序 (例如:name,-mv,name,-rarity) 默认排序:name
其他参数:
unique: 去重方式 (id, oracle_id, illustration_id)priority_chinese: 是否优先显示中文卡牌
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| order | No | 排序字段 (例如: name, -mv, rarity) | |
| page | No | 页码 (默认 1) | |
| page_size | No | 每页数量 (默认 20，最大 100) | |
| priority_chinese | No | 是否优先显示中文卡牌 (默认 true) | |
| q | Yes | 查询字符串，例如 't:creature c:r'、'pow>=5 or mv<2'、's:TDM -t:creature' | |
| unique | No | 去重方式: id(不去重), oracle_id(按卡牌名去重), illustration_id(按插图去重) |
Implementation Reference
- index.ts:333-354 (handler)The main handler function that implements the logic for the 'search_cards' tool by building the API query URL with parameters and fetching the response from the SBWSZ API.
async function handleSearchCards( q: string, page?: number, pageSize?: number, order?: string, unique?: string, priorityChinese?: boolean, config?: z.infer<typeof configSchema> ) { // 构建查询 URL let url = `${config?.apiUrl || BASE_URL}/result?q=${encodeURIComponent(q)}`; // 添加可选参数 if (page !== undefined) url += `&page=${page}`; if (pageSize !== undefined) url += `&page_size=${pageSize}`; if (order !== undefined) url += `&order=${encodeURIComponent(order)}`; if (unique !== undefined) url += `&unique=${encodeURIComponent(unique)}`; if (priorityChinese !== undefined) url += `&priority_chinese=${priorityChinese}`; const response = await fetch(url); return handleSbwszResponse(response); } - index.ts:109-163 (schema)Tool definition including name, detailed description, input schema with parameters (q, page, page_size, etc.), and annotations for the 'search_cards' tool.
const SEARCH_CARDS_TOOL: Tool = { name: "search_cards", description: "通过查询字符串搜索卡牌，支持分页和排序。\n\n" + "**查询语法示例:**\n" + "- `t:creature c:r` (红色生物)\n" + "- `pow>=5 or mv<2` (力量大于等于5或法术力值小于2)\n" + "- `o:\"draw a card\" -c:u` (包含\"抓一张牌\"的非蓝色牌)\n" + "- `(t:instant or t:sorcery) mv<=3` (3费或以下的瞬间或法术)\n\n" + "**分页参数:**\n" + "- `page`: 页码 (整数, 默认 1)\n" + "- `page_size`: 每页数量 (整数, 默认 20, 最大 100)\n\n" + "**排序参数:**\n" + "- `order`: 按字段排序，逗号分隔。前缀 `-` 表示降序\n" + " (例如: `name`, `-mv`, `name,-rarity`)\n" + " 默认排序: `name`\n\n" + "**其他参数:**\n" + "- `unique`: 去重方式 (id, oracle_id, illustration_id)\n" + "- `priority_chinese`: 是否优先显示中文卡牌", inputSchema: { type: "object", properties: { q: { type: "string", description: "查询字符串，例如 't:creature c:r'、'pow>=5 or mv<2'、's:TDM -t:creature'" }, page: { type: "integer", description: "页码 (默认 1)" }, page_size: { type: "integer", description: "每页数量 (默认 20，最大 100)" }, order: { type: "string", description: "排序字段 (例如: name, -mv, rarity)" }, unique: { type: "string", description: "去重方式: id(不去重), oracle_id(按卡牌名去重), illustration_id(按插图去重)" }, priority_chinese: { type: "boolean", description: "是否优先显示中文卡牌 (默认 true)" } }, required: ["q"] }, annotations: { title: "通过查询字符串搜索卡牌", readOnlyHint: true, openWorldHint: true } }; - index.ts:268-276 (registration)Array of all tools including SEARCH_CARDS_TOOL, used for listing available tools.
// 返回我们的工具集 const SBWSZ_TOOLS = [ GET_CARD_BY_SET_AND_NUMBER_TOOL, SEARCH_CARDS_TOOL, GET_SETS_TOOL, GET_SET_TOOL, GET_SET_CARDS_TOOL, HZLS_TOOL ] as const; - index.ts:487-489 (registration)Registers the list of tools (including search_cards) for MCP ListTools requests.
server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: SBWSZ_TOOLS })); - index.ts:500-509 (handler)Switch case dispatcher that extracts arguments and calls the search_cards handler function.
case "search_cards": { const { q, page, page_size, order, unique, priority_chinese } = args as { q: string; page?: number; page_size?: number; order?: string; unique?: string; priority_chinese?: boolean }; return await handleSearchCards(q, page, page_size, order, unique, priority_chinese, config);