README.md

Agentic Zork: MCP ReAct Agent

This project implements an autonomous AI agent to play classic text adventure games (like Zork or Lost Pig) using the Model Context Protocol (MCP) and the ReAct (Reason + Act) framework.

Designed to be robust and fault-tolerant for blind evaluations on smaller language models (like Qwen 2.5), this implementation focuses on stateful memory management, strict tool execution, and avoiding the dreaded "infinite loops" common in text adventures.

Core Architecture

The system is decoupled into two primary components to maximize stability and context-window efficiency:

1. The ReAct Agent (agent.py)

Mine acts as a "Hierarchical Agent Manager", orchestrating three internal personas to decide the next move:

• The Navigator: Focuses on movement and exploration using the map.
• The Interaction Specialist: Focuses on interacting with objects and solving puzzles.
• The Historian: Keeps track of the story, recent history, and prevents repetitive looping.

It utilizes a Chain-of-Thought scratchpad (THOUGHT:) to reason about the environment before committing to an action (TOOL: / ARGS:), which significantly reduces hallucinated commands.

2. The Stateful MCP Server (mcp_server.py)

Solves the inherent "statelessness" of LLMs by maintaining the game environment, tracking historical moves, and mapping the world. It acts as the bridge between the Jericho game engine and the agent, providing persistent state as MCP resources.

Available MCP Tools

The agent interacts with the game world exclusively through the following tools exposed by FastMCP:

• play_action: Executes a physical game command (e.g., "go north", "take lamp") and advances the game state.
• inventory: Checks the items currently held by the player.
• get_map: Returns a topological map of explored locations and their known exits.
• get_historian_summary: Returns a concise log of the last few actions and their corresponding observations to maintain narrative continuity.
• get_valid_actions: Queries the game engine for a list of physically valid interactive commands for the current room.
• get_room_context: Returns a highly structured breakdown of the current location, including previously tried actions and warnings about where the agent just came from to prevent backtracking.

Usage Instructions

1. Install Dependencies Ensure you have the required packages installed, including FastMCP, Jericho, and the HuggingFace Hub client.

pip install -r requirements.txt

2. Set up your Environment Copy .env.example to .env and add your HuggingFace token:

HF_TOKEN=your_token_here

3. Run the Agent You can run the agent locally using the provided runner script.

# Run on Zork 1 with example agent (default)
python run_agent.py

# Play a different game (e.g., lostpig) with verbose reasoning and a 50-step limit
python run_agent.py --agent . --game lostpig -v -n 50

# List all 57 available games
python run_agent.py --list-games