Integration Quest: A Workato RPG

Descend into the Legacy System Dungeons. Connect the disconnected. Automate the manual. Defeat the bugs that plague enterprise workflows.

A Workato-themed text-based RPG implemented as a Python MCP (Model Context Protocol) server. Battle through legacy systems, API errors, and enterprise chaos as an Integration Hero!

Table of Contents

• The Story

• Installation

• Playing the Game

• Character Classes

• Enemies

• Items

• Game Mechanics

• Project Structure

• Development

• Contributing

• License

• Credits

The Story

You are an Integration Hero, venturing into the depths of the Integration Dungeon where legacy systems lurk, APIs fail, and technical debt accumulates. Armed with your trusty HTTP Client and determination, you must connect the disconnected, transform the untransformed, and bring order to enterprise chaos.

Will you become a legendary Integration Engineer, mastering bulk operations? A powerful Recipe Builder, wielding formula transformations? A cunning API Hacker, finding workarounds for every obstacle? Or a resilient Support Engineer, recovering from any failure?

The choice is yours. The legacy systems await.

Installation

Prerequisites

• Python 3.11 or higher

• uv package manager

Setup

1. Install uv (if not already installed):

   # macOS and Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Windows
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Clone the repository:

   git clone https://github.com/MattCarpenter-Workato/workato-integration-quest.git
   cd workato-integration-quest

3. Install dependencies:

   uv sync

   Note: Package discovery warnings are safe to ignore.

Playing the Game

Quick Start

Choose your preferred play mode:

# Terminal Mode (Interactive CLI)
uv run python play.py

# Local MCP Server (for Claude Desktop)
uv run python server.py

# Remote MCP Server (HTTP)
uv run python remote_server.py

New Player Guide

First time playing? Use the AI Game Guide to learn the mechanics. Copy the contents of game_guide_prompt.md into your conversation with Claude when using the MCP server. The guide will teach you game mechanics, explain Workato concepts in context, and provide strategic advice tailored to your experience level.

Play Modes

Terminal Mode

Play directly in your terminal with an interactive command-line interface:

uv run python play.py

Example session:

>>> explore
🏛️ THE INTEGRATION HUB
You stand at the entrance...

>>> attack bug
🎲 Rolled 1d4: [3] = 3
⚔️ You hit Bug for 3 damage!

>>> status
📊 Alex the Mage - Level 1
❤️ Uptime: 90/90

Claude Desktop (MCP Server)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "integration-quest": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/workato-integration-quest",
        "run",
        "python",
        "server.py"
      ]
    }
  }
}

Important: Update the path to match your actual installation location.

Claude Code (CLI)

Add the MCP server to your Claude Code configuration:

claude mcp add integration-quest -- uv --directory /path/to/workato-integration-quest run python server.py

Or manually edit ~/.claude/settings.json:

{
  "mcpServers": {
    "integration-quest": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/workato-integration-quest",
        "run",
        "python",
        "server.py"
      ]
    }
  }
}

After configuration, restart Claude Code and the game tools will be available.

Remote MCP Server

Run the game as a remote MCP server accessible over HTTP:

uv run python remote_server.py

Connect via Claude Desktop:

{
  "mcpServers": {
    "integration-quest-remote": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8000/sse"]
    }
  }
}

Environment Variables:

FastMCP Cloud (Hosted)

Deploy Integration Quest to the cloud for free with FastMCP Cloud:

1. Fork this repository to your GitHub account

2. Sign up at fastmcp.cloud with GitHub

3. Create a new project with entrypoint: remote_server.py:mcp

4. Connect via: npx mcp-remote https://your-project.fastmcp.app/mcp

See DEPLOY_FASTMCP_CLOUD.md for detailed instructions.

Available Commands

Character Classes

Warrior (Integration Engineer)

"Process more. Process faster."

Skills:

• Bulk Upsert — Hit all enemies at once

• Force Sync — Ignore armor completely

• Throughput Surge — Take two actions per turn

Mage (Recipe Builder)

"Everything is just a transformation away."

Skills:

• Formula Transform — Rewrite enemy logic

• Lookup Table Strike — Guaranteed hit +50% damage

• Callable Recipe — Summon automation ally

Rogue (API Hacker)

"There's always a workaround."

Skills:

• Workaround — Bypass armor, double damage

• Rate Limit Dance — Evade all attacks

• Custom Connector — Exploit weaknesses for 3x damage

Cleric (Support Engineer)

"No system stays down on my watch."

Skills:

• Error Handler — Auto-revive from 0 HP (once per combat)

• Job Recovery — Restore 40% max HP

• Escalation — Call backup ally

Enemies

Common (Depth 1-3)

Uncommon (Depth 4-6)

Rare (Depth 7-9)

Bosses (Every 5th Depth)

Items

Weapons (Connectors)

Armor (Error Handlers)

Consumables

Game Mechanics

Stats (Workato Themed)

Room Types

Project Structure

workato-integration-quest/
├── server.py                 # FastMCP server + all 14 tools
├── play.py                   # Terminal mode CLI interface
├── remote_server.py          # Remote MCP server (HTTP/SSE)
├── config.py                 # Game configuration and constants
├── pyproject.toml            # Python project configuration
├── requirements.txt          # Python dependencies
├── game_guide_prompt.md      # Full AI guide system prompt
├── game_guide_prompt_short.md # Condensed guide prompt
├── models/
│   ├── hero.py               # Hero, stats, inventory
│   ├── combat.py             # Combat state, enemies
│   ├── world.py              # Room, dungeon map
│   └── items.py              # Weapons, armor, consumables
├── systems/
│   ├── combat.py             # Damage calc, turn order
│   ├── generation.py         # Procedural dungeon generation
│   ├── progression.py        # XP, leveling, skill unlocks
│   ├── effects.py            # Status effect processing
│   └── dice.py               # Dice rolling utilities
├── data/
│   ├── enemies.json          # 20+ enemy definitions
│   ├── items.json            # Weapons, armor, consumables
│   ├── descriptions.json     # Room templates
│   └── skills.json           # Class skills
└── tests/
    ├── test_dice.py          # Dice rolling unit tests
    └── test_progression.py   # Progression system tests

Development

Running Tests

# Run all function tests (31 tests)
uv run python test_all_functions.py

# Run unit tests with pytest
uv run pytest tests/

Adding Content

Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

Guidelines

• Follow existing code style and conventions

• Add tests for new features

• Update documentation as needed

• Keep commits focused and atomic

Ideas for Contributions

• New enemy types with unique mechanics

• Additional character classes

• New weapons, armor, and consumables

• Quality of life improvements

• Bug fixes and optimizations

License

This project is licensed under the MIT License. See the LICENSE file for details.

MIT License

Copyright (c) 2024 Matt Carpenter

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Credits

Built with:

• FastMCP 2.0 — Python MCP server framework

• Pydantic — Data validation

• uv — Fast Python package manager