Echoes of Dustwood is a Free Pascal/Go text adventure game with AI agent integration via the Model Context Protocol (MCP). The repo compares 4 AI frameworks (Pydantic AI, Agno, Strands, ADK) on autonomous gameplay.
src/pascal/dustwood.pas— Main game logic (Free Pascal). Core state machine, command parser, survival mechanics.src/golang/main.go— Go port of the same logic (preferred for MCP due to better concurrency).data/world.ini— Game world definition (rooms, items, exits).Makefile— Build targets:make build-go,make build-pascal.
Each lives in packages/<framework>/ with its own venv:
pydantic_client.py— Direct stdio gameplaypydantic_mcp_client.py— MCP-based gameplay (recommended)- Setup:
cd packages/pydantic && uv sync --prerelease=allow - Model format:
google:gemini-3.5-flashoranthropic:claude-3-5-sonnet-20241022
agno_client.py— Direct stdio gameplayagno_mcp_client.py— MCP-based gameplay- Setup:
cd packages/agno && uv sync --upgrade - Framework: Uses Agno's built-in MCP tools
strands_client.py— Direct stdio gameplaystrands_mcp_client.py— MCP-based gameplay- Setup:
cd packages/strands && uv sync --upgrade - Framework: LiteLLM for broad model support
adk_mcp_client.py— MCP-based gameplay- Setup:
cd packages/adk && uv sync --upgrade - Framework: Google ADK with MCP toolset integration
vibepascal_shared/guidance_loader.py— Loads difficulty-based gameplay hintsvibepascal_shared/llm_observability.py— Logging, HTTP debugging, timingvibepascal_shared/mcp_command_policy.py— Command validation
- Root-level
*-game.shscripts (e.g.,pydantic-mcp-game.sh) — Wrapper scripts that invokeuv run --project packages/<fw>with the right arguments. play-mcp-game.sh— Runs all 4 frameworks sequentially for benchmarking.
The frameworks have incompatible dependency versions (e.g., pydantic-ai 2.0.0b3 requires pydantic 2.14a1, while agno works with stable pydantic 2.13). Monolithic venv doesn't work; isolation does.
The original "stdio" clients parse game output as text. MCP clients use structured tool calls, allowing agents to:
- Call
command(cmd="LOOK")and get back JSON state - Reason about structured game state, not text
- Avoid hallucinations from parsing
The Go port (bin/dustwood-go) handles HTTP MCP better (async I/O, signal handling). Pascal version is the original but less suitable for server workloads.
./bin/dustwood-go --mcp-http --mcp-addr 127.0.0.1:8765 --mcp-json-response &
./pydantic-mcp-game.sh google-gla:gemini-3.5-flash 25 1 fullcd packages/agno
uv sync --upgrade./bin/dustwood-go --mcp-http --mcp-addr 127.0.0.1:8765 --mcp-json-response &
./play-mcp-game.sh google-gla:gemini-3.5-flash 25 1 full- Edit
src/golang/commands.go(preferred) orsrc/pascal/u_commands.pas - Rebuild:
make build-goormake build-pascal - Test with an MCP client (it will auto-discover new tools)
- Check wrapper script logs in
logs/(if enabled) - Look at
packages/shared/vibepascal_shared/llm_observability.py— enables HTTP/model payload logging via env vars:HTTP_DEBUG_LOGGING=1,PROVIDER_PAYLOAD_LOGGING=1 - MCP server logs: redirect
./bin/dustwood-go --mcp-http ... > logs/mcp-server.log 2>&1
The repo recently underwent a restructure (May 2026):
- Moved
scripts/clients into isolatedpackages/<fw>/with per-framework pyproject.toml - Each framework now has its own lockfile and venv
- Updated all wrapper scripts to use
uv run --project
If you're working on a feature branch, expect RM and R entries in git status (git mv moves), not new files.
No automated test suite currently. Manual testing via the MCP clients (see "Common Tasks" above).
- Documentation: See the main README.md for the project overview and index.
- System Architecture: src/ARCHITECTURE.md — Detailed mirrored engines walkthrough.
- Framework Setup: packages/README.md — How virtual environments are structured.
- Game world:
data/world.ini— Edit to add/modify rooms and items - MCP spec: Game exposes
commandtool; seesrc/golang/mcp_server.gofor implementation - Framework docs: