# YesNoMystery MCP Server Official [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for **[YesNoMystery — Lateral Thinking Puzzles](https://lateralthinkingpuzzles.org)** (*Turtle Soup / Black Stories / Situation Puzzles*). Search **1,000+ official mysteries and public community puzzles across 12 languages**, ask an AI game host yes/no deduction questions (with or without conversation history), track clue progress (0–120 scale), and reveal solutions using the exact same dynamic credit rules as the website. **[Play on Website](https://lateralthinkingpuzzles.org)** | **[Browse Puzzles](https://lateralthinkingpuzzles.org/puzzle)** | **[Community Mysteries](https://lateralthinkingpuzzles.org/community)** | [简体中文](./README.zh-CN.md) | [日本語](./README.ja-JP.md) --- ## Features - **Full Public Catalog (`ynm_search_puzzles`)**: Search and filter all official mysteries and password-free community (UGC) puzzles across 12 languages (`en`, `zh`, `zh-TW`, `ja`, `ko`, `de`, `es`, `fr`, `it`, `pt`, `ru`, `th`) by category, difficulty tier (`1–3`), tags, keyword query, or random sampling. Spoilers are never returned. - **Live Progress & Clue Tracking (`ynm_get_puzzle`)**: Inspect the scenario, investigation question targets, your unlocked clues, raw progress (`0–120`), and current dynamic answer reveal price. - **Contextual or Standalone AI Referee (`ynm_ask_question`)**: Ask yes/no questions and get structured verdicts (`yes`, `no`, `unknown`, `partial_ok`, `needs_rephrase`). Choose `include_history: true` (default) to carry prior Q&A context or `include_history: false` to evaluate independently. - **Fair Dynamic Reveal (`ynm_reveal_solution`)**: Matches website pricing — `20/30/40` credits at 0 progress depending on difficulty, `1` credit at `progress >= 80`, and **FREE (`0` credits)** once your deduction reaches `progress >= 100`. - **Zero Setup Required**: Works out of the box with 50 free anonymous trial credits (`2` credits per question) and no API key required. --- ## Quick Start ### Option A: Local `stdio` (`npx`) Add to Claude Desktop, Cursor, Windsurf, or any MCP client config: ```json { "mcpServers": { "yes-no-mystery": { "command": "npx", "args": ["-y", "yes-no-mystery-mcp"] } } } ``` You can also invoke the keyword alias CLI package: ```json { "mcpServers": { "lateral-thinking-puzzles": { "command": "npx", "args": ["-y", "lateral-thinking-puzzles-mcp"] } } } ``` ### Option B: Remote Streamable HTTP (No install required) Connect directly to the hosted MCP endpoint: ```text https://lateralthinkingpuzzles.org/api/mcp ``` --- ## Tools Reference | Tool | Read-Only | Description | | --- | --- | --- | | `ynm_search_puzzles` | Yes | Search/filter official & public UGC puzzles across 12 languages (`locale`, `source`, `category`, `difficulty`, `tags`, `query`, `random`, `limit`, `offset`) | | `ynm_get_puzzle` | Yes | Get scenario, question targets, current progress (`0–120`), unlocked clues, and current answer price (`puzzle_id`, `locale`, `source`) | | `ynm_ask_question` | No | Ask a yes/no question with `include_history` (`true` by default) and optional `history` or `reset_history` (`2` trial credits/question) | | `ynm_reveal_solution` | No | Reveal full solution & all clues using dynamic pricing (`0` credits free once `progress >= 100`) | --- ## Optional Environment Variables (stdio mode) - `YES_NO_MYSTERY_API_BASE_URL` — Override API base URL (default: `https://lateralthinkingpuzzles.org/api/mcp`) - `YES_NO_MYSTERY_TIMEOUT_MS` — Request timeout in milliseconds (default: `45000`) --- ## Play More on YesNoMystery - English Puzzles: [lateralthinkingpuzzles.org/puzzle](https://lateralthinkingpuzzles.org/puzzle) - 简体中文海龟汤: [lateralthinkingpuzzles.org/zh](https://lateralthinkingpuzzles.org/zh) - 繁體中文海龜湯: [lateralthinkingpuzzles.org/zh-TW](https://lateralthinkingpuzzles.org/zh-TW) - 日本語ウミガメのスープ: [lateralthinkingpuzzles.org/ja](https://lateralthinkingpuzzles.org/ja) ## License MIT — see [LICENSE](./LICENSE).