starreach

This game takes the form of a web server that supports both an HTTP API using Starlette as well as an Model Context Protocol (MCP) API using FastMCP. A browser UI built on HTML, css, and jquery provides a view into the state of the game, while the MCP API allows a Large Language Model (LLM) to interact with the game to retrive state and take actions. The intent is the player interacts with the came through the LLM rather than through the web UI.

Design docs

The game design lives in docs/:

• docs/ONTOLOGY.md: what exists, the rules, the numbers, and the MCP/HTTP interface (the implementation reference)

• docs/CRITERIA.md: how each rule is checked

• docs/RATIONALE.md: why each choice was made, and open questions

• docs/DYNAMICS.md: why it's fun

• docs/ARCHITECTURE_LOG.md: dated history of design changes

• YUWAKISA.md: recommendation for deploying on yuwakisacloud (D-20)

Related MCP server: Blocksworld Simulation MCP Server

Run in Claude Desktop

Provide the full path to the venv python and the launcher

"mcpServers": { "starreach": { "command": "C:/work/starreach/venv/Scripts/python.exe", "args": ["C:/work/starreach/starreach.py"] } }

How to Launch and View the Game

1. Set Up the Environment:

   • Create a virtual environment:

     python -m venv venv

   • Activate the virtual environment:

     • On Windows:

       venv\Scripts\activate

     • On macOS/Linux:

       source venv/bin/activate

   • Install the dependencies:

     pip install -r requirements.txt

2. Start the Servers:

   • Run the following command in the root directory:

     python starreach.py

   • One process serves both: MCP over stdio, with HTTP on http://localhost:8000 (--stream serves streamable-HTTP MCP at http://localhost:8000/mcp instead).

3. View the Game UI: not served yet (RATIONALE Q-8).