Full project upload

.env.example

@@ -0,0 +1,14 @@
+# Hugging Face Hub Configuration
+HF_TOKEN=your_huggingface_token_here
+
+# Model Configuration
+# Default model for all modes (react, function, mcp)
+HF_MODEL=meta-llama/Llama-3.2-3B-Instruct
+
+# Alternative models to try:
+# HF_MODEL=google/gemma-2-2b-it
+# HF_MODEL=Qwen/Qwen2.5-7B-Instruct
+
+# Optional API Keys (if using other providers)
+# ANTHROPIC_API_KEY=your_anthropic_key_here
+# OPENAI_API_KEY=your_openai_key_here

.gitignore

@@ -0,0 +1,151 @@
+master.zip
+.github/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+._*
+.Spotlight-V100
+.Trashes
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Game files
+z-machine-games-master/
+*.z3
+*.z4
+*.z5
+*.z8
+
+# Temp files
+.mcp_config_temp.json

README.md

@@ -10,8 +10,206 @@ pinned: false
 license: mit
 ---
 
-# Playing Zork has never been so boring
+# Text Adventure LLM Agent Project
 
-In this assignment, you will build an AI Agent and an MCP server to play text adventure games like Zork.
+Build AI agents to play classic text adventure games (Zork, Colossal Cave, Enchanter, etc.) using the Model Context Protocol (MCP) and HuggingFace models.
 
-See the instructions below to get started!
+## Overview
+
+This project provides:
+
+1. **MCP Server** - Exposes text adventure games as MCP tools using FastMCP
+2. **ReAct Agent** - An agent that uses MCP tools to play games with reasoning
+3. **Templates** - Starter code for students to implement their own solutions
+4. **57 Games** - Zork trilogy, Infocom classics, and many more Z-machine games
+
+## Architecture
+
+```
++-------------------+     MCP Protocol     +------------------+
+|                   | <------------------> |                  |
+|   ReAct Agent     |    (tool calls)      |   MCP Server     |
+|   (FastMCP Client)|                      |   (FastMCP)      |
+|                   |                      |                  |
++-------------------+                      +------------------+
+        |                                           |
+        | LLM API                                   | Game API
+        v                                           v
++-------------------+                      +------------------+
+|   HuggingFace     |                      |   Text Adventure |
+|   Inference API   |                      |   (Jericho)      |
++-------------------+                      +------------------+
+```
+
+## Quick Start
+
+### 1. Setup
+
+```bash
+# Create virtual environment (using uv recommended)
+uv venv
+source .venv/bin/activate
+
+# Install dependencies
+uv pip install -r requirements.txt
+
+# Configure environment
+cp .env.example .env
+# Edit .env and add your HuggingFace token (HF_TOKEN)
+```
+
+Get your HuggingFace token at: https://huggingface.co/settings/tokens
+
+### 2. Run an Agent
+
+```bash
+# MCP mode (recommended) - uses FastMCP Client
+python run_agent.py --mode mcp
+
+# Basic ReAct agent (direct game interaction)
+python run_agent.py --mode react
+
+# Function calling mode
+python run_agent.py --mode function --simple
+```
+
+## Project Structure
+
+```
+.
++-- run_agent.py              # Unified agent runner
++-- mcp_server/
+|   +-- zork_server.py        # Full MCP server with all tools
++-- agents/
+|   +-- base_agent.py         # Abstract base class
+|   +-- react_agent.py        # Basic ReAct agent (no MCP)
+|   +-- mcp_react_agent.py    # MCP-enabled ReAct agent
++-- templates/                # Student templates
+|   +-- README.md             # Assignment instructions
+|   +-- mcp_server_template.py    # MCP server starter
+|   +-- react_agent_template.py   # Agent starter
++-- function_calling/         # Alternative: function calling
+|   +-- controller.py
+|   +-- simple_controller.py
+|   +-- tools.py
++-- games/
+|   +-- zork_env.py           # Jericho wrapper
++-- z-machine-games-master/   # Game files
+```
+
+## Agent Modes
+
+| Mode | Description | Command |
+|------|-------------|---------|
+| `mcp` | MCP ReAct agent (FastMCP Client) | `--mode mcp` |
+| `react` | Basic ReAct (direct game) | `--mode react` |
+| `function` | Function calling (API) | `--mode function` |
+| `function --simple` | Function calling (text) | `--mode function --simple` |
+
+### Examples
+
+```bash
+# Run MCP agent with verbose output
+python run_agent.py --mode mcp -v
+
+# Run with different model
+python run_agent.py --mode mcp --model google/gemma-2-2b-it
+
+# Limit steps
+python run_agent.py --mode mcp -n 50
+
+# Play different games
+python run_agent.py --mode mcp --game zork2
+python run_agent.py --mode mcp --game advent     # Colossal Cave Adventure
+python run_agent.py --mode mcp --game enchanter  # Infocom classic
+python run_agent.py --mode mcp --game hhgg       # Hitchhiker's Guide
+
+# List all 57 available games
+python run_agent.py --list-games
+```
+
+## MCP Server Tools
+
+The MCP server exposes these tools:
+
+| Tool | Description |
+|------|-------------|
+| `play_action(action)` | Execute a game command (north, take lamp, etc.) |
+| `memory()` | Get current state (location, score, history) |
+| `get_map()` | View explored locations and connections |
+| `inventory()` | Check items you're carrying |
+| `valid_actions()` | Get command hints |
+| `reset_game(game)` | Start over or switch games |
+| `list_games()` | See all 57 available games |
+| `hint()` | Get contextual hints |
+
+### Testing the MCP Server
+
+```bash
+# Run server directly (stdio transport) - default game is zork1
+python mcp_server/zork_server.py
+
+# Run with a specific game
+GAME=advent python mcp_server/zork_server.py
+
+# Use MCP Inspector for interactive testing
+npx @modelcontextprotocol/inspector python mcp_server/zork_server.py
+
+# Use FastMCP dev mode
+fastmcp dev mcp_server/zork_server.py
+```
+
+## Student Assignment
+
+See [templates/README.md](templates/README.md) for the assignment.
+
+Students implement:
+1. **MCP Server** (`mcp_server_template.py`) - Expose game functionality as MCP tools
+2. **ReAct Agent** (`react_agent_template.py`) - Play text adventures using MCP
+
+## Configuration
+
+### Environment Variables
+
+Create `.env` from `.env.example`:
+
+```bash
+# Required: HuggingFace token
+HF_TOKEN=hf_your_token_here
+
+# Optional: Model override (default: meta-llama/Llama-3.2-3B-Instruct)
+HF_MODEL=meta-llama/Llama-3.2-3B-Instruct
+```
+
+### Recommended Models
+
+| Model | Notes |
+|-------|-------|
+| `meta-llama/Llama-3.2-3B-Instruct` | Default, good balance |
+| `google/gemma-2-2b-it` | Smaller, faster |
+| `Qwen/Qwen2.5-7B-Instruct` | Good instruction following |
+
+## Evaluation
+
+Run the evaluator to test agent performance:
+
+```bash
+python evaluate.py --mode mcp --games zork1 --runs 3
+```
+
+Metrics:
+- **Score**: Points earned in-game
+- **Score %**: Score / Max possible score
+- **Steps**: Number of actions taken
+- **Time**: Elapsed time
+
+## Resources
+
+- [FastMCP Documentation](https://gofastmcp.com/)
+- [MCP Protocol](https://modelcontextprotocol.io/)
+- [Jericho (Text Adventures)](https://github.com/microsoft/jericho)
+- [HuggingFace Inference API](https://huggingface.co/docs/huggingface_hub/guides/inference)
+
+## License
+
+MIT

SPACES_README.md

@@ -0,0 +1,17 @@
+---
+title: Agentic Zork
+emoji: "🎮"
+colorFrom: green
+colorTo: purple
+sdk: gradio
+sdk_version: 5.0.0
+app_file: app.py
+pinned: false
+license: mit
+---
+
+# Playing Zork has never been so boring
+
+In this assignment, you will build an AI Agent and an MCP server to play text adventure games like Zork.
+
+See the instructions below to get started!

agents/__init__.py

@@ -0,0 +1,9 @@
+from .base_agent import BaseAgent, AgentConfig
+from .react_agent import ReActAgent, ReActConfig
+from .mcp_react_agent import MCPReActAgent, MCPAgentConfig
+
+__all__ = [
+    "BaseAgent", "AgentConfig", 
+    "ReActAgent", "ReActConfig",
+    "MCPReActAgent", "MCPAgentConfig",
+]

agents/base_agent.py

@@ -0,0 +1,78 @@
+"""
+Base Agent Abstract Class
+
+Defines the interface that all text adventure agents must implement.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from games.zork_env import GameState
+
+
+@dataclass
+class AgentConfig:
+    """Configuration for an agent."""
+    name: str = "BaseAgent"
+    max_history: int = 20  # Maximum number of past interactions to remember
+    verbose: bool = False
+
+
+class BaseAgent(ABC):
+    """
+    Abstract base class for text adventure agents.
+    
+    Students should extend this class and implement the `choose_action` method.
+    """
+    
+    def __init__(self, config: AgentConfig = None):
+        self.config = config or AgentConfig()
+        self.history: list[tuple[str, str, GameState]] = []  # (action, observation, state)
+    
+    @abstractmethod
+    def choose_action(self, observation: str, game_state: GameState) -> str:
+        """
+        Choose the next action based on the current observation and game state.
+        
+        Args:
+            observation: The text observation from the game
+            game_state: The current GameState object with score, inventory, etc.
+            
+        Returns:
+            A string action to take in the game (e.g., "go north", "take lamp")
+        """
+        pass
+    
+    def update_history(self, action: str, observation: str, game_state: GameState):
+        """
+        Update the agent's history after taking an action.
+        
+        Args:
+            action: The action that was taken
+            observation: The resulting observation
+            game_state: The resulting game state
+        """
+        self.history.append((action, observation, game_state))
+        
+        # Keep history bounded
+        if len(self.history) > self.config.max_history:
+            self.history = self.history[-self.config.max_history:]
+    
+    def reset(self):
+        """Reset the agent's internal state for a new game."""
+        self.history = []
+    
+    def get_history_text(self) -> str:
+        """Get a text summary of recent history for context."""
+        if not self.history:
+            return "No previous actions taken."
+        
+        lines = []
+        for action, observation, state in self.history[-10:]:  # Last 10 actions
+            lines.append(f"> {action}")
+            # Truncate long observations
+            obs_preview = observation[:200] + "..." if len(observation) > 200 else observation
+            lines.append(obs_preview)
+            lines.append(f"[Score: {state.score}, Moves: {state.moves}]")
+            lines.append("")
+        
+        return "\n".join(lines)

agents/mcp_react_agent.py

@@ -0,0 +1,477 @@
+"""
+MCP ReAct Agent for Text Adventure Games
+
+A production-ready ReAct agent that uses FastMCP Client to play text adventures via MCP tools.
+This agent connects to the Text Adventure MCP server and uses the LLM to reason and act.
+
+Features:
+- FastMCP Client integration for MCP server communication
+- ReAct loop (Thought -> Tool -> Observation)
+- Loop detection and action validation
+- History tracking and memory management
+- Score tracking and game over detection
+"""
+
+import asyncio
+import json
+import os
+import re
+import sys
+from dataclasses import dataclass, field
+from huggingface_hub import InferenceClient
+from dotenv import load_dotenv
+from fastmcp import Client
+from fastmcp.client.transports import StdioTransport
+
+
+@dataclass
+class MCPAgentConfig:
+    """Configuration for the MCP ReAct agent."""
+    model: str = "meta-llama/Llama-3.2-3B-Instruct"
+    game: str = "zork1"  # Default game to play
+    temperature: float = 0.7
+    max_tokens: int = 300
+    max_history: int = 10
+    verbose: bool = True
+
+
+SYSTEM_PROMPT = """You are an expert text adventure game player. Your goal is to explore, collect treasures, and maximize your score.
+
+AVAILABLE TOOLS (use these via MCP):
+1. play_action - Execute game commands (north, take lamp, open mailbox, etc.)
+2. memory - Get current game state, score, and recent history
+3. get_map - See explored locations and connections
+4. inventory - Check what you're carrying
+5. hint - Get a hint if stuck
+6. list_games - See available games
+7. reset_game - Switch to a different game
+
+VALID GAME COMMANDS for play_action:
+- Movement: north, south, east, west, up, down, enter, exit
+- Objects: take <item>, drop <item>, open <thing>, close <thing>, examine <thing>
+- Light: turn on lamp, turn off lamp
+- Combat: attack <enemy> with <weapon>
+- Other: inventory, look, read <thing>, wait
+
+FORBIDDEN (will NOT work): check, inspect, search, grab, use, help
+
+RESPOND IN THIS EXACT FORMAT (no markdown):
+THOUGHT: <brief reasoning about what to do next>
+TOOL: <tool_name>
+ARGS: <JSON arguments>
+
+Examples:
+THOUGHT: I need to see what's around me.
+TOOL: play_action
+ARGS: {"action": "look"}
+
+THOUGHT: Let me check my current state and score.
+TOOL: memory
+ARGS: {}
+
+THOUGHT: The mailbox might contain something useful.
+TOOL: play_action
+ARGS: {"action": "open mailbox"}
+
+STRATEGY:
+1. Start by looking around and checking memory
+2. Explore systematically - try all directions
+3. Pick up useful items (lamp, sword, etc.)
+4. Open containers (mailbox, window, etc.)
+5. Use get_map to avoid getting lost
+6. Turn on lamp before dark areas!
+
+DO NOT repeat the same action multiple times in a row."""
+
+
+class MCPReActAgent:
+    """
+    A ReAct agent that plays text adventure games using MCP tools via FastMCP Client.
+    
+    This is the robust/production version with:
+    - Full MCP integration
+    - Loop detection
+    - Action validation
+    - Score tracking
+    """
+    
+    def __init__(self, mcp_server_path: str, config: MCPAgentConfig = None):
+        """
+        Initialize the MCP ReAct agent.
+        
+        Args:
+            mcp_server_path: Path to the MCP server script
+            config: Agent configuration
+        """
+        load_dotenv()
+        
+        self.mcp_server_path = mcp_server_path
+        self.config = config or MCPAgentConfig()
+        
+        # Override model from environment if set
+        env_model = os.getenv("HF_MODEL")
+        if env_model:
+            self.config.model = env_model
+        
+        # Initialize LLM client
+        token = os.getenv("HF_TOKEN")
+        if not token:
+            raise ValueError("HF_TOKEN not found. Set it in your .env file.")
+        self.llm = InferenceClient(token=token)
+        
+        # Agent state
+        self.history: list[dict] = []
+        self.thoughts: list[str] = []
+        self.score: int = 0
+        self.max_score: int = 350
+        self.recent_actions: list[str] = []  # For loop detection
+    
+    async def run(self, max_steps: int = 100) -> dict:
+        """
+        Run the ReAct agent loop.
+        
+        Args:
+            max_steps: Maximum number of steps to run
+            
+        Returns:
+            Dictionary with game results
+        """
+        import time
+        start_time = time.time()
+        step = 0
+        game_over = False
+        game_name = self.config.game
+        
+        print("=" * 60)
+        print(f"MCP ReAct Agent - Playing {game_name.upper()}")
+        print(f"Model: {self.config.model}")
+        print("=" * 60)
+        
+        # Set game as environment variable for the server
+        env = os.environ.copy()
+        env["GAME"] = game_name
+        
+        # Create transport with environment variables
+        transport = StdioTransport(
+            command=sys.executable,
+            args=[self.mcp_server_path],
+            env=env,
+        )
+        
+        # Connect to MCP server with game environment
+        async with Client(transport) as client:
+            # List available tools
+            tools = await client.list_tools()
+            tool_names = [t.name for t in tools]
+            print(f"\nConnected to MCP server. Tools: {tool_names}")
+            
+            # Get initial observation
+            result = await client.call_tool("play_action", {"action": "look"})
+            observation = self._extract_result(result)
+            print(f"\n{observation}\n")
+            
+            # Parse initial score
+            self._update_score(observation)
+            
+            # Main ReAct loop
+            for step in range(1, max_steps + 1):
+                print(f"\n{'─' * 50}")
+                print(f"Step {step}/{max_steps} | Score: {self.score}")
+                print("─" * 50)
+                
+                # Build prompt with context
+                prompt = self._build_prompt(observation)
+                
+                # Call LLM for reasoning
+                response = self._call_llm(prompt)
+                
+                # Parse response
+                thought, tool_name, tool_args = self._parse_response(response, tool_names)
+                
+                self.thoughts.append(thought)
+                
+                if self.config.verbose:
+                    print(f"\n[THOUGHT] {thought}")
+                    print(f"[TOOL] {tool_name}({tool_args})")
+                
+                # Validate and fix common issues
+                tool_name, tool_args = self._validate_tool_call(tool_name, tool_args, tool_names)
+                
+                # Check for loops
+                if tool_name == "play_action":
+                    action = tool_args.get("action", "look")
+                    self.recent_actions.append(action)
+                    if len(self.recent_actions) > 5:
+                        self.recent_actions = self.recent_actions[-5:]
+                    
+                    # Detect loops
+                    if len(self.recent_actions) >= 3 and len(set(self.recent_actions[-3:])) == 1:
+                        print(f"\n[WARNING] Loop detected - repeating '{action}'")
+                        # Force a different action
+                        tool_args = {"action": "look"}
+                        self.recent_actions.append("look")
+                
+                # Execute tool via MCP
+                try:
+                    result = await client.call_tool(tool_name, tool_args)
+                    observation = self._extract_result(result)
+                    print(f"\n{observation}")
+                except Exception as e:
+                    observation = f"Error executing tool: {e}"
+                    print(f"\n[ERROR] {e}")
+                
+                # Update history
+                self.history.append({
+                    "step": step,
+                    "thought": thought,
+                    "tool": tool_name,
+                    "args": tool_args,
+                    "result": observation[:200]
+                })
+                if len(self.history) > self.config.max_history:
+                    self.history = self.history[-self.config.max_history:]
+                
+                # Update score
+                self._update_score(observation)
+                
+                # Check for game over
+                if self._is_game_over(observation):
+                    game_over = True
+                    print("\n" + "=" * 60)
+                    print("GAME OVER!")
+                    break
+        
+        elapsed_time = time.time() - start_time
+        
+        # Print summary
+        return self._print_summary(step, elapsed_time, game_over)
+    
+    def _build_prompt(self, observation: str) -> str:
+        """Build the prompt for the LLM with context."""
+        parts = []
+        
+        # Score info
+        parts.append(f"Current Score: {self.score}/{self.max_score}")
+        
+        # Recent history (compact)
+        if self.history:
+            parts.append("\nRecent actions:")
+            for entry in self.history[-3:]:
+                action = entry.get("args", {}).get("action", entry["tool"])
+                result_short = entry["result"][:80] + "..." if len(entry["result"]) > 80 else entry["result"]
+                parts.append(f"  > {action} -> {result_short}")
+            
+            # Warn about repeated actions
+            if self.recent_actions and len(set(self.recent_actions[-3:])) == 1:
+                parts.append(f"\n[WARNING: You've been doing '{self.recent_actions[-1]}' repeatedly. TRY SOMETHING DIFFERENT!]")
+        
+        # Current observation
+        parts.append(f"\nCurrent situation:\n{observation}")
+        parts.append("\nWhat do you do next?")
+        
+        return "\n".join(parts)
+    
+    def _call_llm(self, prompt: str) -> str:
+        """Call the LLM for reasoning."""
+        try:
+            messages = [
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user", "content": prompt}
+            ]
+            
+            response = self.llm.chat.completions.create(
+                model=self.config.model,
+                messages=messages,
+                temperature=self.config.temperature,
+                max_tokens=self.config.max_tokens,
+            )
+            return response.choices[0].message.content
+        except Exception as e:
+            print(f"[LLM Error] {e}")
+            return "THOUGHT: LLM error, trying look.\nTOOL: play_action\nARGS: {\"action\": \"look\"}"
+    
+    def _parse_response(self, response: str, valid_tools: list[str]) -> tuple[str, str, dict]:
+        """Parse the LLM response to extract thought, tool, and arguments."""
+        thought = "No reasoning provided"
+        tool_name = "play_action"
+        tool_args = {"action": "look"}
+        
+        lines = response.strip().split("\n")
+        
+        for i, line in enumerate(lines):
+            line_clean = line.strip()
+            line_upper = line_clean.upper()
+            
+            if line_upper.startswith("THOUGHT:"):
+                thought = line_clean.split(":", 1)[1].strip()
+            
+            elif line_upper.startswith("TOOL:"):
+                raw_tool = line_clean.split(":", 1)[1].strip().lower()
+                # Clean up common issues
+                raw_tool = raw_tool.replace("**", "").replace("*", "").replace("`", "")
+                raw_tool = raw_tool.split()[0] if raw_tool else "play_action"
+                tool_name = raw_tool
+            
+            elif line_upper.startswith("ARGS:"):
+                args_part = line_clean.split(":", 1)[1].strip()
+                try:
+                    # Handle various JSON formats
+                    args_part = args_part.replace("'", '"')
+                    tool_args = json.loads(args_part)
+                except json.JSONDecodeError:
+                    # Try to extract action from text
+                    match = re.search(r'"action"\s*:\s*"([^"]+)"', args_part)
+                    if match:
+                        tool_args = {"action": match.group(1)}
+                    else:
+                        # Fallback: try to use the whole thing as action
+                        tool_args = {"action": "look"}
+        
+        return thought, tool_name, tool_args
+    
+    def _validate_tool_call(self, tool_name: str, tool_args: dict, valid_tools: list[str]) -> tuple[str, dict]:
+        """Validate and fix common tool call issues."""
+        # Fix tool name
+        if tool_name not in valid_tools:
+            # Try common alternatives
+            if tool_name in ["action", "do", "command"]:
+                tool_name = "play_action"
+            elif tool_name in ["map", "location"]:
+                tool_name = "get_map"
+            elif tool_name in ["mem", "state", "status"]:
+                tool_name = "memory"
+            elif tool_name in ["inv", "items"]:
+                tool_name = "inventory"
+            else:
+                tool_name = "play_action"
+        
+        # Fix action in args
+        if tool_name == "play_action":
+            action = tool_args.get("action", "look")
+            
+            # Fix invalid verbs
+            invalid_verb_map = {
+                "check": "examine",
+                "inspect": "examine",
+                "search": "look",
+                "grab": "take",
+                "pick": "take",
+                "use": "examine",
+                "investigate": "examine",
+            }
+            
+            words = action.lower().split()
+            if words and words[0] in invalid_verb_map:
+                words[0] = invalid_verb_map[words[0]]
+                action = " ".join(words)
+            
+            # Clean up action
+            action = action.lower().strip()
+            action = action.replace("**", "").replace("*", "").replace("`", "")
+            action = " ".join(action.split())
+            
+            tool_args["action"] = action
+        
+        return tool_name, tool_args
+    
+    def _extract_result(self, result) -> str:
+        """Extract text from MCP tool result."""
+        if hasattr(result, 'content') and result.content:
+            return result.content[0].text
+        return str(result)
+    
+    def _update_score(self, text: str) -> None:
+        """Update score from game text."""
+        # Look for score patterns
+        patterns = [
+            r'\+(\d+) points',
+            r'Score:\s*(\d+)',
+            r'Total:\s*(\d+)',
+        ]
+        
+        for pattern in patterns:
+            match = re.search(pattern, text, re.IGNORECASE)
+            if match:
+                score = int(match.group(1))
+                if "+" in pattern:
+                    self.score += score
+                else:
+                    self.score = max(self.score, score)
+    
+    def _is_game_over(self, text: str) -> bool:
+        """Check if the game is over."""
+        game_over_phrases = [
+            "game over",
+            "you have died",
+            "you are dead",
+            "*** you have died ***",
+        ]
+        text_lower = text.lower()
+        return any(phrase in text_lower for phrase in game_over_phrases)
+    
+    def _print_summary(self, step: int, elapsed_time: float, game_over: bool) -> dict:
+        """Print game summary and return results."""
+        print("\n" + "=" * 60)
+        print("GAME SUMMARY")
+        print("=" * 60)
+        print(f"Final Score: {self.score}/{self.max_score} ({100*self.score/self.max_score:.1f}%)")
+        print(f"Steps Taken: {step}")
+        print(f"Time Elapsed: {elapsed_time:.1f} seconds")
+        print(f"Game Over: {game_over}")
+        print("=" * 60)
+        
+        return {
+            "final_score": self.score,
+            "max_score": self.max_score,
+            "score_percentage": 100 * self.score / self.max_score,
+            "steps": step,
+            "elapsed_time": elapsed_time,
+            "game_over": game_over,
+        }
+
+
+# =============================================================================
+# Main
+# =============================================================================
+
+async def main():
+    """Run the MCP ReAct agent."""
+    import argparse
+    
+    parser = argparse.ArgumentParser(description="Run the MCP ReAct Text Adventure Agent")
+    parser.add_argument(
+        "--server", "-s",
+        default="mcp_server/zork_server.py",
+        help="Path to the MCP server script"
+    )
+    parser.add_argument(
+        "--max-steps", "-n",
+        type=int,
+        default=100,
+        help="Maximum steps to run"
+    )
+    parser.add_argument(
+        "--model",
+        type=str,
+        default=None,
+        help="HuggingFace model to use"
+    )
+    parser.add_argument(
+        "--verbose", "-v",
+        action="store_true",
+        default=True,
+        help="Show detailed output"
+    )
+    
+    args = parser.parse_args()
+    
+    config = MCPAgentConfig(verbose=args.verbose)
+    if args.model:
+        config.model = args.model
+    
+    agent = MCPReActAgent(args.server, config)
+    return await agent.run(max_steps=args.max_steps)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agents/react_agent.py

@@ -0,0 +1,243 @@
+"""
+ReAct Agent for Text Adventure Games
+
+Implements a ReAct (Reasoning + Acting) loop using an LLM to play text adventures.
+The agent thinks about its situation, decides on an action, and learns from the result.
+"""
+
+import os
+from dataclasses import dataclass
+from huggingface_hub import InferenceClient
+from dotenv import load_dotenv
+
+from agents.base_agent import BaseAgent, AgentConfig
+from games.zork_env import GameState
+
+
+@dataclass
+class ReActConfig(AgentConfig):
+    """Configuration for the ReAct agent."""
+    name: str = "ReActAgent"
+    model: str = "meta-llama/Llama-3.2-3B-Instruct"
+    temperature: float = 0.7
+    max_tokens: int = 300
+    max_history: int = 15
+
+
+SYSTEM_PROMPT = """You are playing a classic text adventure game.
+
+GOAL: Explore the world, solve puzzles, collect treasures, and maximize your score.
+
+VALID COMMANDS:
+- Movement: north, south, east, west, up, down, enter, exit
+- Looking: look, examine <thing>, read <thing>  
+- Objects: take <item>, drop <item>, open <thing>, close <thing>
+- Light: turn on lamp, light match
+- Combat: attack <enemy> with <weapon>
+- Other: inventory, wait, push <thing>, move <thing>
+
+INVALID COMMANDS (do NOT use): check, inspect, search, grab, use, help
+
+TIPS:
+- Explore systematically - try all directions
+- Examine interesting objects and read documents
+- Pick up useful items (lamp, keys, weapons)
+- Open containers to find hidden items
+
+You MUST respond in EXACTLY this format (no markdown, no extra text):
+THOUGHT: <your reasoning in one sentence>
+ACTION: <one valid command>
+
+Example response:
+THOUGHT: I see a container here, I should check what is inside.
+ACTION: open container"""
+
+
+class ReActAgent(BaseAgent):
+    """
+    A ReAct (Reasoning + Acting) agent that uses an LLM to play text adventures.
+    
+    Uses Hugging Face Hub's Inference API.
+    """
+    
+    def __init__(self, config: ReActConfig = None, token: str = None):
+        super().__init__(config or ReActConfig())
+        self.config: ReActConfig = self.config
+        
+        # Load token from environment if not provided
+        load_dotenv()
+        token = token or os.getenv("HF_TOKEN")
+        if not token:
+            raise ValueError("HF_TOKEN not found. Set HF_TOKEN environment variable or pass token parameter.")
+        
+        # Override model from environment if set
+        env_model = os.getenv("HF_MODEL")
+        if env_model:
+            self.config.model = env_model
+        
+        self.client = InferenceClient(token=token)
+        self.thoughts: list[str] = []  # Store reasoning history
+    
+    def choose_action(self, observation: str, game_state: GameState) -> str:
+        """
+        Use the LLM to reason about the situation and choose an action.
+        """
+        # Build the prompt with context
+        prompt = self._build_prompt(observation, game_state)
+        
+        # Call the LLM
+        response = self._call_llm(prompt)
+        
+        # Parse the response
+        thought, action = self._parse_response(response)
+        
+        # Store the thought for history
+        self.thoughts.append(thought)
+        
+        if self.config.verbose:
+            print(f"\n[Thought] {thought}")
+            print(f"[Action] {action}")
+        
+        return action
+    
+    def _build_prompt(self, observation: str, game_state: GameState) -> str:
+        """Build the prompt for the LLM with current context."""
+        parts = []
+        
+        # Current status (compact for small models)
+        parts.append(f"Score: {game_state.score}/{game_state.max_score} | Moves: {game_state.moves}")
+        
+        if game_state.inventory:
+            parts.append(f"Inventory: {', '.join(game_state.inventory)}")
+        
+        # Recent history (only last 3 for small models)
+        if self.history:
+            parts.append("\nRecent:")
+            recent_actions = []
+            for action, obs, state in self.history[-3:]:
+                obs_short = obs[:150] + "..." if len(obs) > 150 else obs
+                parts.append(f"> {action}\n{obs_short}")
+                recent_actions.append(action)
+            
+            # Warn about repeated actions
+            if len(recent_actions) >= 2 and len(set(recent_actions)) == 1:
+                parts.append(f"\n[WARNING: You've done '{recent_actions[0]}' multiple times. Try something different!]")
+        
+        # Current observation
+        parts.append(f"\nNow:\n{observation}")
+        parts.append("\nWhat do you do next? (Try a NEW action)")
+        
+        return "\n".join(parts)
+    
+    def _call_llm(self, prompt: str) -> str:
+        """Call the Hugging Face Inference API."""
+        try:
+            messages = [
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user", "content": prompt}
+            ]
+            
+            response = self.client.chat.completions.create(
+                model=self.config.model,
+                messages=messages,
+                temperature=self.config.temperature,
+                max_tokens=self.config.max_tokens,
+            )
+            return response.choices[0].message.content
+        except Exception as e:
+            print(f"Error calling LLM: {e}")
+            return "THOUGHT: Error occurred, trying a safe action.\nACTION: look"
+    
+    def _parse_response(self, response: str) -> tuple[str, str]:
+        """Parse the LLM response to extract thought and action."""
+        thought = ""
+        action = "look"  # Default fallback action
+        
+        lines = response.strip().split("\n")
+        
+        for i, line in enumerate(lines):
+            line_upper = line.upper().strip()
+            
+            if line_upper.startswith("THOUGHT:"):
+                # Extract thought (may span multiple lines until ACTION)
+                thought_parts = [line.split(":", 1)[1].strip()]
+                for j in range(i + 1, len(lines)):
+                    if lines[j].upper().strip().startswith("ACTION:"):
+                        break
+                    thought_parts.append(lines[j].strip())
+                thought = " ".join(thought_parts).strip()
+            
+            elif line_upper.startswith("ACTION:"):
+                action = line.split(":", 1)[1].strip().lower()
+                # Clean up the action - remove quotes, markdown, and extra whitespace
+                action = action.strip('"\'')
+                # Remove markdown bold/italic markers
+                action = action.replace("**", "").replace("*", "").replace("__", "").replace("_", " ")
+                # Remove backticks
+                action = action.replace("`", "")
+                # Clean up whitespace
+                action = " ".join(action.split())
+                break
+        
+        # Validate action isn't empty
+        if not action or action.isspace():
+            action = "look"
+        
+        return thought, action
+    
+    def reset(self):
+        """Reset the agent for a new game."""
+        super().reset()
+        self.thoughts = []
+    
+    def get_summary(self) -> str:
+        """Get a summary of the agent's reasoning."""
+        if not self.thoughts:
+            return "No thoughts recorded yet."
+        
+        return "\n---\n".join(self.thoughts[-5:])
+
+
+# Example usage and testing
+if __name__ == "__main__":
+    import sys
+    from games.zork_env import TextAdventureEnv
+    
+    # Use command line arg or default to zork1
+    game = sys.argv[1] if len(sys.argv) > 1 else "zork1"
+    
+    # Quick test
+    config = ReActConfig(verbose=True)
+    
+    try:
+        agent = ReActAgent(config)
+        env = TextAdventureEnv(game)
+        
+        state = env.reset()
+        print("=" * 50)
+        print(f"{game.upper()} (using {agent.config.model})")
+        print("=" * 50)
+        print(state.observation)
+        
+        # Run a few steps
+        for step in range(5):
+            print(f"\n{'=' * 50}")
+            print(f"Step {step + 1}")
+            print("=" * 50)
+            
+            action = agent.choose_action(state.observation, state)
+            print(f"\n> {action}")
+            
+            state = env.step(action)
+            print(f"\n{state.observation}")
+            print(f"\nScore: {state.score}/{state.max_score}")
+            
+            agent.update_history(action, state.observation, state)
+            
+            if state.done:
+                print("\nGAME OVER!")
+                break
+    
+    except ValueError as e:
+        print(f"Setup error: {e}")
+        print("Make sure to set your HF_TOKEN in .env file")

function_calling/controller.py

@@ -0,0 +1,291 @@
+"""
+Function-Calling Controller for Zork (API-Based)
+
+This controller uses the HuggingFace API's native function calling feature.
+The model is given tool schemas and can call them via the tools API.
+
+Model: Llama 3.2 3B Instruct (supports native function calling)
+
+Compare with simple_controller.py which uses text-based "parsing" approach.
+"""
+
+import os
+import json
+from dotenv import load_dotenv
+from huggingface_hub import InferenceClient
+
+from tools import ALL_TOOLS, set_game_state, add_to_history
+
+# Add parent directory to path to import games module
+import sys
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from games.zork_env import ZorkEnvironment
+
+
+# System prompt for the agent
+SYSTEM_PROMPT = """You are playing Zork, a classic text adventure game.
+
+## YOUR GOAL
+Explore, collect treasures (bring them to the trophy case), and maximize your score.
+
+## VALID COMMANDS (use ONLY these exact verbs)
+
+Movement:
+  north, south, east, west, up, down (or n, s, e, w, u, d)
+  enter, exit, climb, cross, go <direction>
+
+Looking:
+  look, examine <thing>, look at <thing>, look in <thing>, read <thing>
+
+Objects:
+  take <item>, drop <item>, pick up <item>
+  open <thing>, close <thing>, unlock <thing> with <key>
+  put <item> in <container>, give <item> to <person>
+
+Light:
+  turn on lamp, turn off lamp, light match
+
+Combat:
+  attack <enemy> with <weapon>, kill <enemy> with <weapon>
+
+Other:
+  inventory (or i), wait (or z), score, save, restore
+  push <thing>, pull <thing>, move <thing>, tie <rope> to <thing>
+  eat <food>, drink <liquid>, wave <item>
+
+## FORBIDDEN (these will NOT work):
+  check, inspect, search, investigate, grab, pick, use, interact,
+  go to, walk to, head to, travel, proceed
+
+## YOUR TOOLS
+  memory()    - See current state and recent actions
+  get_map()   - See explored locations
+  inventory() - Check what you're carrying
+
+## RESPONSE FORMAT
+When you want to take a game action, respond with:
+  ACTION: <command>
+
+Examples:
+  ACTION: open mailbox
+  ACTION: north
+  ACTION: take lamp
+  ACTION: examine leaflet"""
+
+
+# Valid Zork command verbs for validation
+VALID_VERBS = {
+    "north", "south", "east", "west", "up", "down", "n", "s", "e", "w", "u", "d",
+    "look", "l", "examine", "x", "read",
+    "take", "get", "drop", "put", "give",
+    "open", "close", "unlock", "lock",
+    "turn", "light", "extinguish", "blow",
+    "attack", "kill", "fight", "hit",
+    "enter", "exit", "go", "climb", "jump",
+    "inventory", "i", "wait", "z", "score",
+    "move", "push", "pull", "tie", "untie",
+    "eat", "drink", "smell", "touch", "rub",
+    "wave", "raise", "lower", "pour",
+    "say", "answer", "yes", "no",
+    "pray", "odysseus", "echo", "hello",
+}
+
+
+def validate_action(action: str) -> str:
+    """Validate and potentially fix an action."""
+    action = action.strip().lower()
+    if not action:
+        return "look"
+    
+    verb = action.split()[0]
+    
+    if verb in VALID_VERBS:
+        return action
+    
+    # Common corrections
+    corrections = {
+        "check": "examine",
+        "inspect": "examine", 
+        "search": "examine",
+        "grab": "take",
+        "pick": "take",
+        "see": "look",
+        "view": "look",
+        "walk": "go",
+    }
+    
+    if verb in corrections:
+        return corrections[verb] + action[len(verb):]
+    
+    return "look"  # Default fallback
+
+
+def build_tool_schemas():
+    """Convert LangChain tools to OpenAI function schemas."""
+    schemas = []
+    for tool in ALL_TOOLS:
+        schema = {
+            "type": "function",
+            "function": {
+                "name": tool.name,
+                "description": tool.description,
+                "parameters": {
+                    "type": "object",
+                    "properties": {},
+                    "required": []
+                }
+            }
+        }
+        schemas.append(schema)
+    return schemas
+
+
+def run_tool(tool_name: str) -> str:
+    """Execute a tool by name and return its result."""
+    for tool in ALL_TOOLS:
+        if tool.name == tool_name:
+            return tool.invoke({})
+    return f"Unknown tool: {tool_name}"
+
+
+class FunctionCallingController:
+    """Controller using LLM API-based function calling."""
+    
+    def __init__(self, model: str = "meta-llama/Llama-3.2-3B-Instruct"):
+        load_dotenv()
+        token = os.getenv("HF_TOKEN")
+        if not token:
+            raise ValueError("HF_TOKEN not set in environment")
+        
+        self.client = InferenceClient(token=token)
+        self.model = os.getenv("HF_MODEL", model)
+        self.tool_schemas = build_tool_schemas()
+    
+    def get_action(self, observation: str, game_state) -> str:
+        """Get the next action from the LLM."""
+        
+        # Update tool state
+        set_game_state(
+            observation=observation,
+            inventory=list(game_state.inventory) if game_state.inventory else [],
+            score=game_state.score,
+            moves=game_state.moves
+        )
+        
+        # Build messages fresh each time (simpler than managing tool history)
+        messages = [
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": f"Game output:\n{observation}\n\nWhat do you do?"}
+        ]
+        
+        # Allow up to 3 tool calls before requiring action
+        for _ in range(3):
+            response = self.client.chat.completions.create(
+                model=self.model,
+                messages=messages,
+                tools=self.tool_schemas,
+                tool_choice="auto",
+                max_tokens=300,
+            )
+            
+            message = response.choices[0].message
+            
+            # Check if model wants to use a tool
+            if message.tool_calls:
+                tool_call = message.tool_calls[0]
+                tool_name = tool_call.function.name
+                
+                print(f"  [Tool] {tool_name}")
+                tool_result = run_tool(tool_name)
+                print(f"  {tool_result[:100]}...")
+                
+                # Add tool interaction to messages for next iteration
+                messages.append({
+                    "role": "assistant",
+                    "content": None,
+                    "tool_calls": [{
+                        "id": tool_call.id,
+                        "type": "function",
+                        "function": {"name": tool_name, "arguments": "{}"}
+                    }]
+                })
+                messages.append({
+                    "role": "tool",
+                    "tool_call_id": tool_call.id,
+                    "content": tool_result
+                })
+                
+                # Continue to get the actual action
+                continue
+            
+            # Model responded with text - extract action
+            content = message.content or ""
+            
+            # Look for ACTION: in response
+            if "ACTION:" in content.upper():
+                for line in content.split('\n'):
+                    if "ACTION:" in line.upper():
+                        action = line.split(":", 1)[1].strip().lower()
+                        validated = validate_action(action)
+                        if validated:
+                            return validated
+                        else:
+                            print(f"  [Warning] Invalid action '{action}', defaulting to 'look'")
+                            return "look"
+            
+            # If no ACTION found, try to extract a command from the response
+            content_lower = content.lower().strip()
+            validated = validate_action(content_lower)
+            if validated:
+                return validated
+            
+            # Default
+            return "look"
+        
+        # After 3 tool calls, just return look
+        return "look"
+
+
+def main():
+    """Run the API-based function-calling controller."""
+    print("=" * 60)
+    print("Zork - API Function Calling Controller")
+    print("   (using Llama 3.2 3B with native tool calling)")
+    print("=" * 60)
+    
+    controller = FunctionCallingController()
+    env = ZorkEnvironment("zork1")
+    
+    state = env.reset()
+    print(f"\n{state.observation}\n")
+    
+    max_steps = 30
+    
+    for step in range(max_steps):
+        print(f"\n{'─' * 50}")
+        print(f"Step {step + 1}/{max_steps} | Score: {state.score}")
+        print("─" * 50)
+        
+        action = controller.get_action(state.observation, state)
+        print(f"\n> ACTION: {action}")
+        
+        # Take action in game
+        state = env.step(action)
+        add_to_history(action, state.observation)
+        
+        print(f"\n{state.observation}")
+        
+        if state.reward > 0:
+            print(f"\n+{state.reward} points!")
+        
+        if state.done:
+            print("\nGAME OVER!")
+            break
+    
+    print(f"\n{'=' * 60}")
+    print(f"Final Score: {state.score}")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

function_calling/simple_controller.py

@@ -0,0 +1,268 @@
+"""
+Function-Calling Controller for Zork (Text-Based)
+
+This controller uses text-based "function calling" - the LLM outputs
+TOOL: <name> or ACTION: <command> and we parse the text response.
+
+Model: Qwen 2.5 7B Instruct (any chat model works)
+
+This approach is:
+- Simpler and more reliable than API-based function calling
+- Works with any chat model (no special support needed)
+
+Compare with controller.py which uses API-based tool calling.
+"""
+
+import os
+import re
+from dotenv import load_dotenv
+from huggingface_hub import InferenceClient
+
+from tools import ALL_TOOLS, set_game_state, add_to_history
+
+# Add parent directory to path
+import sys
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from games.zork_env import ZorkEnvironment
+
+
+SYSTEM_PROMPT = """You are playing Zork, a classic text adventure game.
+
+## YOUR GOAL
+Explore, collect treasures (bring them to the trophy case), and maximize your score.
+
+## VALID COMMANDS (use ONLY these exact verbs)
+
+Movement:
+  north, south, east, west, up, down (or n, s, e, w, u, d)
+  enter, exit, climb, cross, go <direction>
+
+Looking:
+  look, examine <thing>, look at <thing>, look in <thing>, read <thing>
+
+Objects:
+  take <item>, drop <item>, pick up <item>
+  open <thing>, close <thing>, unlock <thing> with <key>
+  put <item> in <container>, give <item> to <person>
+
+Light:
+  turn on lamp, turn off lamp, light match
+
+Combat:
+  attack <enemy> with <weapon>, kill <enemy> with <weapon>
+
+Other:
+  inventory (or i), wait (or z), score, save, restore
+  push <thing>, pull <thing>, move <thing>, tie <rope> to <thing>
+  eat <food>, drink <liquid>, wave <item>
+
+## FORBIDDEN (these will NOT work):
+  check, inspect, search, investigate, grab, pick, use, interact,
+  go to, walk to, head to, travel, proceed
+
+## YOUR TOOLS
+  TOOL: memory    - See current state and recent actions
+  TOOL: get_map   - See explored locations
+  TOOL: inventory - Check what you're carrying
+
+## RESPONSE FORMAT
+Either use a tool:
+  TOOL: memory
+
+Or take a game action:
+  ACTION: open mailbox
+
+Always respond with TOOL: or ACTION: followed by your choice."""
+
+
+# Valid Zork command verbs for validation
+VALID_VERBS = {
+    "north", "south", "east", "west", "up", "down", "n", "s", "e", "w", "u", "d",
+    "look", "l", "examine", "x", "read",
+    "take", "get", "drop", "put", "give",
+    "open", "close", "unlock", "lock",
+    "turn", "light", "extinguish", "blow",
+    "attack", "kill", "fight", "hit",
+    "enter", "exit", "go", "climb", "jump",
+    "inventory", "i", "wait", "z", "score",
+    "move", "push", "pull", "tie", "untie",
+    "eat", "drink", "smell", "touch", "rub",
+    "wave", "raise", "lower", "pour",
+    "say", "answer", "yes", "no",
+    "pray", "odysseus", "echo", "hello",
+}
+
+
+def run_tool(tool_name: str) -> str:
+    """Execute a tool by name."""
+    tool_name = tool_name.strip().lower().replace(" ", "_")
+    for tool in ALL_TOOLS:
+        if tool.name == tool_name:
+            return tool.invoke({})
+    return f"Unknown tool: {tool_name}. Available: memory, get_map, inventory"
+
+
+class SimpleController:
+    """Controller using text-based tool calling."""
+    
+    def __init__(self, model: str = "Qwen/Qwen2.5-7B-Instruct"):
+        load_dotenv()
+        token = os.getenv("HF_TOKEN")
+        if not token:
+            raise ValueError("HF_TOKEN not set in environment")
+        
+        self.client = InferenceClient(token=token)
+        self.model = os.getenv("HF_MODEL", model)
+        self.messages = []
+    
+    def _call_llm(self, user_message: str) -> str:
+        """Call the LLM and get response."""
+        self.messages.append({"role": "user", "content": user_message})
+        
+        # Keep conversation short
+        if len(self.messages) > 15:
+            self.messages = self.messages[-15:]
+        
+        response = self.client.chat.completions.create(
+            model=self.model,
+            messages=[{"role": "system", "content": SYSTEM_PROMPT}] + self.messages,
+            max_tokens=150,
+            temperature=0.7,
+        )
+        
+        reply = response.choices[0].message.content or ""
+        self.messages.append({"role": "assistant", "content": reply})
+        return reply
+    
+    def _validate_action(self, action: str) -> str | None:
+        """Validate and potentially fix an action. Returns None if invalid."""
+        action = action.strip().lower()
+        if not action:
+            return None
+        
+        # Get the first word (verb)
+        verb = action.split()[0]
+        
+        # Check if it's a valid verb
+        if verb in VALID_VERBS:
+            return action
+        
+        # Try common corrections
+        corrections = {
+            "check": "examine",
+            "inspect": "examine",
+            "search": "examine",
+            "grab": "take",
+            "pick": "take",  # "pick up" -> "take"
+            "see": "look",
+            "view": "look",
+            "walk": "go",
+        }
+        
+        if verb in corrections:
+            fixed = corrections[verb] + action[len(verb):]
+            print(f"  [Correcting] '{verb}' -> '{corrections[verb]}'")
+            return fixed
+        
+        return None
+    
+    def get_action(self, observation: str, game_state) -> str:
+        """Get the next action, allowing tool use."""
+        
+        # Update tool state
+        set_game_state(
+            observation=observation,
+            inventory=list(game_state.inventory) if game_state.inventory else [],
+            score=game_state.score,
+            moves=game_state.moves
+        )
+        
+        prompt = f"Game:\n{observation}\n\nRespond with TOOL: or ACTION:"
+        
+        # Allow up to 3 tool calls before requiring an action
+        for _ in range(3):
+            response = self._call_llm(prompt)
+            
+            # Check for TOOL:
+            tool_match = re.search(r'TOOL:\s*(\w+)', response, re.IGNORECASE)
+            if tool_match:
+                tool_name = tool_match.group(1)
+                print(f"  [Tool] {tool_name}")
+                
+                result = run_tool(tool_name)
+                print(f"  {result[:80]}...")
+                
+                # Feed result back
+                prompt = f"Tool result:\n{result}\n\nNow respond with TOOL: or ACTION:"
+                continue
+            
+            # Check for ACTION:
+            action_match = re.search(r'ACTION:\s*(.+)', response, re.IGNORECASE)
+            if action_match:
+                action = action_match.group(1).strip().lower()
+                # Clean up action (remove quotes, extra text)
+                action = action.split('\n')[0].strip('"\'')
+                
+                # Validate the action
+                validated = self._validate_action(action)
+                if validated:
+                    return validated
+                else:
+                    print(f"  [Warning] Invalid action '{action}', asking for retry...")
+                    prompt = f"'{action}' is not a valid Zork command. Use verbs like: look, examine, take, open, north, south, etc.\n\nRespond with ACTION:"
+                    continue
+            
+            # If neither, try to extract a command
+            words = response.lower().split()
+            for cmd in ["north", "south", "east", "west", "up", "down", 
+                       "look", "take", "open", "enter", "examine"]:
+                if cmd in words:
+                    idx = words.index(cmd)
+                    return " ".join(words[idx:idx+3])
+            
+            return "look"
+        
+        return "look"
+
+
+def main():
+    """Run the simple controller."""
+    print("=" * 60)
+    print("Zork - Simple Function Calling Demo")
+    print("=" * 60)
+    
+    controller = SimpleController()
+    env = ZorkEnvironment("zork1")
+    
+    state = env.reset()
+    print(f"\n{state.observation}\n")
+    
+    max_steps = 30
+    
+    for step in range(max_steps):
+        print(f"\n{'─' * 50}")
+        print(f"Step {step + 1}/{max_steps} | Score: {state.score}")
+        print("─" * 50)
+        
+        action = controller.get_action(state.observation, state)
+        print(f"\n> ACTION: {action}")
+        
+        state = env.step(action)
+        add_to_history(action, state.observation)
+        
+        print(f"\n{state.observation}")
+        
+        if state.reward > 0:
+            print(f"\n+{state.reward} points!")
+        
+        if state.done:
+            print("\nGAME OVER!")
+            break
+    
+    print(f"\n{'=' * 60}")
+    print(f"Final Score: {state.score}")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

function_calling/tools.py

@@ -0,0 +1,127 @@
+"""
+Simple tools for the Zork agent using LangChain's tool decorator.
+"""
+
+from langchain_core.tools import tool
+
+
+# Game state that tools can access (set by the controller)
+_game_state = {
+    "observation": "",
+    "inventory": [],
+    "score": 0,
+    "moves": 0,
+    "history": [],  # List of (action, result) tuples
+}
+
+
+def set_game_state(observation: str, inventory: list, score: int, moves: int):
+    """Update the game state (called by controller after each action)."""
+    _game_state["observation"] = observation
+    _game_state["inventory"] = inventory
+    _game_state["score"] = score
+    _game_state["moves"] = moves
+
+
+def add_to_history(action: str, result: str):
+    """Add an action and its result to history."""
+    _game_state["history"].append((action, result))
+    # Keep only last 10 actions
+    if len(_game_state["history"]) > 10:
+        _game_state["history"] = _game_state["history"][-10:]
+
+
+@tool
+def memory() -> str:
+    """Get a summary of the current game state including location, score, and recent actions."""
+    obs = _game_state["observation"]
+    score = _game_state["score"]
+    moves = _game_state["moves"]
+    
+    # Extract location (first line of observation)
+    lines = obs.strip().split('\n')
+    location = lines[0] if lines else "Unknown"
+    
+    # Recent actions
+    recent = _game_state["history"][-5:] if _game_state["history"] else []
+    recent_str = "\n".join([f"  > {a} → {r[:50]}..." for a, r in recent]) if recent else "  (none yet)"
+    
+    return f"""Current State:
+- Location: {location}
+- Score: {score} points
+- Moves: {moves}
+
+Recent Actions:
+{recent_str}
+
+Current Observation:
+{obs}"""
+
+
+@tool
+def get_map() -> str:
+    """Get a map showing known locations and connections based on exploration history."""
+    # Build a simple map from history
+    locations = set()
+    connections = []
+    
+    prev_loc = None
+    for action, result in _game_state["history"]:
+        # Extract location from result
+        lines = result.strip().split('\n')
+        if lines:
+            loc = lines[0]
+            locations.add(loc)
+            
+            # If this was a movement action, record connection
+            if action in ["north", "south", "east", "west", "up", "down", "enter", "exit"]:
+                if prev_loc and prev_loc != loc:
+                    connections.append(f"  {prev_loc} --{action}--> {loc}")
+                prev_loc = loc
+    
+    if not locations:
+        return "Map: No locations explored yet. Try moving around!"
+    
+    loc_list = "\n".join([f"  - {loc}" for loc in sorted(locations)])
+    conn_list = "\n".join(connections[-10:]) if connections else "  (no connections recorded)"
+    
+    return f"""Known Locations:
+{loc_list}
+
+Connections:
+{conn_list}"""
+
+
+@tool
+def inventory() -> str:
+    """Get the list of items currently in your inventory."""
+    items = _game_state["inventory"]
+    
+    if not items:
+        return "Inventory: You are empty-handed."
+    
+    # Clean up item names (Jericho returns objects with metadata)
+    item_names = []
+    for item in items:
+        item_str = str(item)
+        # Handle Jericho's object format: "leaflet Parent4 Sibling0..."
+        # Look for "Parent" (case-insensitive) to find where metadata starts
+        item_lower = item_str.lower()
+        if "parent" in item_lower:
+            idx = item_lower.index("parent")
+            name = item_str[:idx].strip()
+            # Remove leading "obj123: " if present
+            if ":" in name:
+                name = name.split(":", 1)[1].strip()
+            item_names.append(name)
+        elif ":" in item_str:
+            name = item_str.split(":")[1].strip()
+            item_names.append(name)
+        else:
+            item_names.append(item_str)
+    
+    return f"Inventory: {', '.join(item_names)}"
+
+
+# Export all tools
+ALL_TOOLS = [memory, get_map, inventory]

games/__init__.py

@@ -0,0 +1,6 @@
+from .zork_env import TextAdventureEnv, GameState, list_available_games, discover_games
+
+# Alias for backwards compatibility
+ZorkEnvironment = TextAdventureEnv
+
+__all__ = ["TextAdventureEnv", "ZorkEnvironment", "GameState", "list_available_games", "discover_games"]

games/zork_env.py

@@ -0,0 +1,219 @@
+"""
+Text Adventure Game Environment
+
+Provides a clean interface to text adventure games via Jericho.
+Supports Zork and many other classic Z-machine games.
+"""
+
+from jericho import FrotzEnv
+from dataclasses import dataclass
+from typing import Optional
+from pathlib import Path
+import os
+
+
+@dataclass
+class GameState:
+    """Represents the current state of the game."""
+    observation: str
+    score: int
+    max_score: int
+    moves: int
+    done: bool
+    reward: int  # Points gained from last action
+    inventory: list[str]
+    location: str
+
+
+def get_default_games_dir() -> Path:
+    """Get the default directory containing game files."""
+    project_root = Path(__file__).parent.parent
+    return project_root / "z-machine-games-master" / "jericho-game-suite"
+
+
+def discover_games(games_dir: Optional[Path] = None) -> dict[str, Path]:
+    """
+    Discover all available Z-machine games in the games directory.
+    
+    Args:
+        games_dir: Directory to search for games (default: jericho-game-suite)
+        
+    Returns:
+        Dictionary mapping game name (without extension) to full path
+    """
+    if games_dir is None:
+        games_dir = get_default_games_dir()
+    
+    games_dir = Path(games_dir)
+    if not games_dir.exists():
+        return {}
+    
+    games = {}
+    # Find all Z-machine game files (.z3, .z4, .z5, .z8)
+    for ext in ["*.z3", "*.z4", "*.z5", "*.z8"]:
+        for game_path in games_dir.glob(ext):
+            # Use stem (filename without extension) as game name
+            game_name = game_path.stem.lower()
+            games[game_name] = game_path
+    
+    return dict(sorted(games.items()))
+
+
+def list_available_games(games_dir: Optional[Path] = None) -> list[str]:
+    """Return a sorted list of available game names."""
+    return list(discover_games(games_dir).keys())
+
+
+class TextAdventureEnv:
+    """Wrapper around Jericho's FrotzEnv for text adventure games."""
+    
+    def __init__(self, game: str = "zork1", games_dir: Optional[str] = None):
+        """
+        Initialize the text adventure environment.
+        
+        Args:
+            game: Game name (e.g., 'zork1', 'advent', 'enchanter')
+                  Can also be a full path to a .z* file
+            games_dir: Directory containing game files (optional)
+        """
+        # Check if game is a full path
+        if os.path.isfile(game):
+            game_path = Path(game)
+            self.game = game_path.stem
+        else:
+            # Look up game by name
+            games_path = Path(games_dir) if games_dir else None
+            available_games = discover_games(games_path)
+            
+            if game.lower() not in available_games:
+                available = list(available_games.keys())[:20]
+                raise ValueError(
+                    f"Unknown game: {game}. "
+                    f"Available: {', '.join(available)}... "
+                    f"({len(available_games)} total)"
+                )
+            
+            game_path = available_games[game.lower()]
+            self.game = game.lower()
+        
+        self.env = FrotzEnv(str(game_path))
+        self.game_path = game_path
+        self._last_score = 0
+        self._history: list[tuple[str, str]] = []  # (action, observation) pairs
+    
+    def reset(self) -> GameState:
+        """Reset the game to the beginning."""
+        observation, info = self.env.reset()
+        self._last_score = 0
+        self._history = []
+        return self._make_game_state(observation, info, done=False, reward=0)
+    
+    def step(self, action: str) -> GameState:
+        """
+        Take an action in the game.
+        
+        Args:
+            action: The text command to execute (e.g., "go north", "take lamp")
+            
+        Returns:
+            GameState with the result of the action
+        """
+        observation, reward, done, info = self.env.step(action)
+        
+        # Track reward as score change
+        current_score = info.get('score', 0)
+        reward = current_score - self._last_score
+        self._last_score = current_score
+        
+        # Record history
+        self._history.append((action, observation))
+        
+        return self._make_game_state(observation, info, done, reward)
+    
+    def _make_game_state(self, observation: str, info: dict, done: bool, reward: int) -> GameState:
+        """Create a GameState from the environment info."""
+        # Try to get inventory and location (may fail without spacy)
+        try:
+            inventory = [str(obj) for obj in self.env.get_inventory()]
+        except Exception:
+            inventory = []
+        
+        try:
+            location = str(self.env.get_player_location())
+        except Exception:
+            location = "Unknown"
+        
+        return GameState(
+            observation=observation,
+            score=info.get('score', 0),
+            max_score=self.env.get_max_score(),
+            moves=info.get('moves', 0),
+            done=done,
+            reward=reward,
+            inventory=inventory,
+            location=location,
+        )
+    
+    def get_history(self) -> list[tuple[str, str]]:
+        """Get the history of (action, observation) pairs."""
+        return self._history.copy()
+    
+    def get_valid_actions(self) -> list[str]:
+        """
+        Get a list of valid actions for the current state.
+        Note: This requires spacy to be properly installed.
+        """
+        try:
+            return self.env.get_valid_actions()
+        except Exception:
+            # Return common actions if spacy isn't available
+            return [
+                "north", "south", "east", "west",
+                "up", "down", "look", "inventory",
+                "take all", "open mailbox", "read"
+            ]
+    
+    def save_state(self):
+        """Save the current game state."""
+        return self.env.get_state()
+    
+    def load_state(self, state):
+        """Load a previously saved game state."""
+        self.env.set_state(state)
+    
+    def get_walkthrough(self) -> list[str]:
+        """Get the walkthrough for the game (for debugging/comparison only)."""
+        return self.env.get_walkthrough()
+
+
+# Alias for backwards compatibility
+ZorkEnvironment = TextAdventureEnv
+
+
+# Example usage
+if __name__ == "__main__":
+    import sys
+    
+    # List available games
+    games = list_available_games()
+    print(f"Available games ({len(games)} total):")
+    print(f"  {', '.join(games[:15])}...")
+    print()
+    
+    # Use command line arg or default to zork1
+    game = sys.argv[1] if len(sys.argv) > 1 else "zork1"
+    
+    env = TextAdventureEnv(game)
+    state = env.reset()
+    
+    print(f"=== {env.game.upper()} ===")
+    print(f"Max Score: {state.max_score}")
+    print(f"\n{state.observation}")
+    print(f"\nValid actions: {env.get_valid_actions()[:10]}...")
+    
+    # Try a few actions
+    for action in ["look", "inventory"]:
+        print(f"\n> {action}")
+        state = env.step(action)
+        print(state.observation)
+        print(f"Score: {state.score}, Reward: {state.reward}")

mcp_server/README.md

@@ -0,0 +1,83 @@
+# Zork MCP Server
+
+This directory contains an MCP (Model Context Protocol) server that exposes Zork game tools to LLM agents.
+
+## Overview
+
+The MCP server wraps the Jericho Zork environment and provides tools that any MCP-compatible agent (like Mini SWE Agent) can use to play the game.
+
+## Tools Available
+
+| Tool | Description |
+|------|-------------|
+| `play_action(action)` | Execute a game command (e.g., "north", "take lamp") |
+| `memory()` | Get current state summary (location, score, recent actions) |
+| `get_map()` | View explored locations and connections |
+| `inventory()` | Check items you're carrying |
+| `valid_actions()` | Get hints on available commands |
+| `reset_game(game)` | Start over with zork1, zork2, or zork3 |
+| `hint()` | Get contextual hints for your situation |
+
+## Resources
+
+The server also exposes MCP resources:
+- `zork://state` - Current game state
+- `zork://history` - Complete action history  
+- `zork://map` - Explored locations map
+
+## Running the Server
+
+### Standalone (for testing)
+```bash
+python mcp_server/zork_server.py
+```
+
+### With MCP Inspector (for debugging)
+```bash
+npx @modelcontextprotocol/inspector python mcp_server/zork_server.py
+```
+
+### With Mini SWE Agent
+```bash
+python play_zork.py
+```
+
+## Configuration
+
+The `mcp_config.json` file configures the server for use with MCP clients:
+
+```json
+{
+  "mcpServers": {
+    "zork": {
+      "command": "python",
+      "args": ["mcp_server/zork_server.py"]
+    }
+  }
+}
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│         MCP Client (Agent)              │
+│   (Mini SWE Agent / Claude / etc.)      │
+└──────────────────┬──────────────────────┘
+                   │ MCP Protocol (stdio)
+                   ▼
+┌─────────────────────────────────────────┐
+│         Zork MCP Server                 │
+│   (FastMCP - zork_server.py)            │
+│                                         │
+│   Tools: play_action, memory, map,      │
+│          inventory, valid_actions,      │
+│          reset_game, hint               │
+└──────────────────┬──────────────────────┘
+                   │
+                   ▼
+┌─────────────────────────────────────────┐
+│     Jericho + Frotz                     │
+│   (Z-machine game interpreter)          │
+└─────────────────────────────────────────┘
+```

mcp_server/__init__.py

@@ -0,0 +1 @@
+# Text Adventure MCP Server

mcp_server/mcp_config.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "zork": {
+      "command": "python",
+      "args": ["mcp_server/zork_server.py"],
+      "cwd": "${workspaceFolder}"
+    }
+  }
+}

mcp_server/zork_server.py

@@ -0,0 +1,420 @@
+"""
+Text Adventure MCP Server - Exposes text adventure games via Model Context Protocol.
+
+This server allows any MCP-compatible agent to play Zork and other text adventure 
+games using tools for game actions, memory, mapping, and inventory.
+
+Uses FastMCP for simple, Pythonic MCP server implementation.
+
+Usage:
+    # Run directly (stdio transport) - default game is zork1
+    python mcp_server/zork_server.py
+    
+    # Run with a different game
+    GAME=zork2 python mcp_server/zork_server.py
+    GAME=advent python mcp_server/zork_server.py
+    GAME=enchanter python mcp_server/zork_server.py
+    
+    # Use with FastMCP dev tools
+    fastmcp dev mcp_server/zork_server.py
+    
+    # Connect from an MCP client
+    from fastmcp import Client
+    async with Client("mcp_server/zork_server.py") as client:
+        result = await client.call_tool("play_action", {"action": "look"})
+"""
+
+import sys
+import os
+
+# Add parent directory to path to import games module
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from fastmcp import FastMCP
+from games.zork_env import TextAdventureEnv, list_available_games
+
+
+# Get game from environment variable (default: zork1)
+INITIAL_GAME = os.environ.get("GAME", "zork1")
+
+# Create the MCP server
+mcp = FastMCP("Text Adventure Server")
+
+
+class GameState:
+    """Manages the text adventure game state and exploration data."""
+    
+    def __init__(self, game: str = "zork1"):
+        self.game_name = game
+        self.env = TextAdventureEnv(game)
+        self.state = self.env.reset()
+        self.history: list[tuple[str, str]] = []
+        self.explored_locations: dict[str, set[str]] = {}  # location -> set of exits
+        self.current_location: str = self._extract_location(self.state.observation)
+    
+    def _extract_location(self, observation: str) -> str:
+        """Extract location name from observation (usually first line)."""
+        lines = observation.strip().split('\n')
+        return lines[0] if lines else "Unknown"
+    
+    def take_action(self, action: str) -> str:
+        """Execute a game action and return the result."""
+        self.state = self.env.step(action)
+        result = self.state.observation
+        
+        # Track history
+        self.history.append((action, result))
+        if len(self.history) > 50:
+            self.history = self.history[-50:]
+        
+        # Update map
+        new_location = self._extract_location(result)
+        if action in ["north", "south", "east", "west", "up", "down", 
+                      "enter", "exit", "n", "s", "e", "w", "u", "d"]:
+            if self.current_location not in self.explored_locations:
+                self.explored_locations[self.current_location] = set()
+            if new_location != self.current_location:
+                self.explored_locations[self.current_location].add(f"{action} -> {new_location}")
+        self.current_location = new_location
+        
+        return result
+    
+    def get_memory(self) -> str:
+        """Get a summary of current game state."""
+        recent = self.history[-5:] if self.history else []
+        recent_str = "\n".join([f"  > {a} → {r[:60]}..." for a, r in recent]) if recent else "  (none yet)"
+        
+        return f"""Current State:
+- Location: {self.current_location}
+- Score: {self.state.score} points
+- Moves: {self.state.moves}
+- Game: {self.game_name}
+
+Recent Actions:
+{recent_str}
+
+Current Observation:
+{self.state.observation}"""
+    
+    def get_map(self) -> str:
+        """Get a map of explored locations."""
+        if not self.explored_locations:
+            return "Map: No locations explored yet. Try moving around!"
+        
+        lines = ["Explored Locations and Exits:"]
+        for loc, exits in sorted(self.explored_locations.items()):
+            lines.append(f"\n* {loc}")
+            for exit_info in sorted(exits):
+                lines.append(f"    -> {exit_info}")
+        
+        lines.append(f"\n[Current] {self.current_location}")
+        return "\n".join(lines)
+    
+    def get_inventory(self) -> str:
+        """Get current inventory."""
+        items = self.state.inventory if hasattr(self.state, 'inventory') and self.state.inventory else []
+        
+        if not items:
+            return "Inventory: You are empty-handed."
+        
+        item_names = []
+        for item in items:
+            item_str = str(item)
+            # Handle Jericho's object format: "leaflet Parent4 Sibling0..."
+            # Look for "Parent" (case-insensitive) to find where metadata starts
+            item_lower = item_str.lower()
+            if "parent" in item_lower:
+                idx = item_lower.index("parent")
+                name = item_str[:idx].strip()
+                # Remove leading "obj123: " if present
+                if ":" in name:
+                    name = name.split(":", 1)[1].strip()
+                item_names.append(name)
+            elif ":" in item_str:
+                name = item_str.split(":")[1].strip()
+                item_names.append(name)
+            else:
+                item_names.append(item_str)
+        
+        return f"Inventory: {', '.join(item_names)}"
+    
+    def get_valid_actions(self) -> str:
+        """Get list of valid actions in current state."""
+        try:
+            valid = self.env.get_valid_actions() if hasattr(self.env, 'get_valid_actions') else []
+            if valid:
+                return f"Valid actions: {', '.join(valid[:20])}"
+        except Exception:
+            pass
+        return "Valid actions: Try standard commands like look, north, south, east, west, take <item>, open <thing>"
+
+
+# Global game state (initialized on first use)
+_game_state: GameState | None = None
+
+
+def get_game() -> GameState:
+    """Get or initialize the game state."""
+    global _game_state
+    if _game_state is None:
+        _game_state = GameState(INITIAL_GAME)
+    return _game_state
+
+
+# ============================================================================
+# MCP Tools
+# ============================================================================
+
+@mcp.tool()
+def play_action(action: str) -> str:
+    """
+    Execute a game action in the text adventure.
+    
+    Common commands:
+    - Movement: north, south, east, west, up, down, enter, exit (or n, s, e, w, u, d)
+    - Objects: take <item>, drop <item>, open <thing>, close <thing>, put <item> in <container>
+    - Look: look, examine <thing>, read <thing>
+    - Combat: attack <enemy> with <weapon>
+    - Light: turn on lamp, light match
+    - Other: wait, score, inventory
+    
+    Args:
+        action: The command to execute (e.g., 'north', 'take lamp', 'open mailbox')
+    
+    Returns:
+        The game's response to your action
+    """
+    game = get_game()
+    result = game.take_action(action)
+    
+    # Add score info if points were earned
+    score_info = ""
+    if game.state.reward > 0:
+        score_info = f"\n\n+{game.state.reward} points! (Total: {game.state.score})"
+    
+    done_info = ""
+    if game.state.done:
+        done_info = "\n\nGAME OVER"
+    
+    return result + score_info + done_info
+
+
+@mcp.tool()
+def memory() -> str:
+    """
+    Get a summary of the current game state.
+    
+    Returns your location, score, moves, recent actions, and current observation.
+    Use this to understand where you are and what happened recently.
+    Very useful for avoiding loops and tracking progress.
+    """
+    return get_game().get_memory()
+
+
+@mcp.tool()
+def get_map() -> str:
+    """
+    Get a map showing all locations you have explored and the connections between them.
+    
+    Useful for navigation and planning routes back to previous locations.
+    The map builds up as you explore more of the game world.
+    """
+    return get_game().get_map()
+
+
+@mcp.tool()
+def inventory() -> str:
+    """
+    Check what items you are currently carrying.
+    
+    Essential before trying to use, drop, or interact with items.
+    Most games have an inventory limit, so manage your items wisely.
+    """
+    return get_game().get_inventory()
+
+
+@mcp.tool()
+def valid_actions() -> str:
+    """
+    Get a list of valid actions available in the current game state.
+    
+    Helpful when stuck or unsure what commands the game accepts.
+    Note: This may not include all possible actions, just common ones.
+    """
+    return get_game().get_valid_actions()
+
+
+@mcp.tool()
+def reset_game(game: str = "zork1") -> str:
+    """
+    Reset the game to the beginning or switch to a different game.
+    
+    Use this to start over if you get stuck, die, or want to try a different game.
+    
+    Args:
+        game: Game name (e.g., 'zork1', 'zork2', 'advent', 'enchanter')
+              Use list_games() to see available options.
+    
+    Returns:
+        The initial game text
+    """
+    global _game_state
+    try:
+        _game_state = GameState(game)
+        return f"Game reset to {game}.\n\n{_game_state.state.observation}"
+    except ValueError as e:
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def list_games() -> str:
+    """
+    List all available text adventure games.
+    
+    Returns:
+        List of game names that can be passed to reset_game()
+    """
+    games = list_available_games()
+    return f"Available games ({len(games)} total):\n" + ", ".join(games)
+
+
+@mcp.tool()
+def hint() -> str:
+    """
+    Get a hint about what to do next based on your current situation.
+    
+    Provides general guidance without spoiling puzzle solutions.
+    """
+    game = get_game()
+    location = game.current_location.lower()
+    inv = game.get_inventory().lower()
+    observation = game.state.observation.lower()
+    
+    hints = []
+    
+    # Darkness detection (common in many games)
+    if "dark" in location or "dark" in observation or "pitch black" in observation:
+        hints.append("It's dangerous in the dark! You need a light source.")
+        hints.append("If you have a lamp, try 'turn on lamp'.")
+    
+    # Common items to look for
+    if "lamp" in observation and "lamp" not in inv:
+        hints.append("There's a lamp here - light sources are essential!")
+    if "lantern" in observation and "lantern" not in inv:
+        hints.append("There's a lantern here - you'll need light for dark areas!")
+    if "sword" in observation and "sword" not in inv:
+        hints.append("A sword might be useful for combat encounters.")
+    if "key" in observation and "key" not in inv:
+        hints.append("A key might unlock something important.")
+    
+    # Container hints
+    if any(word in observation for word in ["mailbox", "chest", "box", "container", "cabinet"]):
+        hints.append("Try opening containers to find hidden items.")
+    
+    # Door/window hints
+    if "door" in observation or "window" in observation:
+        hints.append("There might be a way in or out here. Try 'open' commands.")
+    
+    # General hints if nothing specific found
+    if not hints:
+        hints.append("Explore all directions: north, south, east, west, up, down.")
+        hints.append("Examine interesting objects with 'examine <thing>'.")
+        hints.append("Pick up useful items with 'take <item>'.")
+        hints.append("Open containers and read documents for clues.")
+    
+    return "Hints:\\n" + "\\n".join(f"  - {h}" for h in hints)
+
+
+# ============================================================================
+# MCP Resources
+# ============================================================================
+
+@mcp.resource("game://state")
+def get_state_resource() -> str:
+    """Current game state as a resource."""
+    return get_game().get_memory()
+
+
+@mcp.resource("game://history")
+def get_history_resource() -> str:
+    """Complete action history as a resource."""
+    game = get_game()
+    if not game.history:
+        return "No actions taken yet."
+    lines = [f"{i+1}. {action} -> {result[:80]}..." for i, (action, result) in enumerate(game.history)]
+    return "\n".join(lines)
+
+
+@mcp.resource("game://map")
+def get_map_resource() -> str:
+    """Explored map as a resource."""
+    return get_game().get_map()
+
+
+# ============================================================================
+# Game Prompt (for agents)
+# ============================================================================
+
+GAME_PROMPT = """You are playing a classic text adventure game.
+
+## YOUR GOAL
+Explore the world, solve puzzles, collect treasures, and maximize your score.
+
+## VALID COMMANDS (use ONLY these exact verbs)
+
+Movement:
+  north, south, east, west, up, down (or n, s, e, w, u, d)
+  enter, exit, climb, cross, go <direction>
+
+Looking:
+  look, examine <thing>, look at <thing>, look in <thing>, read <thing>
+
+Objects:
+  take <item>, drop <item>, pick up <item>
+  open <thing>, close <thing>, unlock <thing> with <key>
+  put <item> in <container>, give <item> to <person>
+
+Light:
+  turn on lamp, turn off lamp, light match
+
+Combat:
+  attack <enemy> with <weapon>, kill <enemy> with <weapon>
+
+Other:
+  inventory (or i), wait (or z), score
+  push <thing>, pull <thing>, move <thing>
+  tie <rope> to <thing>, eat <food>, wave <item>
+
+## FORBIDDEN VERBS (these will NOT work):
+  check, inspect, search, investigate, grab, pick, use, interact,
+  go to, walk to, head to, travel, proceed
+
+## STRATEGY TIPS
+1. Explore systematically - check all directions
+2. Read everything - open containers, read documents, examine objects
+3. Use get_map() to track explored locations
+4. Light is essential - find a light source before dark areas!
+5. Manage inventory - you can only carry limited items
+
+## GETTING STARTED
+1. Call memory() to see your current state
+2. Explore your starting area thoroughly
+3. Pick up useful items (light sources, weapons, keys)
+
+Good luck!
+"""
+
+
+def get_game_prompt(game: str = "zork1") -> str:
+    """Get the system prompt for playing text adventures."""
+    prompt = GAME_PROMPT
+    prompt += f"\n\nNote: Currently playing {game}. Use list_games() to see all 57 available games."
+    return prompt
+
+
+# ============================================================================
+# Main
+# ============================================================================
+
+if __name__ == "__main__":
+    mcp.run()

requirements.txt

@@ -1 +1,14 @@
-gradio>=4.0.0
+# Core dependencies
+jericho
+python-dotenv
+
+# LLM providers
+huggingface_hub
+openai
+anthropic
+
+# MCP Server
+fastmcp
+
+# Function calling (optional, for the alternative approach)
+langchain-core

run_agent.py

@@ -0,0 +1,352 @@
+#!/usr/bin/env python3
+"""
+Unified Text Adventure Agent Runner
+
+Run different types of LLM agents to play text adventure games:
+  - react:     Basic ReAct agent with HuggingFace models
+  - function:  Function-calling controller (API-based or text-based)
+  - mcp:       MCP ReAct agent using FastMCP Client
+
+Usage:
+    python run_agent.py --mode react
+    python run_agent.py --mode function
+    python run_agent.py --mode mcp
+
+Examples:
+    # Run the basic ReAct agent
+    python run_agent.py --mode react
+
+    # Run the function-calling controller (API-based)
+    python run_agent.py --mode function
+
+    # Run the function-calling controller (text-based, works with any model)
+    python run_agent.py --mode function --simple
+
+    # Run with MCP ReAct agent (uses FastMCP Client)
+    python run_agent.py --mode mcp
+    
+    # Play a different game
+    python run_agent.py --mode mcp --game advent
+"""
+
+import argparse
+import sys
+import os
+import time
+from pathlib import Path
+
+# Add games module to path for discovering available games
+sys.path.insert(0, str(Path(__file__).parent))
+from games.zork_env import list_available_games, TextAdventureEnv
+
+
+# =============================================================================
+# Mode: ReAct Agent
+# =============================================================================
+
+def run_react_agent(args):
+    """Run the basic ReAct agent."""
+    from agents.react_agent import ReActAgent, ReActConfig
+    
+    print("\n[ReAct] Running ReAct Agent")
+    print(f"   Game: {args.game}")
+    print(f"   Model: {args.model}")
+    print()
+    
+    env = TextAdventureEnv(args.game)
+    config = ReActConfig(verbose=args.verbose, model=args.model)
+    agent = ReActAgent(config)
+    
+    return run_game_loop(env, agent, args.max_steps, args.verbose)
+
+
+def run_game_loop(env, agent, max_steps: int, verbose: bool) -> dict:
+    """Common game loop for ReAct-style agents."""
+    state = env.reset()
+    agent.reset()
+    
+    print("=" * 60)
+    print(f"{env.game.upper()} - Starting Game")
+    print(f"Max Score: {state.max_score}")
+    print("=" * 60)
+    print(f"\n{state.observation}\n")
+    
+    start_time = time.time()
+    step = 0
+    
+    try:
+        for step in range(1, max_steps + 1):
+            print(f"\n{'─' * 40}")
+            print(f"Step {step}")
+            print("─" * 40)
+            
+            action = agent.choose_action(state.observation, state)
+            print(f"\n> {action}")
+            
+            state = env.step(action)
+            print(f"\n{state.observation}")
+            
+            if state.reward > 0:
+                print(f"\n+{state.reward} points! (Total: {state.score}/{state.max_score})")
+            elif state.reward < 0:
+                print(f"\n{state.reward} points! (Total: {state.score}/{state.max_score})")
+            else:
+                print(f"\nScore: {state.score}/{state.max_score}")
+            
+            agent.update_history(action, state.observation, state)
+            
+            if state.done:
+                print("\n" + "=" * 60)
+                print("GAME OVER!")
+                break
+    
+    except KeyboardInterrupt:
+        print("\n\nGame interrupted by user")
+    
+    elapsed_time = time.time() - start_time
+    return print_summary(env.game, state, step, elapsed_time)
+
+
+# =============================================================================
+# Mode: MCP ReAct Agent
+# =============================================================================
+
+def run_mcp_agent(args):
+    """Run MCP ReAct Agent using FastMCP Client."""
+    import asyncio
+    from agents.mcp_react_agent import MCPReActAgent, MCPAgentConfig
+    
+    print("\n[MCP] Running MCP ReAct Agent with FastMCP")
+    print(f"   Game: {args.game}")
+    print(f"   Model: {args.model}")
+    print(f"   Server: mcp_server/zork_server.py")
+    print()
+    
+    config = MCPAgentConfig(verbose=args.verbose, model=args.model, game=args.game)
+    agent = MCPReActAgent("mcp_server/zork_server.py", config)
+    
+    return asyncio.run(agent.run(max_steps=args.max_steps))
+
+
+# =============================================================================
+# Mode: Function Calling
+# =============================================================================
+
+def run_function_calling(args):
+    """Run the function-calling controller."""
+    # Import the appropriate controller
+    sys.path.insert(0, str(Path(__file__).parent / "function_calling"))
+    from tools import add_to_history
+    
+    if args.simple:
+        from simple_controller import SimpleController
+        print("\n[Function] Running Function Calling Controller (text-based)")
+        controller = SimpleController(model=args.model)
+    else:
+        from controller import FunctionCallingController
+        print("\n[Function] Running Function Calling Controller (API-based)")
+        controller = FunctionCallingController(model=args.model)
+    
+    print(f"   Game: {args.game}")
+    print(f"   Model: {args.model}")
+    print()
+    
+    env = TextAdventureEnv(args.game)
+    state = env.reset()
+    
+    print("=" * 60)
+    print(f"{args.game.upper()} - Function Calling Mode")
+    print("=" * 60)
+    print(f"\n{state.observation}\n")
+    
+    start_time = time.time()
+    step = 0
+    
+    try:
+        for step in range(1, args.max_steps + 1):
+            print(f"\n{'─' * 50}")
+            print(f"Step {step}/{args.max_steps} | Score: {state.score}")
+            print("─" * 50)
+            
+            action = controller.get_action(state.observation, state)
+            print(f"\n> ACTION: {action}")
+            
+            state = env.step(action)
+            add_to_history(action, state.observation)
+            
+            print(f"\n{state.observation}")
+            
+            if state.reward > 0:
+                print(f"\n+{state.reward} points!")
+            
+            if state.done:
+                print("\nGAME OVER!")
+                break
+    
+    except KeyboardInterrupt:
+        print("\n\nGame interrupted by user")
+    
+    elapsed_time = time.time() - start_time
+    return print_summary(args.game, state, step, elapsed_time)
+
+
+# =============================================================================
+# Common Utilities
+# =============================================================================
+
+def print_summary(game: str, state, step: int, elapsed_time: float) -> dict:
+    """Print game summary and return results dict."""
+    print("\n" + "=" * 60)
+    print("GAME SUMMARY")
+    print("=" * 60)
+    print(f"Game: {game}")
+    print(f"Final Score: {state.score}/{state.max_score} ({100*state.score/state.max_score:.1f}%)")
+    print(f"Total Moves: {state.moves}")
+    print(f"Steps Taken: {step}")
+    print(f"Time Elapsed: {elapsed_time:.1f} seconds")
+    print("=" * 60)
+    
+    return {
+        "game": game,
+        "final_score": state.score,
+        "max_score": state.max_score,
+        "score_percentage": 100 * state.score / state.max_score,
+        "moves": state.moves,
+        "steps": step,
+        "elapsed_time": elapsed_time,
+        "game_over": state.done,
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Run an LLM agent to play text adventure games",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Modes:
+  react     Basic ReAct agent (direct game interaction)
+  function  Function-calling controller (use --simple for text-based)
+  mcp       MCP ReAct agent using FastMCP Client (recommended)
+
+Examples:
+  python run_agent.py --mode react
+  python run_agent.py --mode function
+  python run_agent.py --mode function --simple  # text-based, any model
+  python run_agent.py --mode mcp                # MCP with FastMCP
+  python run_agent.py --mode mcp --game advent  # Play different game
+  python run_agent.py --mode mcp --model google/gemma-2-2b-it
+        """
+    )
+    
+    # Get available games for help text
+    available_games = list_available_games()
+    game_help = f"Game to play (default: zork1). {len(available_games)} games available."
+    
+    parser.add_argument(
+        "--mode", "-m",
+        type=str,
+        default="react",
+        choices=["react", "function", "mcp"],
+        help="Which agent mode to use (default: react)"
+    )
+    parser.add_argument(
+        "--game", "-g",
+        type=str,
+        default="zork1",
+        help=game_help
+    )
+    parser.add_argument(
+        "--list-games",
+        action="store_true",
+        help="List all available games and exit"
+    )
+    parser.add_argument(
+        "--max-steps", "-n",
+        type=int,
+        default=100,
+        help="Maximum number of steps to run (default: 100)"
+    )
+    parser.add_argument(
+        "--model",
+        type=str,
+        default=None,
+        help="Model to use (default: meta-llama/Llama-3.2-3B-Instruct)"
+    )
+    parser.add_argument(
+        "--verbose", "-v",
+        action="store_true",
+        help="Show detailed reasoning from the agent"
+    )
+    parser.add_argument(
+        "--simple",
+        action="store_true",
+        help="Use text-based function calling (works with any model, only for --mode function)"
+    )
+    
+    args = parser.parse_args()
+    
+    # Handle --list-games
+    if args.list_games:
+        print(f"\nAvailable games ({len(available_games)} total):\n")
+        # Print in columns
+        cols = 5
+        for i in range(0, len(available_games), cols):
+            row = available_games[i:i+cols]
+            print("  " + "  ".join(f"{g:<15}" for g in row))
+        print()
+        sys.exit(0)
+    
+    # Validate game choice
+    if args.game.lower() not in available_games:
+        print(f"\nError: Unknown game '{args.game}'")
+        print(f"Use --list-games to see {len(available_games)} available options.")
+        sys.exit(1)
+    
+    # Get default model from environment
+    default_model = os.getenv("HF_MODEL", "meta-llama/Llama-3.2-3B-Instruct")
+    
+    # Set model if not specified
+    if args.model is None:
+        args.model = default_model
+    
+    print("\n" + "=" * 60)
+    print("Text Adventure LLM Agent Runner")
+    print("=" * 60)
+    print(f"Mode: {args.mode}" + (" (simple)" if args.simple else ""))
+    print(f"Game: {args.game}")
+    print(f"Max Steps: {args.max_steps}")
+    print(f"Model: {args.model}")
+    print(f"Verbose: {args.verbose}")
+    
+    # Run the selected mode
+    try:
+        if args.mode == "react":
+            results = run_react_agent(args)
+        elif args.mode == "function":
+            results = run_function_calling(args)
+        elif args.mode == "mcp":
+            results = run_mcp_agent(args)
+        else:
+            print(f"Unknown mode: {args.mode}")
+            sys.exit(1)
+            
+    except FileNotFoundError as e:
+        print(f"\n[Error] {e}")
+        sys.exit(1)
+    except ValueError as e:
+        print(f"\n[Error] {e}")
+        print("\nTo fix this:")
+        print("1. Copy .env.example to .env")
+        print("2. Add your HuggingFace token (HF_TOKEN)")
+        sys.exit(1)
+    except ImportError as e:
+        print(f"\n[Import Error] {e}")
+        print("\nMake sure to install dependencies:")
+        print("  pip install -r requirements.txt")
+        sys.exit(1)
+    
+    return results
+
+
+if __name__ == "__main__":
+    main()

spaces_requirements.txt

@@ -0,0 +1 @@
+gradio>=4.0.0