Imagina RPG

Assemble a chunked upload and put it on the slot named when the session was opened. The world, the draft and the slot are checked again here.

finish_image_upload

Cheap table of contents for one of your worlds: every top-level field with its size and a short preview (short values verbatim), and every list (npcs, loreBook, beats, ...) with its item count and each item's name/id, a one-line preview, and JSON size. Call this FIRST to see the shape, then read only the fields you need with get_world. Includes a _restApi URL that returns the full world JSON. By default the latest version; pass versionId for a specific one.

get_world_outline

What an image for each world slot should be: target size, shape, accepted formats, transparency and the size limits. Read this before making or sourcing art, so a picture is not rejected or reshaped after the fact.

get_image_requirements

Inspect the debug turns of one of your journeys on a world you author: the same world-writer debug view you get in the app. Each turn includes the player action, narrative, the world-state changes it made (trackers, NPCs, plot threads, fired beats, revealed lore), player-safe reasoning, a per-step trace of what the AI did (coarse action kinds, which ones the engine refused, and the text of refused narration drafts, which explains a reply that rewrote itself while streaming), dice rolls, the credits it cost you, and percentage-only token stats, plus the latest world state. Raw prompts and tool-call names, arguments and results are not included. Only works for your own journeys on your own worlds.

get_journey_debug

Dice worlds only. Without action: the check the story is waiting on (after a turn with checkCall, roll it, then play_turn with no action to continue). With action: the check that suggested action needs before it can be played (null means play it as is). Roll a returned card with roll_dice_check, then play_turn with that same action. Needs the play-tools opt-in.

get_dice_check

Performance analytics for one of your worlds: the same numbers as the in-app creator dashboard. Lifetime totals (unique players, journeys, turns, reroll rate, credits earned), the same figures over the selected period (periodTotals, what the dashboard tiles show), a per-day series (journeys, turns, rerolls, new players) over the selected period, and engagement metrics computed over a sample of journeys active within that period (up to the 1000 most recent): average/median turns per journey, a turns-per-journey histogram split into new vs returning players, and model usage share. Earnings over time are lifetime. Also world-page views: lifetime totals plus a period block (views, unique viewers, and the share of viewers who went on to play), with views and uniqueViewers in the per-day series. View counting only began on views.countingSince (YYYY-MM-DD): a period starting before that day is incomplete on the view side. Signed-in viewers dedup exactly; signed-out ones are counted once per day, so unique viewers is a floor for reach, not a headcount. Your own playtesting is excluded by default; pass includeOwn to count it (the own block always reports what is being left out). Your own page views are never counted at all.

get_world_analytics

Whether a turn is still being written on a journey, and the latest turn. Use it after play_turn answered status "generating": poll every 10 to 20 seconds until generating is false. Needs the play-tools opt-in.

get_journey_status

Page back through a journey's turns, oldest first within the page. before is a turnNumber: the page ends just before it (use the first turnNumber of the previous page to keep going back). Needs the play-tools opt-in.

list_journey_turns

List your own journeys (playthroughs) that run on worlds you author, newest first. These are the journeys you can debug as the world's writer. Use get_journey_debug to inspect a journey's turns. Optionally filter by worldId.

list_my_journeys

List the albums and tracks in your music library (uploaded on the website's Music page), with their ids, titles, artists, durations and moods, and which of your worlds link each album. Use the ids in a world's music settings (music.albumIds, music.themeTrackId, music.lockedTrackIds), a location's musicTrackId, and playMusic beat effects. Pass worldId to also get that world's music settings and the albums it links with their tracks (a forked world can link albums you do not own: those can be cued but not linked anew). Read-only: uploading music stays on the website.

list_my_music

List the journeys (playthroughs) you play, on any world, newest first. Party journeys are left out (they are played in the app). Needs the user's play-tools opt-in, like every play tool: see play_turn.

list_my_playthroughs

List the worlds (stories) you own, including drafts. Returns each world's id, name, description, published/latest version ids, version count, content flags and tags. Use get_world to read a full definition.

list_my_worlds

The narrator models this account can play with, each with its estimated credits per turn (sized on the journey when journeyId is given). Use an id with set_journey_model or start_journey. Needs the play-tools opt-in.

list_play_models

List all versions of one of your worlds (newest first), with version number, engine version, changelog, and timestamps.

get_world_versions

Play one turn of one of your journeys: the narrator writes what happens after the player's action. SPENDS the user's credits (the journey's model price, see list_play_models), within the daily MCP limit the user set. All play tools are off until the user switches them on in the Imagina app at https://playimagina.com/create/integrations; a call before that is refused with that link. Pass it on to the user. - action: what the player character does or says, in their voice. Leave it out to let the story continue. A suggested action from the last turn can be sent word for word. When the last turn has pendingPlayerPrompt of kind "choice", the action must be one of its options. - Dice worlds: a suggested action may need a roll first (get_dice_check with that action, roll_dice_check, then play_turn). - steering: an optional out-of-character note to the narrator for this turn ("slow down", "introduce the captain"). - expectedParentTurnId: the id of the latest turn you saw; the call is refused if the journey moved on (avoids double-playing on a retry). - Waits up to about 45 seconds. A slower turn answers status "generating": call get_journey_status every 10 to 20 seconds for the result. Never resend the action while it is generating. - Turns can be undone with rollback_journey.

play_turn

Read one of your journeys as the player sees it: title, narrator model, whether a turn is being written, the last few turns (narrative, suggested actions, visible dice rolls, ending), the character sheet and any pending choice. Needs the play-tools opt-in.

get_journey

Get the world definition ONE of your journeys is actually running on. A journey freezes the world at the moment it started and never picks up later edits, so when a journey misbehaves this frozen snapshot, not the world you are editing, is what the storyteller reads. Use it with get_journey_debug to explain why a beat did not fire or a tracker went missing. Returns the journey's settings and how its pinned version compares to the world today, plus a _restApi URL for the full snapshot: snapshots are large, so curl that URL into a file and grep/jq the file rather than pulling it into the conversation. Pass fields to inline just a few top-level keys instead. Only works for your own journeys on worlds you author.

get_journey_world

Get the definition of one of your worlds. Worlds can be large, so prefer get_world_outline first, then fetch only the fields you need here: pass fields: ["npcs", "generalInstructions"] to return just those top-level keys (id, versionId, name are always included; unknown keys are reported in missingFields). Omit fields to get the whole world. The response also includes a _restApi URL that returns the full world JSON for about 5 minutes (curl to a file / pipe to jq). By default the latest version; pass versionId for a specific one.

get_world

Get Imagina's Markdown reference with examples for authored introductions, public world descriptions, fictional texting bubbles, text effects, images, and story beats. Explains introduction-only versus live-narration formatting and which world settings enable features. During play the storyteller already knows enabled syntax. Returns documentation only, with no inputs, world edits, or real message sending. The same guide ends get_authoring_guide, so skip this if you already read that.

get_markdown_guide

Documentation for this MCP: how the tools work, the editing loop, and a guide to authoring a great Imagina world (what each part of a world is for and how to write it well), followed by the full Markdown guide for player-facing text. Call this before creating or editing a world, and refer back to it while you work.

get_authoring_guide

Roll the dice for a check card from get_dice_check (checkId from the card; edgeId optionally spends one of the card's before-roll edges). Free. Then play_turn with the card's action (or no action for a check the story paused on). Needs the play-tools opt-in.

roll_dice_check

Undo a journey back to a turn: every turn after turnId is removed (or kept as an alternate version of the next turn when keepAsAlternate is true), and the story continues from turnId. Use it to retry a branch. Needs the play-tools opt-in.

rollback_journey

Switch the narrator model of one of your journeys (ids from list_play_models). It changes what each later turn costs. Needs the play-tools opt-in.

set_journey_model

Start a new journey on a world and return its opening. Free (the turns that follow cost credits). Needs the user's play-tools opt-in; at most a few journeys per day through the MCP. - worldId: any published world the user can play. versionId plays a specific draft of a world YOU own (playtesting your draft); leave it out for the published version. - characterIndex picks the player character on worlds that offer several (0-based, default 0). model sets the narrator model (see list_play_models; default the account's). - Then play with play_turn.

start_journey

Make another version of the LATEST turn the current one (versions come from regenerating or a rollback that kept the alternate). turnId is the alternate's id. Needs the play-tools opt-in.

switch_turn_version

Update one of your worlds by merging top-level fields into a DRAFT version. Best for scalar fields (name, description, generalInstructions, writingStyle, flags) and whole-field replacement. Call get_world_outline or get_world first to read the current state. IMPORTANT: - To edit ONE list entry (an NPC, a lore entry, a beat), use upsert_world_list_item / delete_world_list_item instead. Here, arrays (npcs, playerCharacters, loreBook, additionalInstructions, settings, tags, ...) are REPLACED entirely, which also clobbers concurrent edits to sibling items. - Edits only an unpublished DRAFT. If the requested version is published, use the latest unpublished draft if one exists. Before calling create_world_version, inspect the world's latest version. If the latest version is already an unpublished draft, edit it instead of creating another. A world can have an older published version and a newer draft at the same time. Only create a draft when the latest version is published, or when the user explicitly asks for a fresh version. Respect the user's versioning wishes and do not accumulate unpublished drafts by default. A new draft first copies its images from the previous version: create_world_version returns status "preparing" while it does (a minute or more for a world with many images), and every edit, publish or delete of that draft is refused until it is ready. Call get_world_version_status every few seconds until status is "ready", then edit it. Edit the draft, then publish from the Imagina app. - additionalInstructions must be an array of objects { name: string, content: string, nsfwOnly?: boolean, partyOnly?: boolean }. nsfwOnly limits a block to NSFW journeys (the same gate as nsfwInstructions), partyOnly to journeys played by a party. Beats, endings (goodEnds/badEnds entries and simpleEndings sides), achievements, loreBook, codex, startingTrackers (the world's and each player character's), tables and seededLocations entries take the same optional nsfwOnly: true ("Only if NSFW is on"), which on an SFW world keeps them out of journeys and readers whose NSFW is off. - Protected fields (id, versionId, versionNumber, engineVersion) cannot be changed. - Writes may run in parallel: each is applied to the draft as it is when it saves, and returns the new revision. Pass expectedRevision (from a read or an earlier write) to have the write refused instead if the draft changed since. - Endings are one mode at a time. journeyEndingMode: "simple" uses simpleEndings ({ victory?: { enabled, condition, displayText }, defeat?: {...} }); "multiple" uses goodEnds/badEnds ([{ id, title, condition, displayText }], max 10 each); null turns endings off. Switching simple -> multiple converts the pair into named endings (send the mode change alone). Switching multiple -> simple, or turning endings off, deletes the current endings: confirm by sending goodEnds: [] and badEnds: [] (or simpleEndings: {}) in the same update. A list only accepts content in its own mode. Any ending (either mode) may also carry imageId: the id of a world extraImages entry, shown above the ending text on the end screen. An id that matches no extra image simply renders nothing, and an extra image marked nsfw is hidden on a journey that is not adult. - A key that is not a valid world field is rejected, EXCEPT to delete it: if the world still stores such a key from an older write (it shows up in get_world / get_world_outline), send it as null to remove it for good, e.g. fields: { "trackers": null }. - Character spriteLooks are outfits: { id?, name, description?, extraPrompt?, bodyPrompt? }. Omit id for a NEW outfit to have one assigned. Keep existing ids when editing. The response's outfitIds lists the saved { id, name } pairs per character, ready for gallery lookId and outfit beat references. Supplied ids must be non-blank strings and unique within that character. - Character gallery images keep their stored id and key; only labels and flags are editable (exposeToAI is on by default, and a "sprite" label belongs on a transparent cutout; a flat one stands on the stage as a rectangle until its background is removed in the app). See get_authoring_guide, "Character images".

update_world

Put an image you already have onto one of your DRAFT worlds, sending the bytes inline as base64. One image per call. - Call get_image_requirements first: the image is re-encoded to WebP and scaled to FIT the slot box (aspect kept, never enlarged), so it is NOT cropped for you. The title card, portrait, background, location and share card only take a picture within 1.2x of their slot's aspect and refuse anything further off (crop it to the slot's shape first). - Accepted input: JPEG, PNG, WebP. Inline limit: 4194304 base64 characters. For a bigger file use begin_image_upload, or set_world_image_from_url. - Draft-only, like every write here. Publish from the Imagina app. - target "gallery" adds a picture to a character's gallery. A "sprite" / "sprite:<state>" label wants a transparent cutout, whose framing is measured from the image. An opaque sprite is still stored, but the reply's warnings say so: then either cut it out yourself and upload again with replaceLabel, or tell the user to use "Remove background" on it in the editor gallery. - target "share_card" sets the world's social sharing card: 1200x630 (1.91:1) art for the link preview, replacing the composed title card + background image. The world name, author and site name are drawn over its left 40%: keep that part dark and free of text, put the characters in the right 60%. Clear it with update_world shareImage: null. - target "showcase_background" sets the world's showcase background: optional 16:9 art shown instead of the play background on world cards, the home hero and the link preview, never in play. Same size as the play background. Clear it with update_world showcaseImage: null. - target "codex" sets a Codex entry's picture (entryId names the entry). It is fitted inside 1536px, any shape: square suits items, landscape suits places, and a transparent cut-out keeps its transparency. A picture a character already has (portrait or gallery) does not need uploading again: set_codex_image_from_character points the entry at it. - target "extra_image" adds a scene picture to the world's extraImages (label, nsfw) and returns its extraImageId, ready for a beat's showSceneImage, an ending's imageId or ::scene[label]. replaceId swaps an existing entry's picture and keeps its id, so whatever uses it stays linked. At most 40 per world (80 for trusted authors). - The reply reports what was stored: final width/height, file bytes, whether it was downscaled, the slot box, and warnings when the result is smaller than the slot (shown upscaled) or the wrong shape for a cropped slot.

upload_world_image

Use one of a character's existing pictures (their portrait, or an image from their gallery) as a Codex entry's picture on one of your DRAFT worlds. The entry points at the same stored image, nothing is copied or uploaded. This is the editor's "Choose from a character's gallery" button. - entryId names the Codex entry: its id (get_world with fields ["codex"]), or its exact title as get_world_outline lists it. subject + index name the character, like the portrait / gallery image targets: "npc" indexes npcs, "player" indexes playerCharacters. - Omit galleryImageId to use the character's portrait; pass a gallery image's id (get_world shows each character's gallery) to use that picture. - An explicit gallery image (nsfw: true) is shown to every reader of the entry, so on an SFW world it is only accepted on an entry marked nsfwOnly. - Any entry can take any character's picture, though it fits best on a character entry linked to that NPC. - To remove the picture later, set the entry's image to null with upsert_world_list_item (list codex). To put NEW art on an entry, use upload_world_image with target "codex".

set_codex_image_from_character

Discard a chunked upload started with begin_image_upload.