# torch-mcp

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![MCP Protocol](https://img.shields.io/badge/MCP-2024--11--05-green.svg)](https://modelcontextprotocol.io)
[![HarbourMasters/Torch](https://img.shields.io/badge/Torch-72960ca-orange.svg)](https://github.com/HarbourMasters/Torch)
[![Distro: Arch & Ubuntu](https://img.shields.io/badge/Distro-Arch%20%7C%20Ubuntu-purple.svg)](#installation)

**torch-mcp** is a production Model Context Protocol (MCP) server for [HarbourMasters/Torch](https://github.com/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`](https://github.com/HarbourMasters/Torch/commit/72960ca16f4723f96aaf4037b76072c230af8c11).

---

## ⚡ Recommended: Set Up Your `CLAUDE.md`

We strongly recommend copying [`CLAUDE.md`](./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.

---

## 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

```bash
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:

```bash
./install.sh --build-torch
```

---

## Claude Desktop & Claude Code Setup

### Claude Desktop
Add to your `~/.claude/claude_desktop_config.json`:

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

### Claude Code CLI
```bash
claude mcp add torch torch-mcp
```

---

## MCP Tools Catalog

| Tool | Purpose | Key Parameters |
|---|---|---|
| `torch_capabilities` | Inspect Torch binary, registered CLI subcommands, compiled modules, and known caveats | `subcommand`, `torch_path` |
| `torch_validate_project` | Pre-flight check: ROM SHA1 checksum, `config.yml` match, output write permissions | `rom_path`, `srcdir`, `destdir`, `single_yaml` |
| `torch_export_archive` | Extract ROM assets into `.o2r` (ZIP archive) or `.otr` (StormLib) | `rom_path`, `format`, `srcdir`, `destdir`, `version`, `single`, `additional_files` |
| `torch_export_code` | Export decompiled C source code representation of assets | `rom_path`, `srcdir`, `destdir`, `verbose`, `single` |
| `torch_export_headers` | Generate C asset headers (`--otr` for OTR/O2R style) | `rom_path`, `srcdir`, `destdir`, `otr` |
| `torch_export_modding` | Export editable assets and `modding.yml` (raw or `--xml`) | `rom_path`, `srcdir`, `destdir`, `xml` |
| `torch_import_modding` | Import edited assets back into `code`, `otr`, `o2r`, or `header` | `mode`, `rom_path`, `srcdir`, `destdir`, `verbose` |
| `torch_pack_archive` | Pack existing directory into `.o2r` or `.otr` archive (no ROM needed) | `folder`, `target`, `format`, `version` |
| `torch_bk64_hashes` | Generate Banjo-Kazooie asset table hashes from ROM offset 0x5E90 | `rom_path`, `output_path` |
| `torch_diagnose_binary` | Explains upstream `torch binary` bug and provides working alternatives | `rom_path` |
| `torch_render_sequences` | Headless audio rendering: outputs 32kHz 16-bit PCM WAV sequence driver previews | `rom_path`, `wav_outdir`, `filter` |
| `torch_parse_config` | Parse and inspect `config.yml` games, GBI settings, output paths, and segments | `config_path` |

---

## 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**:
   ```json
   {
     "name": "torch_validate_project",
     "arguments": {
       "rom_path": "/path/to/baserom.z64",
       "srcdir": "/path/to/project",
       "destdir": "/path/to/output"
     }
   }
   ```
2. **Export O2R Resource Archive**:
   ```json
   {
     "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:

```bash
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.