HytaleDocsMCP

A high-performance Model Context Protocol (MCP) server designed to decompile, index, and expose the Hytale game engine source code. This project enables AI systems (like Cursor, Windsurf, or custom LLM agents) to have a deep, authoritative understanding of Hytale's internal APIs, class structures, and logic.

Important

This tool requires a valid HytaleServer.jar. It does not provide the game binaries.

---

✨ Features

• 🔍 Real-time Decompilation: Automatically decompiles JAR files using the high-accuracy Vineflower decompiler.
• ⚡ Turbo Indexing: High-performance full-text search and metadata indexing powered by PostgreSQL.
• 🧠 AI-Optimized: Exposes searchable resources and tools specifically tuned for LLM discovery workflows.
• 🛡️ Smart Caching: Hash-based change detection ensures decompilation only happens when the JAR is updated.
• 📦 Optional Asset.zip indexing: Index game asset paths and full-text search over .ui files from Asset.zip (stream-only; no full extract). Configure [assets] zip_path to enable.
• 🌐 Flexible Deployment: Optimized for HTTP (SSE) transport, with fallback support for stdio.

---

🚀 Quick Start

1. Prerequisites

• Rust: Install Rust (latest stable)
• Java 17+: Required for the Vineflower decompiler.
• Hytale JAR: Place your HytaleServer.jar in the project root (or configure the path).

2. Build the Project

# Build for release
cargo build --release

The compiled binary will be located at ./target/release/hytale-docs-mcp (or .exe on Windows).

3. Run the Server

HytaleDocsMCP is optimized for HTTP (SSE) mode, providing better stability and session management.

# Start the HTTP server (Recommended)
./target/release/hytale-docs-mcp serve

# FALLBACK: Start in stdio mode (Direct integration)
./target/release/hytale-docs-mcp stdio

---

🛠️ Configuration

HytaleDocsMCP can be configured via config.toml, Environment Variables, or CLI arguments.

Example config.toml

[decompiler]
jar_path = "%APPDATA%/Hytale/install/release/package/game/latest/Server/HytaleServer.jar"
output_dir = "%APPDATA%/hytale-docs-mcp/decompiled"
package_scope = "com.hypixel.hytale"  # Target package to index

[database]
type = "postgres"
url = "postgresql://user:password@localhost/hytale_docs"

[server]
bind = "127.0.0.1"
port = 3000

Tip

Use .env or system environment variables for sensitive settings like database credentials. Prefix them with HYTALE_ (e.g., HYTALE_DB_URL).

---

🤖 MCP Integration

Cursor / Windsurf

Add the following to your MCP configuration:

{
  "mcpServers": {
    "hytale-docs": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Stdio

Add the following to your MCP configuration:

{
  "mcpServers": {
    "hytale-docs": {
      "command": "C:/path/to/HytaleDocsMCP/target/release/hytale-docs-mcp.exe",
      "args": ["stdio"],
      "env": {
        "HYTALE_JAR_PATH": "C:/path/to/HytaleServer.jar"
      }
    }
  }
}

Tip

Use the Absolute Path: Always use absolute paths for the command and any environment variable overrides to ensure the AI can launch the server correctly.

---

🔧 CLI Reference

HytaleDocsMCP includes powerful management tools accessible via the binary:

Command	Description
serve	Start high-performance HTTP (SSE) server.
stdio	Start standard I/O server for agent integration.
status	Show JAR, decompiler, and indexer status.
db stats	Show indexing statistics (file/class/method counts).
db reset	Wipe the database and recreate the schema.
jar info	Show configured JAR and decompiler details.
jar check-update	Check for Vineflower updates.
asset index	Index Asset.zip (requires [assets] zip_path in config).
asset info	Show asset index stats (path count, .ui file count).
cache clear	Force re-decompilation by wiping the change-detection cache.

MCP tools include list_asset_paths (optional path/extension filter) and search_ui_files (full-text search over indexed .ui content). Asset UI files are exposed as asset:// resources.

---

📚 Documentation

For more detailed information, check out our documentation:

• 🏗️ Architecture: How the decompilation and indexing pipeline works.
• ⚙️ Detailed Configuration: Full list of options and environment variables.
• 🛠️ MCP Guide: Tips for using the search tools and resource URIs effectively.
• 📜 Changelog: Track recent improvements and version history.

---

🛡️ License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines on how to get started.