FrankieTarot API

塔罗数据,
解读由你决定。

用双语牌义、原始牌图与牌阵布局构建应用,通过 REST 或 MCP 接入。

阅读 API 文档 ↗
愚人
0愚人
真实重绘牌图中的愚人。这是固定牌库示例,不是抽牌结果。

牌库,是一次解读的其中一部分。

Frankie 返回结构化的牌面参考与牌阵定义。问题、选牌、正逆位、解读与保存状态,由调用方界面负责。

双语牌面资料

获取名称、关键词、描述、正逆位牌义、三种牌图 URL 与来源信息。maj00 这样的稳定 ID,在不同语言中仍指向同一张牌。

带有位置语义的布局

每个牌阵提供牌数、有序位置标签与各位置的牌池。例如宫廷行为模式依次使用点数牌、宫廷牌与大阿卡纳。

智能体也使用相同数据

五个无 UI 的 MCP 工具提供检索、查询、牌阵定义与可选抽牌。服务本身不调用语言模型,也不生成个性化解读。

78
张牌
11
种牌阵
en / zh-CN
语言

从一张确定的牌开始。

确定性的牌面查询适合作为第一条请求。这个节选示例使用真实牌库字段;完整响应还包括牌义、牌图 URL 与来源。

打开真实响应 ↗
curl "https://tarot-api.songhai.site/api/v1/cards/maj00?locale=zh-CN"
{
  "id": "maj00",
  "name": "愚人",
  "names": {
    "en": "The Fool",
    "zh-CN": "愚人"
  },
  "arcana": "MAJOR",
  "suit": null,
  "rank": 0
}

先了解定义,不必抽牌。

这个小示例改编自真实的 SpreadLayout 组件,使用当前源码数据。编号图形表示位置,并非已经选出的牌;不会发送请求或保存记录。

    第一次接入

    1. 加载参考数据

      选择 en 或 zh-CN 获取牌库与牌阵,默认语言为 zh-CN。牌库不分页,公共服务无需 API key。

    2. 在应用中保留手动选择

      让用户选择牌阵与牌,再按 ID 查询。独立的 Frankie Tarot 应用提供交互牌桌,这个服务提供参考数据。

    3. 明确选择后,再自动抽牌

      可选的随机牌与牌阵抽牌接口,每次都会生成新样本。只有用户明确委托自动抽牌时才调用;只提出一个问题,并不等于同意代选卡牌。

    4. 保存成功返回的结果

      调用方保存牌 ID、位置、正逆位与准确的牌阵定义。没有公开种子、幂等键或恢复接口;结果不确定时再次请求,会是新一次抽牌。

    应用用 REST,工具用 MCP。

    REST 提供带 CORS 的只读 GET 接口。Agent MCP 通过 /mcp/agent 的 Streamable HTTP 返回结构化内容;它是工具服务,不是 ChatGPT 可视化组件或账号系统。

    智能体指南 ↗

    MCP 官方传输与工具说明 ↗

    已注册的工具

    • search_tarot_cards
    • get_random_tarot_cards
    • draw_tarot_spread
    • get_tarot_card
    • list_tarot_spreads

    当前的完整参考文档

    理解资料,也理解边界。

    来源层次保持可见

    主要牌义附有 PKT 1911 英文引文出处与中文编辑摘要。modernMeanings 保留项目整理的延伸解释,图像变体、关键词与描述同样经过项目编辑;不能把所有字段都视为历史原文。

    没有隐藏的解读数据库

    服务没有数据库或模型 API 依赖。历史、恢复、用户选择、解读与正逆位由调用方管理;象征性牌义不是事实预测或概率。

    处理结构化错误

    不合法查询返回 400,不存在的牌或牌阵返回 404,不支持的 REST 方法返回 405。应处理错误响应,不能编造成功结果。

    在本地运行服务

    REST 与 Agent MCP 位于 http://127.0.0.1:3001。独立的 Vite 命令用于编辑完整文档;只启动静态文件服务器,并不会运行服务。

    截图与接口约定更新指南 ↗
    npm ci
    npm run api