pyularn-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| PYULARN_HOME | No | Folder where scores and save games are stored. Defaults to ~/.pyularn; set PYULARN_HOME to use another folder. | ~/.pyularn |
| PYULARN_WATCH | No | Set to a port (e.g. 8765) to enable the live spectator web page, equivalent to the --watch option. Use 0 to pick a free port. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Play the roguelike Ularn. Start with new_game, then use move / send_keys and read the returned screen.
Ularn controls (keys are sent with the send_keys tool): Movement h=W j=S k=N l=E y=NW u=NE b=SW n=SE (capital letter = run) . stay here one turn (space) do nothing i inventory g pack weight w wield a weapon W wear armour T take off armour d drop an item q quaff (drink) a potion r read a scroll or book e eat a fortune cookie c cast a spell (then a 3-letter code) \ list known spells o / C open / close a door O open a chest ^ identify adjacent traps Z teleport (level 10+) P show taxes owed S save game and quit Q quit ? help pages v version ^R () redraw screen Walking onto an object or a building usually brings up a prompt; answer it with the letter shown. Answer y/n prompts with y or n; cancels most prompts and menus. Inventory prompts take the item's slot letter. Map symbols: @ you, # wall, letters are monsters, other symbols are objects:
gold ! potion ? scroll [ armour ( weapon = ring or mirror " amulet / wand or staff < gem B book C chest c fortune cookie % staircase ~ elevator ^ trap O / D open / closed door P pit A altar T throne F fountain & statue : drugs Town buildings: E dungeon entrance, V volcanic shaft, H your home, S DND store, M College of Larn, $ bank, T trading post, L Larn Revenue Service, P Dealer McDope's Pad. Walk onto a building to enter it. The
get_statetool gives exact stats. The goal: find the potion of cure dianthroritis and return home with it before the time limit runs out.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| new_gameA | Start a new game of Ularn (ends any game in progress). Returns the screen and player state. |
| send_keysA | Send keystrokes to the game and return the resulting screen. Plain characters are sent literally; use , , , , ///, for special keys. Call key_reference for the command list. |
| moveB | Move the player one or more steps in a compass direction (or run until something interesting). |
| get_screenA | Return the current 80x24 game screen without sending input. |
| get_stateA | Return structured player state as JSON: stats, HP, gold, dungeon level, position, inventory, active effects and known spells. |
| key_referenceA | Return the list of Ularn commands, map symbols and the goal of the game. |
| end_gameA | Stop the game in progress without saving. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 7 tools
Most tools have clearly distinct purposes: get_screen vs. get_state vs. key_reference vs. new_game/end_game are unambiguous. The main overlap is move versus send_keys, since movement could also be done by sending direction keys; the descriptions clarify the intended split, but an agent may still hesitate between them.
Most names follow a verb_noun pattern (get_screen, get_state, send_keys, new_game, end_game), which is predictable and readable. The bare verb 'move' and the noun-phrase 'key_reference' are minor deviations, not enough to cause confusion.
Seven tools is well-scoped for an interactive game server: screen/state inspection, input, movement, lifecycle control, and a reference tool. Each tool earns its place without redundant surface area.
The surface covers the core game lifecycle: start, inspect screen/state, send input, move, get help, and end. send_keys acts as a general escape hatch for unmodeled actions, though there is no explicit save/resume or wait/rest operation.