torch-mcp

torch-mcp is a production Model Context Protocol (MCP) server for HarbourMasters/Torch, the Nintendo 64 asset extractor, archive packer, and modding suite used in modern reverse-engineering PC ports (Ship of Harkinian, Star Fox 64, Paper Mario, etc.).

Audited against upstream commit 72960ca16f4723f96aaf4037b76072c230af8c11.

⚡ Recommended: Set Up Your CLAUDE.md

We strongly recommend copying CLAUDE.md into your project root or your global agent configuration (~/.claude/CLAUDE.md).

Key rules enforced in CLAUDE.md:

• Targeted Mid-Run Order Handling (No Collateral Process Killing): If the user asks for code changes during an active run, only kill the exact conflicting process. Never kill background builds, daemons, watchers, or servers without asking first!

• No Unauthorized Dependencies or Hand-Rolling: Prohibits agents from adding surprise packages or writing ad-hoc throwaway scripts when dedicated project CLI tools exist.

• Multi-Distro Compatibility: Guaranteed compatibility across Arch Linux (pacman) and Ubuntu/Debian (apt).

• Game Dev & Asset Pipeline Standards: Prevents recursive packing loops, verifies disk artifacts, and enforces direct argv array execution without shell quoting bugs.

Related MCP server: local-code-intel-mcp

Features

• Strict Stdio Isolation: Zero non-protocol data leaked to stdout. All diagnostics, progress bars, and subprocess outputs are safely routed to stderr or encapsulated inside JSON-RPC tool responses.

• Direct Argv Execution: Spawns torch using native argument arrays rather than /bin/sh -c strings, preventing shell injection and escaping issues with complex paths.

• Post-Run Artifact Verification: Because Torch can return exit code 0 on certain errors (e.g. missing config.yml or unmatched ROM hash), torch-mcp inspects disk artifacts and file sizes to guarantee actual success.

• Pre-Flight Validation: Computes ROM lowercase SHA-1 checksums, parses config.yml, checks game registration, and validates directory permissions before launching long extraction jobs.

• Upstream Caveat Protection:

  • Guards against the broken torch binary upstream command by offering safe alternatives (torch_export_archive with O2R or torch_export_modding).

  • Enforces 3-component uint16 version parsing (X.Y.Z, 0–65535).

  • Safeguards torch pack to prevent recursive packing if the output target is inside the input directory.

Installation

Prerequisites

• Node.js (>= 18)

• tmux (for persistent background worker execution)

• Linux (tested on Arch Linux and Ubuntu/Debian) or macOS

Automated Multi-Distro Installer

git clone https://github.com/CodeMasterCody3D/torch-mcp.git
cd torch-mcp
./install.sh

The installer will:

1. Detect your package manager (pacman on Arch, apt on Ubuntu/Debian, dnf on Fedora, brew on macOS).

2. Verify or automatically install tmux.

3. Symlink torch-mcp to ~/.local/bin/torch-mcp.

4. Run the automated test suite.

Optional: Compile Torch from Source

If Torch is not already installed on your system, install.sh can automatically clone, configure, and build it with Ninja and StormLib:

./install.sh --build-torch

Claude Desktop & Claude Code Setup

Claude Desktop

Add to your ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "torch": {
      "command": "torch-mcp",
      "env": {
        "TORCH_PATH": "/home/cody/.local/bin/torch"
      }
    }
  }
}

Claude Code CLI

claude mcp add torch torch-mcp

MCP Tools Catalog

Game Porting & Reverse Engineering Workflows

1. Tribes 2 & Torque Asset Porting Pipeline

When porting older games like Tribes 2 (Torque Game Engine) to modern engines or cross-compiling assets:

• Legacy Torque assets typically consist of:

  • 3D Shapes: .dts (DTS mesh hierarchy)

  • Interiors: .dif (CSG interior structures)

  • Terrain: .ter (heightmaps)

  • Missions: .mis & Scripts: .cs

  • Textures: .dds / .png

• Use torch_pack_archive to bundle converted game resources directly into .o2r or .otr virtual filesystems for modern ports.

• Use torch_validate_project to ensure all asset paths and manifests resolve cleanly before starting bulk conversions.

2. Standard N64 Extraction Walkthrough

1. Validate Pre-Flight:

   {
     "name": "torch_validate_project",
     "arguments": {
       "rom_path": "/path/to/baserom.z64",
       "srcdir": "/path/to/project",
       "destdir": "/path/to/output"
     }
   }

2. Export O2R Resource Archive:

   {
     "name": "torch_export_archive",
     "arguments": {
       "rom_path": "/path/to/baserom.z64",
       "format": "o2r",
       "srcdir": "/path/to/project",
       "destdir": "/path/to/output",
       "version": "1.0.0"
     }
   }

3. Modding Round-Trip:

   • Run torch_export_modding to dump editable assets into output/modding/.

   • Modify the textures or models in output/modding/.

   • Run torch_import_modding with mode o2r to re-inject modified assets into a fresh game archive.

Technical Audit Findings (Commit 72960ca)

1. torch binary Subcommand: Registered in CLI11, but its callback assigns ArchiveType::None. The Binary exporter switch rejects None, causing execution to fail. Use torch_export_archive with format o2r (which is a standard ZIP archive containing raw assets) or torch_export_modding instead.

2. Exit Code 0 on Missing Config: If config.yml is missing or the ROM SHA-1 does not match, Torch prints a warning to console and exits with code 0. torch-mcp performs pre-flight checks and verifies disk artifacts to prevent silent failures.

3. Target Isolation: In torch pack FOLDER TARGET ARCHIVE_TYPE, TARGET must never be inside FOLDER. The tool slices entry paths relative to the folder name length; placing the target inside the folder causes recursive self-packing corruption.

4. Log Levels: Torch uses CRITICAL log severity for normal extraction progress indicators. torch-mcp does not treat CRITICAL in logs as an automatic fatal error.

Testing

Run the test suite:

npm test
# or
node test/index.js

All 4 test suites cover:

• Path normalization, directory containment, and uint16 version checks.

• SHA-1 calculation and config.yml parser.

• Tool registry schemas, error guards, and capabilities probing.

• Full end-to-end JSON-RPC protocol over stdio.

License

MIT License. Copyright (c) 2026 Cody (CodeMasterCody3D). HarbourMasters/Torch is developed by the Harbour Masters team.