mcp-server-if CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCP server for playing interactive fiction games (Glulx and Z-machine). Enables AI assistants to play text adventure games (.ulx, .gblorb, .z3-.z8, .zblorb) via the Model Context Protocol. Uses compiled interpreters (glulxe for Glulx, bocfel for Z-code) with RemGlk as subprocesses, communicating via JSON (RemGlk protocol).

Common Commands

# Setup (clones submodules, installs deps, AND compiles glulxe+bocfel binaries)
# Requires both a C compiler (cc/gcc) and C++ compiler (c++/g++/clang++)
uv sync --group dev --reinstall-package mcp-server-if

# Run all unit tests
uv run pytest -v

# Run a single test file
uv run pytest tests/test_session.py -v

# Run a single test by name
uv run pytest -k "test_play_if_basic" -v

# Integration tests (require compiled glulxe + network)
uv run pytest -m integration -v

# Lint and format
uv run ruff check src/ tests/
uv run ruff format src/ tests/

# Type check
uv run pyright src/

# Build package (compiles glulxe from C source via hatch_build.py)
uv build

Important: uv sync compiles glulxe and bocfel into src/mcp_server_if/bin/ via the hatch build hook (editable install). The build hook skips compilation if binaries already exist; use --reinstall-package mcp-server-if to force recompilation. Bocfel requires a C++ compiler (g++/c++/clang++).

Architecture

MCP Server (FastMCP)
    └── server.py      — 6 MCP tools + journal management + interpreter routing
        └── session.py — GlulxSession: async subprocess ↔ RemGlk JSON protocol
            ├── glulxe binary (Glulx games, compiled from deps/glulxe + deps/remglk)
            └── bocfel binary (Z-code games, compiled from deps/garglk/terps/bocfel + deps/remglk)

config.py — Resolves paths (env vars → bundled binary → PATH) and validates config

Data flow per turn: server.play_if() → detects game format → selects interpreter (glulxe or bocfel) → GlulxSession.run_turn(command) → spawns interpreter subprocess → sends JSON input (RemGlk format) → reads JSON output → formats to Markdown text.