@pipeworx/tarot

Connect: https://pipeworx.io/mcp — every tool in the catalog, including @pipeworx/tarot’s. Install: one-click buttons

No MCP client? Skip the connection: POST https://gateway.pipeworx.io/v1/tools/search_packs {"query":"..."} to find a tool below, GET /v1/tools/<name> for its schema, POST the same URL with arguments for the data — see For AI agents.

Tools: 6

Draws, searches and spreads from an original 78-card tarot deck written for this pack, with seeded/reproducible randomness, optional card reversals, named spreads, and stateful shuffle sessions.

What changed

This pack no longer calls tarotapi.dev. The 78-card deck — every card’s name, keywords, upright/reversed meaning and image description — is written for this pack and shipped inline (src/deck.ts, ~46 KB); nothing is fetched at call time. random_card and draw_cards keep their original argument shapes and gain seed, reversals, and session_id. Two tools are new: tarot_spread (named layouts) and tarot_shuffle (sessions).

Tools

• random_card(seed?, reversals?, session_id?) — draws one card. Returns the card, its orientation (upright/reversed — a 50% coin flip unless reversals: false), the traditional meaning for that orientation, and the seed used (pass it back to reproduce the exact draw).
• draw_cards(count, seed?, reversals?, session_id?) — draws 1–78 cards the same way. (The gateway exposes this tool as tarot_draw_cards when it collides with another pack’s draw_cards; the pack-local name stays draw_cards.)
• search_cards(query) — searches the deck by card name, suit, or keyword (either orientation). A query that matches nothing is a loud error, not an empty list.
• get_card(name_short) — looks up one card by id (major_00..major_21, wands_01..pentacles_14) or exact name ("The Fool", "Ace of Wands"). Returns both the upright and reversed meaning as reference.
• tarot_spread(spread, positions?, question?, reversals?, seed?, session_id?) — deals a named layout: three_card, situation_obstacle_advice, celtic_cross (10 positions), horseshoe (7 positions), yes_no (1 position), or custom (caller supplies positions[], max 20). Each position gets its own card, orientation and meaning. question is echoed back verbatim — this tool never interprets it; the calling agent does.
• tarot_shuffle(session_id?, seed?) — opens a new 78-card session, or reshuffles an existing one if session_id is given.

Meanings are traditional; interpretation is the calling agent’s job, not this pack’s — every tool description says so.

Sessions are hosted-only

session_id (on the drawing tools and tarot_spread) and tarot_shuffle need the gateway’s shared KV to track which cards have already been drawn. A standalone/npm build of this pack has no KV binding, so those calls return { session_supported: false, hint } instead of throwing — single-call seeded draws work identically either way, since they need no session.

A session draws without replacement across calls (it never repeats a card until reshuffled), expires 24h after it’s opened or last reshuffled, and its card order is reproducible from the seed tarot_shuffle returns.

Auth

Keyless. No upstream, no API key, no rate-limited third party — the deck is inline and the randomness is local.

Data sources

This pack has no live data source. The deck’s structure (suit/rank layout, the Major Arcana’s traditional planet/zodiac correspondences, the suits’ elemental correspondences) follows centuries-old public-domain tarot tradition. The Rider–Waite–Smith deck and A.E. Waite’s 1910 “Pictorial Key to the Tarot” (public domain) were consulted only as a reference for which traditional images and themes this deck tracks — every card’s keywords, meanings and image description in src/deck.ts are original text written for this pack, not a transcription of Waite’s or any other published deck’s booklet.

Reproducing a draw

Every drawing tool returns meta.seed. Passing that seed back as the seed argument on an otherwise-identical call reproduces the exact same cards and orientations. Omit seed for fresh randomness — the seed used is always returned either way, so a draw is always citable even when it wasn’t requested as reproducible.

Tools

• random_card — Draws one random card from the Pipeworx original 78-card tarot deck (Rider–Waite–Smith tradition). Returns the card, its orientation (upright or reversed, a coin-flip unless disabled), the traditional
• draw_cards — Draws a spread of 1–78 random cards from the Pipeworx original tarot deck (Rider–Waite–Smith tradition), each with its own orientation and traditional meaning for that orientation.
• search_cards — Searches the Pipeworx original tarot deck by name, suit, or keyword — matches against card names, both orientations’ keywords and meanings, and suit.
• get_card — Looks up one card from the Pipeworx original tarot deck by its id (e.g. “major_00”, “wands_01”) or its exact name (e.g. “The Fool”). Returns both upright and reversed meanings as reference, plus keywo
• tarot_spread — Deals a named layout from the Pipeworx original tarot deck (Rider–Waite–Smith tradition): three_card, situation_obstacle_advice, celtic_cross, horseshoe, yes_no, or a custom set of positions. Each pos
• tarot_shuffle — Opens (or reshuffles) a stateful 78-card tarot session on the Pipeworx original deck, so later random_card/draw_cards/tarot_spread calls with the same session_id draw without repeating a card until th