mcp-server-if 0.1.0__py3-none-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl

mcp_server_if/__init__.py

@@ -0,0 +1,12 @@
+"""MCP server for playing Glulx interactive fiction games."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .server import main
+
+try:
+    __version__ = version("mcp-server-if")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = ["__version__", "main"]

mcp_server_if/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for running as a module: python -m mcp_server_if"""
+
+from .server import main
+
+if __name__ == "__main__":
+    main()

mcp_server_if/config.py

@@ -0,0 +1,103 @@
+"""Configuration handling for mcp-server-if."""
+
+import os
+import shutil
+from pathlib import Path
+
+
+def get_games_dir() -> Path:
+    """Get the games directory from environment or default."""
+    env_dir = os.environ.get("IF_GAMES_DIR")
+    if env_dir:
+        return Path(env_dir)
+    return Path.home() / ".mcp-server-if" / "games"
+
+
+def get_bundled_glulxe() -> Path | None:
+    """Get the bundled glulxe binary path if it exists."""
+    package_dir = Path(__file__).parent
+    for name in ("glulxe", "glulxe.exe"):
+        bundled = package_dir / "bin" / name
+        if bundled.exists() and bundled.is_file():
+            return bundled
+    return None
+
+
+def get_glulxe_path() -> Path | None:
+    """Get the glulxe binary path from environment, bundled, or auto-detect."""
+    # 1. Check environment variable
+    env_path = os.environ.get("IF_GLULXE_PATH")
+    if env_path:
+        path = Path(env_path)
+        if path.exists() and path.is_file():
+            return path
+        return None
+
+    # 2. Check for bundled binary (installed with package)
+    bundled = get_bundled_glulxe()
+    if bundled:
+        return bundled
+
+    # 3. Try to find glulxe in PATH
+    glulxe_in_path = shutil.which("glulxe")
+    if glulxe_in_path:
+        return Path(glulxe_in_path)
+
+    # 4. Check common locations
+    common_paths = [
+        Path.home() / ".local" / "bin" / "glulxe",
+        Path("/usr/local/bin/glulxe"),
+        Path("/usr/bin/glulxe"),
+    ]
+
+    for path in common_paths:
+        if path.exists() and path.is_file():
+            return path
+
+    return None
+
+
+def _get_require_journal() -> bool:
+    """Check if journal mode is enabled."""
+    return os.environ.get("IF_REQUIRE_JOURNAL", "").lower() in ("1", "true", "yes")
+
+
+class Config:
+    """Server configuration."""
+
+    def __init__(
+        self,
+        games_dir: Path | None = None,
+        glulxe_path: Path | None = None,
+        require_journal: bool | None = None,
+    ):
+        self.games_dir = games_dir or get_games_dir()
+        self.glulxe_path: Path | None = glulxe_path or get_glulxe_path()
+        self._require_journal = require_journal if require_journal is not None else _get_require_journal()
+
+    @property
+    def require_journal(self) -> bool:
+        return self._require_journal
+
+    def ensure_games_dir(self) -> None:
+        """Ensure the games directory exists."""
+        self.games_dir.mkdir(parents=True, exist_ok=True)
+
+    def validate(self) -> list[str]:
+        """Validate configuration. Returns list of errors."""
+        errors = []
+        if not self.glulxe_path:
+            checked = [
+                "IF_GLULXE_PATH env var",
+                f"bundled binary at {Path(__file__).parent / 'bin'}",
+                "glulxe in PATH",
+            ]
+            errors.append(
+                "glulxe binary not found. Checked:\n"
+                + "\n".join(f"  - {loc}" for loc in checked)
+                + "\n\nFor development: run 'uv sync --reinstall-package mcp-server-if' to compile from source."
+                + "\nFor production: install the wheel from PyPI."
+            )
+        elif not self.glulxe_path.exists():
+            errors.append(f"glulxe binary not found at: {self.glulxe_path}")
+        return errors

mcp_server_if/server.py

@@ -0,0 +1,412 @@
+"""MCP server for interactive fiction games."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import TypedDict
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+from .config import Config
+from .session import GlulxSession, detect_game_format, find_game_file
+
+
+class JournalEntry(TypedDict):
+    turn: int
+    timestamp: str
+    command: str
+    output: str
+    reflection: str
+
+
+# IF Archive base URL
+IF_ARCHIVE_BASE = "https://ifarchive.org/if-archive/games/glulx"
+
+# Global config - set at startup
+_config: Config | None = None
+
+
+def get_config() -> Config:
+    """Get the server configuration."""
+    global _config
+    if _config is None:
+        _config = Config()
+    return _config
+
+
+# Initialize FastMCP server
+mcp = FastMCP("interactive-fiction")
+
+
+def _get_game_dir(game: str) -> Path:
+    """Get the directory for a game by name."""
+    safe_name = re.sub(r"[^a-zA-Z0-9_-]", "_", game.lower())
+    return get_config().games_dir / safe_name
+
+
+def _append_journal(game_dir: Path, turn: int, command: str, output: str, reflection: str) -> None:
+    """Append a complete journal entry with command, output, and reflection."""
+    journal_file = game_dir / "journal.jsonl"
+
+    entry: JournalEntry = {
+        "turn": turn,
+        "timestamp": datetime.now().isoformat(),
+        "command": command,
+        "output": output,
+        "reflection": reflection.strip(),
+    }
+
+    with open(journal_file, "a") as f:
+        f.write(json.dumps(entry) + "\n")
+
+
+def _load_journal(game_dir: Path) -> list[JournalEntry]:
+    """Load journal entries from JSONL file."""
+    journal_file = game_dir / "journal.jsonl"
+    if not journal_file.exists():
+        return []
+
+    entries = []
+    for line in journal_file.read_text().strip().split("\n"):
+        if line:
+            try:
+                entries.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+    return entries
+
+
+def _format_journal_entry(entry: JournalEntry, include_output: bool = True) -> list[str]:
+    """Format a single journal entry as lines of text."""
+    lines = []
+    timestamp = entry["timestamp"][:16].replace("T", " ")
+    lines.append(f"## Turn {entry['turn']} ({timestamp})")
+    lines.append("")
+    lines.append(f"**Command:** `{entry['command']}`")
+    lines.append("")
+    if include_output:
+        lines.append("**Game output:**")
+        for output_line in entry["output"].split("\n"):
+            lines.append(f"> {output_line}")
+        lines.append("")
+    lines.append(f"**Reflection:** {entry['reflection']}")
+    lines.append("")
+    lines.append("---")
+    lines.append("")
+    return lines
+
+
+def _list_available_games() -> list[str]:
+    """List available game names."""
+    games_dir = get_config().games_dir
+    if not games_dir.exists():
+        return []
+    games = []
+    for game_dir in games_dir.iterdir():
+        if game_dir.is_dir() and find_game_file(game_dir):
+            games.append(game_dir.name)
+    return sorted(games)
+
+
+@mcp.tool()
+async def play_if(game: str, command: str = "", journal: str = "") -> str:
+    """Play a turn of interactive fiction.
+
+    Args:
+        game: Name of the game to play
+        command: Command to send to the game (empty to start/show current state)
+        journal: Reflection on the previous turn (required after first turn if journaling enabled)
+    """
+    config = get_config()
+    game = game.strip()
+    journal = journal.strip()
+
+    if not game:
+        return "Error: game name required"
+
+    # Validate glulxe
+    errors = config.validate()
+    if errors:
+        return "Error: " + "; ".join(errors)
+    assert config.glulxe_path is not None
+
+    game_dir = _get_game_dir(game)
+    if not find_game_file(game_dir):
+        available = _list_available_games()
+        msg = f"Game '{game}' not found."
+        if available:
+            msg += f" Available: {', '.join(available)}"
+        msg += "\nUse download_game to get new games."
+        return msg
+
+    session = GlulxSession(game_dir, config.glulxe_path)
+
+    # Warn about save/restore commands
+    if command.strip().lower() in ("save", "restore"):
+        return (
+            f"Warning: The '{command.strip()}' command triggers an in-game file dialog that isn't supported.\n\n"
+            "Your game state is automatically saved after every turn (autosave).\n"
+            "To start fresh, use reset_game."
+        )
+
+    # Handle journaling if enabled
+    if config.require_journal and session.has_state() and command.strip():
+        metadata = session.load_metadata()
+        prev_command = metadata.get("last_command")
+
+        if prev_command is not None:
+            if not journal:
+                return (
+                    "Journal entry required. Reflect on the previous turn before continuing.\n\n"
+                    'Use: play_if(game, command, journal="Your reflection on what happened...")'
+                )
+            word_count = len(journal.split())
+            if word_count < 100:
+                return (
+                    f"Journal entry too short ({word_count} words). Minimum 100 words required.\n\n"
+                    "Take your time. Reflect on what happened, what it means, how it connects to the story."
+                )
+            # Record the journal entry
+            turn = metadata.get("turn", 1)
+            prev_output = metadata.get("last_output", "")
+            _append_journal(game_dir, turn, prev_command, prev_output, journal)
+
+    try:
+        cmd = command if command.strip() else None
+        if session.has_state() and not command.strip():
+            cmd = ""
+
+        output, metadata = await session.run_turn(cmd)
+
+        # Track turn and store for next journal entry
+        turn = metadata.get("turn", 0) + 1
+        metadata["turn"] = turn
+        metadata["last_command"] = command
+        metadata["last_output"] = output
+        session.save_metadata(metadata)
+
+        # Add status info
+        status = []
+        if metadata.get("input_type") == "char":
+            status.append("Input: single keypress")
+        elif metadata.get("input_window") is None:
+            status.append("Game ended or waiting for special input")
+
+        if status:
+            output += "\n\n[" + ", ".join(status) + "]"
+
+        return output
+
+    except Exception as e:
+        return f"Error: {e}"
+
+
+@mcp.tool()
+async def list_games() -> str:
+    """List available interactive fiction games."""
+    games = _list_available_games()
+
+    if not games:
+        return (
+            "No games installed.\n\n"
+            "Use download_game to get games from the IF Archive.\n"
+            'Example: download_game(name="advent", url="advent.ulx")'
+        )
+
+    lines = ["**Available games:**", ""]
+    config = get_config()
+    for game in games:
+        game_dir = _get_game_dir(game)
+        session = GlulxSession(game_dir, config.glulxe_path)
+        status = "has saved state" if session.has_state() else "no saved state"
+        lines.append(f"- {game} ({status})")
+
+    lines.append("")
+    lines.append("Use play_if(game, command) to play.")
+
+    return "\n".join(lines)
+
+
+@mcp.tool()
+async def download_game(name: str, url: str) -> str:
+    """Download an interactive fiction game (.ulx or .gblorb).
+
+    Args:
+        name: Local name for the game
+        url: Full URL or just filename for IF Archive games (e.g., 'advent.ulx')
+    """
+    config = get_config()
+    name = name.strip()
+    url = url.strip()
+
+    if not name:
+        return "Error: name required (used as local game name)"
+
+    if not url:
+        return "Error: url required (full URL or IF Archive filename like 'advent.ulx')"
+
+    # If URL is just a filename, construct IF Archive URL
+    if not url.startswith("http"):
+        url = f"{IF_ARCHIVE_BASE}/{url}"
+
+    game_dir = _get_game_dir(name)
+
+    try:
+        config.ensure_games_dir()
+        game_dir.mkdir(parents=True, exist_ok=True)
+
+        async with httpx.AsyncClient(follow_redirects=True, timeout=60.0) as client:
+            response = await client.get(url)
+            response.raise_for_status()
+            content = response.content
+
+        game_format = detect_game_format(content)
+        if not game_format:
+            return f"Error: Downloaded file is not a valid Glulx or Blorb game (magic bytes: {content[:12]!r})"
+
+        game_file = game_dir / f"game.{game_format}"
+        game_file.write_bytes(content)
+
+        size_kb = len(content) / 1024
+        return f'Downloaded \'{name}\' ({size_kb:.1f} KB)\nUse play_if("{name}", "") to start playing.'
+
+    except httpx.HTTPStatusError as e:
+        return f"Download failed: HTTP {e.response.status_code}"
+    except Exception as e:
+        return f"Download failed: {e}"
+
+
+@mcp.tool()
+async def reset_game(game: str) -> str:
+    """Reset an interactive fiction game to start fresh.
+
+    Args:
+        game: Name of the game to reset
+    """
+    config = get_config()
+    game = game.strip()
+
+    if not game:
+        return "Error: game name required"
+
+    game_dir = _get_game_dir(game)
+    if not find_game_file(game_dir):
+        return f"Game '{game}' not found."
+
+    session = GlulxSession(game_dir, config.glulxe_path)
+    session.clear_state()
+
+    return f"Game '{game}' reset. Journal preserved. Use play_if to start fresh."
+
+
+@mcp.tool()
+async def read_journal(game: str, recent: int = 0) -> str:
+    """Read the playthrough journal for an interactive fiction game.
+
+    Args:
+        game: Name of the game
+        recent: Only show last N entries (0 = all)
+    """
+    game = game.strip()
+
+    if not game:
+        return "Error: game name required"
+
+    game_dir = _get_game_dir(game)
+    entries = _load_journal(game_dir)
+
+    if not entries:
+        return f"No journal yet for '{game}'."
+
+    if recent > 0:
+        entries = entries[-recent:]
+
+    lines = [f"# {game} Playthrough Journal", ""]
+    for entry in entries:
+        lines.extend(_format_journal_entry(entry, include_output=True))
+
+    return "\n".join(lines)
+
+
+@mcp.tool()
+async def search_journal(game: str, query: str) -> str:
+    """Search the playthrough journal for keywords or patterns.
+
+    Args:
+        game: Name of the game
+        query: Search query
+    """
+    game = game.strip()
+    query = query.strip().lower()
+
+    if not game:
+        return "Error: game name required"
+
+    if not query:
+        return "Error: search query required"
+
+    game_dir = _get_game_dir(game)
+    entries = _load_journal(game_dir)
+
+    if not entries:
+        return f"No journal yet for '{game}'."
+
+    matches = [e for e in entries if query in e.get("reflection", "").lower() or query in e.get("output", "").lower()]
+
+    if not matches:
+        return f"No matches for '{query}' in {game} journal."
+
+    lines = [f"# Found {len(matches)} match(es) for '{query}'", ""]
+    for entry in matches:
+        lines.extend(_format_journal_entry(entry, include_output=False))
+
+    return "\n".join(lines)
+
+
+def main():
+    """Main entry point for the MCP server."""
+    parser = argparse.ArgumentParser(description="MCP server for interactive fiction games")
+    parser.add_argument(
+        "--games-dir",
+        type=Path,
+        help="Directory to store games (default: ~/.mcp-server-if/games or IF_GAMES_DIR)",
+    )
+    parser.add_argument(
+        "--glulxe-path",
+        type=Path,
+        help="Path to glulxe binary (default: auto-detect or IF_GLULXE_PATH)",
+    )
+    parser.add_argument(
+        "--require-journal",
+        action="store_true",
+        help="Require journal reflections between turns",
+    )
+
+    args = parser.parse_args()
+
+    # Set global config
+    global _config
+    _config = Config(
+        games_dir=args.games_dir,
+        glulxe_path=args.glulxe_path,
+        require_journal=args.require_journal,
+    )
+
+    # Validate config
+    errors = _config.validate()
+    if errors:
+        for error in errors:
+            print(f"Warning: {error}", file=sys.stderr)
+
+    # Run the server
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

mcp_server_if/session.py

@@ -0,0 +1,299 @@
+"""Glulx game session management with RemGlk protocol."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+
+# Magic bytes for game formats
+GLULX_MAGIC = b"Glul"  # Glulx game file
+BLORB_MAGIC = b"FORM"  # Blorb container (FORM....IFRS)
+
+
+def detect_game_format(content: bytes) -> str | None:
+    """Detect game format from magic bytes. Returns 'ulx', 'gblorb', or None."""
+    if content.startswith(GLULX_MAGIC):
+        return "ulx"
+    if content.startswith(BLORB_MAGIC) and len(content) > 12 and content[8:12] == b"IFRS":
+        return "gblorb"
+    return None
+
+
+def find_game_file(game_dir: Path) -> Path | None:
+    """Find the game file in a game directory (.ulx or .gblorb)."""
+    for ext in ("ulx", "gblorb"):
+        game_file = game_dir / f"game.{ext}"
+        if game_file.exists():
+            return game_file
+    return None
+
+
+class GlulxSession:
+    """Manages a glulxe session with RemGlk JSON protocol."""
+
+    def __init__(self, game_dir: Path, glulxe_path: Path | None = None):
+        self.game_dir = game_dir
+        self.glulxe_path = glulxe_path
+        self.game_file = find_game_file(game_dir)
+        self.state_dir = game_dir / "state"
+        self.metadata_file = game_dir / "metadata.json"
+
+    def has_state(self) -> bool:
+        """Check if saved state exists."""
+        return (self.state_dir / "autosave.json").exists()
+
+    def load_metadata(self) -> dict:
+        """Load session metadata."""
+        if self.metadata_file.exists():
+            try:
+                return json.loads(self.metadata_file.read_text())
+            except (OSError, json.JSONDecodeError):
+                pass
+        return {"gen": 0, "windows": [], "input_window": None, "input_type": "line"}
+
+    def save_metadata(self, metadata: dict) -> None:
+        """Save session metadata."""
+        self.metadata_file.write_text(json.dumps(metadata, indent=2))
+
+    def clear_state(self) -> None:
+        """Clear saved game state."""
+        if self.state_dir.exists():
+            for f in self.state_dir.iterdir():
+                f.unlink()
+        if self.metadata_file.exists():
+            self.metadata_file.unlink()
+
+    async def run_turn(self, command: str | None = None) -> tuple[str, dict]:
+        """
+        Run a single turn of the game.
+
+        Args:
+            command: The command to send (None for initial turn)
+
+        Returns:
+            Tuple of (formatted output, updated metadata)
+        """
+        if not self.game_file or not self.game_file.exists():
+            raise FileNotFoundError(f"Game file not found in: {self.game_dir}")
+
+        if not self.glulxe_path or not self.glulxe_path.exists():
+            raise FileNotFoundError(
+                f"glulxe binary not found: {self.glulxe_path}\n"
+                "Set IF_GLULXE_PATH or see README.md for build instructions."
+            )
+
+        # Ensure state directory exists
+        self.state_dir.mkdir(parents=True, exist_ok=True)
+
+        # Load metadata
+        metadata = self.load_metadata()
+
+        # Build glulxe command
+        cmd = [
+            str(self.glulxe_path),
+            "-singleturn",
+            "-fm",
+            "--autosave",
+            "--autodir",
+            str(self.state_dir),
+        ]
+
+        if self.has_state():
+            cmd.append("--autorestore")
+
+        cmd.append(str(self.game_file))
+
+        # Build input JSON
+        if command is None or not self.has_state():
+            # Initial turn
+            input_json = {"type": "init", "gen": 0, "metrics": {"width": 80, "height": 24}, "support": []}
+        else:
+            # Subsequent turn
+            input_type = metadata.get("input_type", "line")
+            input_window = metadata.get("input_window")
+
+            if input_window is None:
+                raise ValueError("No input window available - game may have ended")
+
+            if input_type == "char":
+                # Character input - send single char or RemGlk special key name.
+                # RemGlk special keys: return, escape, tab, left, right, up, down,
+                # pageup, pagedown, home, end, func1-func12.
+                # Regular chars (including space) are sent as literal single chars.
+                if not command:
+                    key = " "
+                elif command in ("\n", "\r") or command.strip().lower() in ("enter", "return"):
+                    key = "return"
+                elif len(command) == 1:
+                    key = command.lower()
+                else:
+                    key = command.strip().lower()
+                input_json = {"type": "char", "gen": metadata["gen"], "window": input_window, "value": key}
+            else:
+                # Line input
+                input_json = {"type": "line", "gen": metadata["gen"], "window": input_window, "value": command}
+
+        # Run glulxe
+        proc = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+
+        input_bytes = (json.dumps(input_json) + "\n").encode()
+        stdout, stderr = await proc.communicate(input_bytes)
+
+        if proc.returncode != 0:
+            error = stderr.decode("utf-8", errors="replace").strip()
+            stdout_preview = stdout.decode("utf-8", errors="replace")[:500]
+            raise RuntimeError(f"glulxe failed (exit {proc.returncode}): {error}\nstdout: {stdout_preview}")
+
+        # Parse output - RemGlk sends JSON terminated by blank line
+        output_text = stdout.decode("utf-8", errors="replace")
+        output_lines = output_text.strip().split("\n\n")
+
+        if not output_lines:
+            raise RuntimeError("No output from glulxe")
+
+        # Parse the JSON output
+        try:
+            output = json.loads(output_lines[0])
+        except json.JSONDecodeError as e:
+            raise RuntimeError(f"Failed to parse glulxe output: {e}\nOutput: {output_text[:500]}") from e
+
+        # Update metadata from output
+        if "gen" in output:
+            metadata["gen"] = output["gen"]
+
+        # Update window list if present
+        if "windows" in output:
+            metadata["windows"] = output["windows"]
+
+        # Update input expectations
+        if output.get("input"):
+            inp = output["input"][0]
+            metadata["input_window"] = inp.get("id")
+            metadata["input_type"] = inp.get("type", "line")
+            metadata["input_gen"] = inp.get("gen", metadata["gen"])
+        else:
+            metadata["input_window"] = None
+            metadata["input_type"] = None
+
+        # Handle special input (file dialogs)
+        if "specialinput" in output:
+            special = output["specialinput"]
+            if special.get("type") == "fileref_prompt":
+                metadata["pending_fileref"] = True
+
+        self.save_metadata(metadata)
+
+        # Format output
+        formatted = self._format_output(output, metadata.get("windows", []))
+
+        return formatted, metadata
+
+    def _format_output(self, output: dict, windows: list) -> str:
+        """Format RemGlk output as readable text."""
+        result = []
+
+        # Build window type map
+        window_types = {}
+        for w in windows:
+            window_types[w["id"]] = w.get("type", "buffer")
+
+        # Process content
+        content = output.get("content", [])
+        grid_content = []
+        buffer_content = []
+
+        for item in content:
+            win_id = item.get("id")
+            win_type = window_types.get(win_id, "buffer")
+
+            if win_type == "grid":
+                # Status bar - extract lines
+                for line in item.get("lines", []):
+                    text = self._extract_text(line.get("content", []))
+                    if text.strip():
+                        grid_content.append(text)
+            else:
+                # Buffer window - extract text
+                if item.get("clear"):
+                    buffer_content = []  # Clear previous content
+
+                for text_item in item.get("text", []):
+                    if not text_item:
+                        buffer_content.append("")
+                    elif text_item.get("append"):
+                        if buffer_content:
+                            buffer_content[-1] += self._extract_text(text_item.get("content", []))
+                        else:
+                            buffer_content.append(self._extract_text(text_item.get("content", [])))
+                    else:
+                        buffer_content.append(self._extract_text(text_item.get("content", [])))
+
+        # Format output
+        if grid_content:
+            result.append("=== " + " | ".join(grid_content) + " ===")
+            result.append("")
+
+        if buffer_content:
+            result.extend(buffer_content)
+
+        # Note if character input expected
+        if output.get("input") and output["input"][0].get("type") == "char":
+            result.append("")
+            result.append("[Waiting for keypress]")
+
+        return "\n".join(result)
+
+    def _extract_text(self, content: list) -> str:
+        """Extract text from RemGlk content array, preserving style info."""
+        if not content:
+            return ""
+
+        result = []
+        i = 0
+        while i < len(content):
+            item = content[i]
+            if isinstance(item, dict):
+                style = item.get("style", "normal")
+                text = item.get("text", "")
+                result.append(self._apply_style(style, text))
+                i += 1
+            elif isinstance(item, str):
+                style = item
+                if i + 1 < len(content) and isinstance(content[i + 1], str):
+                    text = content[i + 1]
+                    result.append(self._apply_style(style, text))
+                    i += 2
+                else:
+                    i += 1
+            else:
+                i += 1
+
+        return "".join(result)
+
+    def _apply_style(self, style: str, text: str) -> str:
+        """Apply markdown-style formatting based on Glulx style."""
+        if not text:
+            return ""
+
+        if style in ("user1", "user2"):
+            return f"[{text}]"
+        elif style == "emphasized":
+            return f"*{text}*"
+        elif style in ("header", "subheader", "alert"):
+            return f"**{text}**"
+        elif style == "preformatted":
+            return f"`{text}`"
+        elif style == "note":
+            return f"({text})"
+        elif style == "blockquote":
+            return f'"{text}"'
+        elif style == "input":
+            return f"> {text}"
+        else:
+            return text

mcp_server_if-0.1.0.dist-info/METADATA

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: mcp-server-if
+Version: 0.1.0
+Summary: MCP server for playing Glulx interactive fiction games
+Project-URL: Homepage, https://github.com/davidar/mcp-server-if
+Project-URL: Repository, https://github.com/davidar/mcp-server-if
+Project-URL: Issues, https://github.com/davidar/mcp-server-if/issues
+Author-email: David A Roberts <d@vidr.cc>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,glulx,interactive-fiction,mcp,text-adventure
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment :: Role-Playing
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# mcp-server-if
+
+An MCP (Model Context Protocol) server for playing Glulx interactive fiction games. Enables AI assistants like Claude to play text adventure games through a standardized interface.
+
+## Features
+
+- Play Glulx (.ulx) and Blorb (.gblorb) interactive fiction games
+- Automatic game state persistence (save/restore between sessions)
+- Download games directly from the IF Archive
+- Optional journaling mode for reflective playthroughs
+- Works with Claude Desktop, Claude Code, and other MCP clients
+- Bundled glulxe interpreter (no manual compilation required)
+
+## Installation
+
+```bash
+# Using uvx (recommended)
+uvx mcp-server-if
+
+# Or install with pip
+pip install mcp-server-if
+```
+
+The package includes a pre-compiled `glulxe` binary. No additional setup required.
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `IF_GAMES_DIR` | Directory to store games | `~/.mcp-server-if/games` |
+| `IF_GLULXE_PATH` | Override path to glulxe binary | Bundled binary |
+| `IF_REQUIRE_JOURNAL` | Require journal reflections | `false` |
+
+### Command Line Arguments
+
+```bash
+mcp-server-if --help
+
+Options:
+  --games-dir PATH       Directory to store games
+  --glulxe-path PATH     Path to glulxe binary (overrides bundled)
+  --require-journal      Require journal reflections between turns
+```
+
+## Usage with Claude Desktop
+
+Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "interactive-fiction": {
+      "command": "uvx",
+      "args": ["mcp-server-if"]
+    }
+  }
+}
+```
+
+## Usage with Claude Code
+
+```bash
+claude mcp add interactive-fiction -- uvx mcp-server-if
+```
+
+## Available Tools
+
+### `play_if`
+Play a turn of interactive fiction.
+
+```
+play_if(game="zork", command="go north")
+play_if(game="zork", command="", journal="...reflection...")  # with journaling
+```
+
+### `list_games`
+List available games and their save state status.
+
+### `download_game`
+Download a game from the IF Archive or any URL.
+
+```
+download_game(name="advent", url="advent.ulx")
+download_game(name="bronze", url="https://example.com/Bronze.gblorb")
+```
+
+### `reset_game`
+Reset a game to start fresh (clears save state, preserves journal).
+
+### `read_journal`
+Read the playthrough journal for a game.
+
+```
+read_journal(game="zork", recent=10)  # last 10 entries
+```
+
+### `search_journal`
+Search journal entries by keyword.
+
+```
+search_journal(game="zork", query="treasure")
+```
+
+## Supported Game Formats
+
+- `.ulx` - Raw Glulx game files
+- `.gblorb` - Blorb containers with Glulx games (may include graphics/sound)
+
+Find games at the [IF Archive](https://ifarchive.org/indexes/if-archive/games/glulx/).
+
+## Journaling Mode
+
+Enable with `--require-journal` or `IF_REQUIRE_JOURNAL=true`. In this mode:
+
+1. After playing your first command, subsequent turns require a journal entry
+2. Journal entries must be at least 100 words
+3. Entries are saved to `{game}/journal.jsonl`
+4. Use `read_journal` and `search_journal` to review your playthrough
+
+This encourages thoughtful, reflective gameplay rather than rushing through.
+
+## How It Works
+
+1. Games are stored in `~/.mcp-server-if/games/{name}/`
+2. Each game directory contains:
+   - `game.ulx` or `game.gblorb` - the game file
+   - `state/` - autosave data (persists between sessions)
+   - `metadata.json` - session metadata
+   - `journal.jsonl` - playthrough journal (if enabled)
+
+3. The server uses glulxe's RemGlk mode for JSON-based I/O
+4. Game state is automatically saved after each turn
+
+## Building from Source
+
+If installing from source (not from PyPI), glulxe will be compiled during installation. This requires:
+
+- C compiler (gcc or clang)
+- make
+- git (for submodules)
+
+```bash
+git clone --recursive https://github.com/davidar/mcp-server-if.git
+cd mcp-server-if
+pip install .
+```
+
+## Troubleshooting
+
+### "glulxe binary not found"
+
+This shouldn't happen with pip/uvx installs. If it does:
+- Try reinstalling: `pip install --force-reinstall mcp-server-if`
+- Or set `IF_GLULXE_PATH` to a manually installed glulxe
+
+### "Game file not found"
+
+Use `list_games` to see available games, or `download_game` to get new ones.
+
+### Save/restore commands don't work
+
+In-game save/restore triggers file dialogs that aren't supported. Use the automatic autosave system instead - your game state persists between sessions automatically.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Credits
+
+- [glulxe](https://github.com/erkyrath/glulxe) - The Glulx VM interpreter by Andrew Plotkin
+- [RemGlk](https://github.com/erkyrath/remglk) - Remote Glk library for JSON I/O
+- [MCP](https://modelcontextprotocol.io/) - Model Context Protocol by Anthropic

mcp_server_if-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+mcp_server_if/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcp_server_if/__main__.py,sha256=HEiagMZ-9v0Ugdszyh4nC7R-esMTX8Bk7vu3ox3McLI,132
+mcp_server_if/__init__.py,sha256=9CHcB-6L566M9Gy_R5tzYWp8gXK1GJ5DhINUiJKK28Y,289
+mcp_server_if/server.py,sha256=lYuWCCmseoRpkiP4zCnd9lk-wZy6AhadfgmMq9Ly2-o,12100
+mcp_server_if/config.py,sha256=MXDDzHPv6vhTEAj9x_Zqn4Ys4rfl_LDNgVfRD0wc1Y4,3239
+mcp_server_if/session.py,sha256=VXamjN85XezxfCuhmfoBO82t78q9YPD_JEWw7vSIHcE,10663
+mcp_server_if/bin/glulxe,sha256=KcFj63eKbRuQvcU1zd2NMP1-S9HAC9haYA6xpsFv-VI,812736
+mcp_server_if-0.1.0.dist-info/WHEEL,sha256=tQPINDmzfU0y7pfVJjQUrngsc-O9y-WskGTTjmtBvXg,145
+mcp_server_if-0.1.0.dist-info/entry_points.txt,sha256=Fh-zkWrbgDBe_2UzNjRKYR6vw_kc-q5GnIojwdFS3vk,53
+mcp_server_if-0.1.0.dist-info/METADATA,sha256=S9cnguCgOVHR1GPMDJJWW5IK6zq70cCT-c2R1IpKDRw,5861
+mcp_server_if-0.1.0.dist-info/RECORD,,
+mcp_server_if-0.1.0.dist-info/licenses/LICENSE,sha256=BXxcwr8hEiK-byLXh_amNTuuES4DlNmCmLmQMlVptNY,1072

mcp_server_if-0.1.0.dist-info/WHEEL

@@ -0,0 +1,6 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: false
+Tag: py3-none-manylinux_2_27_aarch64
+Tag: py3-none-manylinux_2_28_aarch64
+

mcp_server_if-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-server-if = mcp_server_if:main

mcp_server_if-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 David A Roberts
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.