Jokerly documentation
Jokerly is an American mahjong helper for AI assistants. Show or type your rack: Jokerly counts how many tiles away you are from each hand on your own card, suggests which three tiles to pass in the Charleston, and checks whether a joker swap is legal. The answers come from a rules engine, the same every time.
How it works
- You type your tiles or attach a photo of your rack. The assistant (Claude, Grok or ChatGPT) reads the photo and sends Jokerly tile codes, such as
5Dfor 5 Dot. Jokerly never receives the photo. - Jokerly's engine tries every suit, number and joker placement each hand allows (jokers only in groups of three or more) and returns the result with a one-line summary.
- The answer appears as an interactive card: tap a tile to fix a misread one, open a hand to see its best arrangement, or step through the Charleston pass by pass. The card recounts on the spot.
Your card's hands
Jokerly ships no league's card: card hands belong to their publishers. Type or photograph the hands from the card your table plays and the assistant writes each line in Jokerly notation, for example FF 2222a 4444b 6666c. Until you share yours, Jokerly uses its own practice hands and says so.
- In Claude and Grok, Jokerly stores nothing: your card's lines stay in your conversation and go with each check (up to 40 per question). Ask “Check these hands from my card” to have each line checked and numbered.
- In ChatGPT, Jokerly can also save your hands privately for you (“Save these hands from my card”), until you say “Delete my Jokerly card”.
Connect Jokerly
| App | How |
|---|---|
| Claude | Customize → Connectors, then find Jokerly in the directory once it's listed. Until then, add a custom connector with the URL https://jokerly.ambientapp.ai/mcp/claude and no authentication. Add it on web or desktop; it then works on mobile too. |
| Grok | In Grok Bot, open Connect apps and find Jokerly once listed. Until then, ask Grok Bot: “Add this MCP server: https://jokerly.ambientapp.ai/mcp/grok”. |
| ChatGPT | The plugin directory, under Jokerly American Mahjong (see Jokerly in ChatGPT). |
No account or sign-in is needed anywhere.
What each tool does
check_rack· Claude, Grok, ChatGPT- Counts how many tiles away your rack is from every hand (your card's lines, or the practice hands), with what each hand still needs and where jokers can stand in. Reads the tiles you send. Changes nothing.
suggest_charleston_pass· Claude, Grok, ChatGPT- Tries every set of three tiles and suggests the pass that keeps you closest to your hands, never a joker; says when a blind pass saves a tile. Reads the tiles you send. Changes nothing.
check_joker_swap· Claude, Grok, ChatGPT- Says whether a joker swap is legal under the standard rules, which rule decided, and whether the swap brings you closer. Reads the tiles you send. Changes nothing.
show_card_hands· Claude, Grok, ChatGPT- Claude and Grok: checks the lines you typed or photographed from your card and numbers them, or lists the practice hands. ChatGPT: shows the hands you saved. Reads. Changes nothing.
save_card_hands· ChatGPT only- Saves hands from your own card for you alone. Adds hands to your private saved card.
remove_card_hands· ChatGPT only- Removes saved hands by number, or deletes your whole saved card. Deletes saved hands.
Tile codes: 1B-9B Bams, 1C-9C Craks, 1D-9D Dots, N E W S winds, RD GD WD dragons (WD is Soap), F flower, J joker, and ? for a tile that can't be read.
Example prompts
| Say | What happens |
|---|---|
| “Here's my American mahjong rack: 2B 2B 4B 4B 6B 6B 8B F F J N 9D 3C. How close am I to a hand?” | check_rack: the closest hands, ranked, with the tiles each needs |
| “What three tiles should I pass right in the first Charleston?” | suggest_charleston_pass: the three tiles, why each goes, and the joker kept |
| “Can I swap my 5 Dot for the joker in their 5 Dot pung? It's my turn and I drew.” | check_joker_swap: allowed, the rule that decided, and the effect on your rack |
| “These are the hands on my card: [photo of your card, or the lines typed]. Check my rack against them.” | show_card_hands, then check_rack with your lines |
Jokerly is for American mahjong (the game with jokers, the Charleston and a yearly card). It doesn't score games, play Riichi or Chinese mahjong, recite any league's card, or handle money.
Troubleshooting
- A tile was read wrong.
- Jokerly lists every tile it received. Tap the tile in the card and pick the right one; the counts update at once. Or type the right tiles in the chat.
- Grok didn't notice the tile I fixed in the card.
- Grok can't see changes made inside the card. The card then shows your rack as tile codes: send them in the chat and ask again.
- A line from my card was rejected.
- Jokerly says what's wrong, usually the tile count (a hand is 14 tiles) or a missing suit letter. See how to write a hand and send the line again.
- It used the practice hands, not my card.
- Share your card's lines in the conversation (typed or a photo) and ask to check against them. In Claude and Grok they aren't saved, so a new conversation starts on the practice hands again.
- The card doesn't appear.
- The answer still arrives as text. In Claude, interactive cards show on web, desktop and mobile; if you added Jokerly as a custom connector before an update, remove it and add it again so Claude reloads its tools.
- A link asks for confirmation.
- The card's only link is Jokerly's notation guide on jokerly.ambientapp.ai. Your app may ask before opening it.
- My table plays a different joker rule.
- Jokerly checks the standard rules and says which rule decided. House rules win at your table.
Privacy, terms and support
In Claude and Grok, Jokerly receives the tiles and hand lines in each question, answers, and stores none of them; it receives no name, email or user ID. Technical logs (counts and field names, never tiles, hands or IP addresses) are kept for 30 days. Jokerly has no ads, no payments and no AI-generated images. Read the privacy policy and the terms.
Support: support@theopenapps.com (email only, answered within two business days). Jokerly is made by The Open Apps, Inc.