Build a tarot reader in Node.js with an open 78-card dataset (no scraping)

使用开源的 78 张塔罗牌数据集在 Node.js 中构建塔罗牌占卜应用（无需爬虫）

I wanted tarot card meanings as clean, structured data for a side project, and quickly hit the usual wall: the good interpretations live in long blog posts, and nobody wants to scrape and parse that. So I ended up packaging all 78 cards as an open, MIT-licensed dataset with npm and Python packages (and an MCP server, more on that at the end). This post is a quick, practical tour: install it, pull a card, build a 3-card spread, and see where else the data lives. No scraping, no API key. 为了一个副业项目，我需要干净、结构化的塔罗牌含义数据，但很快就遇到了常见的问题：高质量的解读通常散落在冗长的博客文章中，没人愿意去爬取和解析这些内容。因此，我最终将全部 78 张牌打包成了一个开源的、采用 MIT 协议的数据集，并发布了 npm 和 Python 包（还有一个 MCP 服务器，稍后会提到）。这篇文章是一个快速实用的指南：安装它、抽取一张牌、构建一个三牌阵，并了解这些数据还能在哪里使用。无需爬虫，无需 API 密钥。

Install npm install tarot-card-meanings It ships with TypeScript types, has zero dependencies, and includes upright, reversed, love, career, and yes/no fields for every Major and Minor Arcana card. 安装 npm install tarot-card-meanings 它自带 TypeScript 类型定义，零依赖，并为每一张大阿卡纳和小阿卡纳牌提供了正位、逆位、爱情、事业以及“是/否”等字段。

Quick start

const tarot = require('tarot-card-meanings');

// Pull a random card
const card = tarot.getRandomCard();
console.log(card.name); // e.g. "The Star"
console.log(card.upright); // upright meaning
console.log(card.reversed); // reversed meaning

// Look up a specific card
const fool = tarot.getCard('The Fool');
console.log(fool.love); // love-context interpretation
console.log(fool.career); // career-context interpretation

// A built-in yes/no reading
const reading = tarot.getYesOrNo();
console.log(`${reading.card}: ${reading.answer}`);

Every card object has the same shape, so you can render it however you like. 快速上手

const tarot = require('tarot-card-meanings');

// 抽取一张随机牌
const card = tarot.getRandomCard();
console.log(card.name); // 例如 "The Star"
console.log(card.upright); // 正位含义
console.log(card.reversed); // 逆位含义

// 查询特定牌
const fool = tarot.getCard('The Fool');
console.log(fool.love); // 爱情语境下的解读
console.log(fool.career); // 事业语境下的解读

// 内置的“是/否”占卜
const reading = tarot.getYesOrNo();
console.log(`${reading.card}: ${reading.answer}`);

每张牌的对象结构都是一致的，因此你可以随心所欲地进行渲染。

Build a 3-card spread The classic past / present / future spread is just three unique cards. Here is a tiny helper that draws without repeats: 构建三牌阵 经典的“过去/现在/未来”牌阵只需要三张不重复的牌。这是一个简单的辅助函数，可以实现不重复抽取：

const tarot = require('tarot-card-meanings');

function drawSpread(positions) {
  const deck = [...tarot.getAllCards()];
  return positions.map((label) => {
    const i = Math.floor(Math.random() * deck.length);
    const card = deck.splice(i, 1)[0]; // remove so it can't repeat
    return { position: label, ...card };
  });
}

const spread = drawSpread(['Past', 'Present', 'Future']);
for (const c of spread) {
  console.log(`\n${c.position}: ${c.name}`);
  console.log(c.upright);
}

That is the whole core of a reading app. Swap the position labels for [‘Situation’, ‘Obstacle’, ‘Advice’] and you have a decision spread instead. 这就是一个占卜应用的核心。将位置标签替换为 [‘Situation’, ‘Obstacle’, ‘Advice’]（情境、障碍、建议），你就得到了一个决策牌阵。

Same data in Python If your stack is Python, the identical dataset is on PyPI: pip install tarot-card-meanings Python 中的相同数据 如果你的技术栈是 Python，同样的数据集也已发布在 PyPI 上： pip install tarot-card-meanings

For the ML / data crowd The raw dataset is also published on Hugging Face and archived with a DOI, so it is citable in a paper or notebook: Hugging Face dataset: https://huggingface.co/datasets/Blacik/deckaura-tarot-card-meanings DOI (Zenodo): https://doi.org/10.5281/zenodo.19475329 It is handy as a small, clean, labeled text corpus for embedding/semantic-search demos. 面向机器学习/数据人群 原始数据集也已发布在 Hugging Face 上，并归档了 DOI，因此可以在论文或 Notebook 中引用： Hugging Face 数据集：https://huggingface.co/datasets/Blacik/deckaura-tarot-card-meanings DOI (Zenodo)：https://doi.org/10.5281/zenodo.19475329 它非常适合作为小型、干净、已标注的文本语料库，用于嵌入（embedding）或语义搜索演示。

Bonus: let an AI assistant read tarot (MCP) Because Model Context Protocol is having a moment, I also wrapped the dataset in an MCP server so an AI assistant can query card meanings as a tool: MCP server: https://github.com/gokimedia/tarot-mcp-server Point a compatible client at it and your assistant can pull meanings and spreads on demand instead of hallucinating them. 额外福利：让 AI 助手进行塔罗占卜 (MCP) 由于模型上下文协议（Model Context Protocol）正当红，我还将该数据集封装成了一个 MCP 服务器，这样 AI 助手就可以将卡牌含义作为工具进行查询： MCP 服务器：https://github.com/gokimedia/tarot-mcp-server 将兼容的客户端指向它，你的助手就能按需获取含义和牌阵，而不是胡乱编造。

See it running If you want to see the data powering a real UI before you build your own, there is a free no-signup reader here: https://deckaura.com/pages/free-tarot-reading All of the above is open and MIT licensed by Deckaura; the package source and issues are on GitHub, and there is a full index of the open data and tools at deckaura.com/pages/ai-data-sources. PRs and label corrections welcome. Happy building, and if you make something with it I would love to see it in the comments. 查看运行效果 如果你想在自己动手构建之前看看这些数据如何驱动真实界面，这里有一个无需注册的免费占卜工具：https://deckaura.com/pages/free-tarot-reading 以上所有内容均由 Deckaura 开源并采用 MIT 协议；包源码和问题反馈在 GitHub 上，完整的开源数据和工具索引位于 deckaura.com/pages/ai-data-sources。欢迎提交 PR 和修正标签。祝开发愉快，如果你用它做出了什么作品，我很乐意在评论区看到。