mcp-server-if 0.1.0__tar.gz

mcp_server_if-0.1.0/.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Build artifacts (but not deps/ - those are submodules)
+src/mcp_server_if/bin/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# OS
+.DS_Store
+Thumbs.db

mcp_server_if-0.1.0/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.

mcp_server_if-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,174 @@
+# 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/deps/glulxe/.git

@@ -0,0 +1 @@
+gitdir: ../../.git/modules/deps/glulxe

mcp_server_if-0.1.0/deps/glulxe/.gitignore

@@ -0,0 +1,2 @@
+*.o
+glulxe

mcp_server_if-0.1.0/deps/glulxe/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 1999-2023, Andrew Plotkin
+
+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.

mcp_server_if-0.1.0/deps/glulxe/Makefile

@@ -0,0 +1,75 @@
+# Unix Makefile for Glulxe.
+
+# To use this, you must set three variables. GLKINCLUDEDIR must be the 
+# directory containing glk.h, glkstart.h, and the Make.library file.
+# GLKLIBDIR must be the directory containing the library.a file.
+# And GLKMAKEFILE must be the name of the Make.library file. Two
+# sets of values appear below; uncomment one of them and change the
+# directories appropriately.
+
+GLKINCLUDEDIR = ../cheapglk
+GLKLIBDIR = ../cheapglk
+GLKMAKEFILE = Make.cheapglk
+
+#GLKINCLUDEDIR = ../glkterm
+#GLKLIBDIR = ../glkterm
+#GLKMAKEFILE = Make.glkterm
+
+#GLKINCLUDEDIR = ../xglk
+#GLKLIBDIR = ../xglk
+#GLKMAKEFILE = Make.xglk
+
+#GLKINCLUDEDIR = ../remglk
+#GLKLIBDIR = ../remglk
+#GLKMAKEFILE = Make.remglk
+
+#GLKINCLUDEDIR = ../gtkglk/src
+#GLKLIBDIR = ../gtkglk
+#GLKMAKEFILE = ../Make.gtkglk
+
+# Also set an appropriate OS config in OPTIONS, below.
+#   -DOS_MAC for MacOS
+#   -DOS_WINDOWS for Windows
+#   -DOS_UNIX for Unix/Linux
+# For OS_UNIX, you probably also want to set a random number generator
+# option. These are unfortunately not very standardized across Unixes.
+# We recommend -DUNIX_RAND_GETRANDOM on Linux and -DUNIX_RAND_ARC4
+# on NetBSD.
+# (MacOS always uses ARC4, in case you were wondering.)
+
+# Pick a C compiler.
+CC = cc
+#CC = gcc
+
+OPTIONS = -g -Wall -Wmissing-prototypes -Wno-unused -DOS_MAC
+
+# Locate the libxml2 library. You only need these lines if you are using
+# the VM_DEBUGGER option. If so, uncomment these and set appropriately.
+#XMLLIB = -L/usr/local/lib -lxml2
+#XMLLIBINCLUDEDIR = -I/usr/local/include/libxml2
+
+include $(GLKINCLUDEDIR)/$(GLKMAKEFILE)
+
+CFLAGS = $(OPTIONS) -I$(GLKINCLUDEDIR) $(XMLLIBINCLUDEDIR)
+LIBS = -L$(GLKLIBDIR) $(GLKLIB) $(LINKLIBS) -lm $(XMLLIB)
+
+OBJS = main.o files.o vm.o exec.o funcs.o operand.o string.o glkop.o \
+  heap.o serial.o search.o accel.o float.o gestalt.o osdepend.o \
+  profile.o debugger.o
+
+all: glulxe
+
+glulxe: $(OBJS) unixstrt.o unixautosave.o
+	$(CC) $(OPTIONS) -o glulxe $(OBJS) unixstrt.o unixautosave.o $(LIBS)
+
+glulxdump: glulxdump.o
+	$(CC) -o glulxdump glulxdump.o
+
+$(OBJS) unixstrt.o unixautosave.o: glulxe.h unixstrt.h
+
+exec.o operand.o: opcodes.h
+gestalt.o: gestalt.h
+
+clean:
+	rm -f *~ *.o glulxe glulxdump profile-raw
+