CSB: Lookup by oracle IDs
csb_lookup_by_oracle_idsMap Scryfall oracle_id UUIDs to Commander Spellbook numeric IDs using a local index. Convert card identifiers between systems for Magic: The Gathering data integration.
Instructions
Map Scryfall oracle_id UUIDs to Commander Spellbook numeric IDs using the local index (builds if stale).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| oracleIds | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| found | Yes | ||
| missing | Yes |
Implementation Reference
- src/csb-index.ts:79-89 (handler)Main handler function that performs the lookup of CSB card IDs by Scryfall oracle IDs using the cached index. Loads index if necessary and maps provided oracleIds to CSB ids.
export async function lookupCsbIdsByOracle(oracleIds: string[], options?: { ttlMs?: number; force?: boolean; cachePath?: string }): Promise<{ found: Record<string, number>; missing: string[] }> { const idx = await loadCsbIndex(options); const found: Record<string, number> = {}; const missing: string[] = []; for (const oid of oracleIds) { const id = idx.oracleToId[oid]; if (typeof id === "number") found[oid] = id; else missing.push(oid); } return { found, missing }; } - src/mcp-server.ts:539-540 (schema)Zod schemas defining the input (array of oracle UUIDs) and output (map of found oracleId to CSB id, and missing list) for the tool.
const csbLookupOracleInput = { oracleIds: z.array(z.string().uuid()).min(1) } as const; const csbLookupOracleOutput = { found: z.record(z.string(), z.number().int()), missing: z.array(z.string()) } as const; - src/mcp-server.ts:541-552 (registration)Tool registration in the MCP server, including thin wrapper handler that delegates to lookupCsbIdsByOracle.
server.registerTool( "csb_lookup_by_oracle_ids", { title: "CSB: Lookup by oracle IDs", description: "Map Scryfall oracle_id UUIDs to Commander Spellbook numeric IDs using the local index (builds if stale).", inputSchema: csbLookupOracleInput, outputSchema: csbLookupOracleOutput }, async ({ oracleIds }: { oracleIds: string[] }) => { const res = await lookupCsbIdsByOracle(oracleIds); return { structuredContent: res } as any; } - src/csb-index.ts:58-77 (helper)Helper function to load the CSB index from memory, disk cache, or build it if stale/missing. Called by the handler.
export async function loadCsbIndex(options?: { ttlMs?: number; force?: boolean; cachePath?: string }): Promise<CsbCardIndex> { const ttl = options?.ttlMs ?? DEFAULT_TTL_MS; const cachePath = options?.cachePath ?? DEFAULT_CACHE_PATH; const now = Date.now(); if (!options?.force && memCache && now - memCache.at < ttl) return memCache.data; if (!options?.force) { const disk = await readCsbIndex(cachePath); if (disk && now - disk.at < ttl) { memCache = { at: disk.at, data: disk.data }; return disk.data; } } const data = await buildCsbIndex(); memCache = { at: now, data }; await writeCsbIndex(data, cachePath).catch(() => {}); return data; }