{
  "markdown": "# The Fortuneteller's Hand — an RPG MCP Server\n\nAn MCP server that acts as a role playing game and GM using the rules of **The\nFortuneteller's Hand**, an original tabletop RPG that I am currently working on. Claude reads the cards, casts the omens, and runs the table; the player and Claude will take turns narrating the story that develops. \n\n## What playing feels like\n\nA short version, before you install anything: you sit with the\nFortuneteller first — where you meet them is the one choice made before any\ncard is drawn. Four suits become four facets of who you are; the\nFortuneteller draws one card from each and speaks what it reveals, and you\nbuild a character from those four phrases. \nOnce you have your character, you must interpret your Goal card before you set out.\n\nFrom there, every scene works the same way: decide where you are, flip a\ncard to see what's stirring, narrate forward. The moment the story reaches\nanother heart, something hidden, or needs a turn of luck, you stop and ask\nfate directly by calling an Omen. Fate can turn against you, too; when\nit does, you can fight it.\n\nThis is, at heart, a creative journaling game. The real pleasure is in the\nnarration you and the Fortuneteller build together, not in winning\nanything. Motivation, Ends, Seek, and Carry aren't rules to obey; they're\nseeds, four starting points for your character's psychology and the shape\nof the story ahead. Follow them where they lead, or let the story wander\nsomewhere else. The more you describe, the more the story gives back.\n\nThat's the shape of it. Full mechanics in [`RULES.md`](RULES.md); a\ngentler, fuller walkthrough in [`HOW_TO_PLAY.md`](HOW_TO_PLAY.md); a full\ntranscript of an actual session in\n[`08-2026-Play-Example.md`](08-2026-Play-Example.md). If you ever lose\ntrack of your Goal or your four facets partway through a story, just ask\nthe Fortuneteller to remind you.\n\n## Running it\n\n### Quick install\n\n1. Download [`fortunetellers-hand-0.1.1.mcpb`](https://github.com/PistachioPony/learnMCP/releases/download/v0.1.1/fortunetellers-hand-0.1.1.mcpb) somewhere findable.\n2. Double-click it (don't drag it into a chat window — just double-click\n   the file itself). It'll open an install prompt in Claude Desktop.\n3. Confirm the install.\n4. Fully quit and reopen Claude Desktop.\n5. Start a new chat, and pull in the `start_game` prompt — it'll ask for a\n   character name, then you're off.\n\n### Run from source\n\nRequires Python and [`uv`](https://docs.astral.sh/uv/).\n\n1. `uv sync` inside this directory.\n2. In Claude Desktop: Settings → Developer → Edit Config, and add:\n   ```json\n   {\n     \"mcpServers\": {\n       \"fortuneteller\": {\n         \"command\": \"uv\",\n         \"args\": [\"run\", \"--directory\", \"/absolute/path/to/learnMCP\", \"main.py\"]\n       }\n     }\n   }\n   ```\n3. Fully quit and restart Claude Desktop.\n4. Click the `+` icon near the message box → Connectors → enable\n   \"fortuneteller.\"\n5. Start a new chat and pull in the `start_game` prompt.\n6. When it asks for your character's name (`player_name`), fill that in.\n7. Once the prompt attaches as a chip above the message box, click send or\n   hit enter — attaching it doesn't submit it on its own.\n\n## Influences\n\nThis project draws from a few places. The Omens' two-dice reading, comparing\nrather than summing, owes a real debt to *Ironsworn* by Shawn Tomkin, which I absolutely LOVE. The\nDefiance ritual, \"Not Like This,\" borrows its five-dice, three-roll,\nkeep-what-you-want shape from Yahtzee (which was stolen from the Puerto Rican game \"Jenerala\"). As a journaling game, this owes a lot\nto *Thousand Year Old Vampire* by Tim Hutchings, one of the games that\nproved solo, prompt-driven play could carry real weight. Incredible game! And finally, Max Moon has shaped the tone of this project throughout. I adore everything Max Moon creates.\n\n## Curious about the build?\n\nThis started as a way to learn the Model Context Protocol in a way that would interest me. The tool/resource/prompt choices, the state design, a few real bugs found and\nfixed along the way, these are all written up in [`DESIGN.md`](DESIGN.md). If you have any questions or wish me to fix, or add anything, please contact me.\n\n## Privacy Policy\n\n- Data collection: This MCP collects nothing.\n- Usage and storage: Nothing is stored. All game state (your character, cards drawn, debt owed) exists only in memory for the length of your session and is discarded when it ends.\n- Third-party sharing: Nothing is shared with any third party, because nothing is collected in the first place.\n- Data retention: Nothing is retained.\n- Contact information: maria@mariasaha.com\n\n",
  "bytes": 4622,
  "sha": "9b74657138741569251350cfee445def85dfecfead3ea59c18c1a547195690dc",
  "repo_slug": "pistachiopony/learnmcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_pistachiopony_fortunetellers_h_0a4f8715/readme"
}