garbro-mcp

A modern TypeScript toolkit for parsing and extracting ADV/Galgame resource formats. The project uses GARbro as a format and algorithm reference while providing independent, streaming implementations of its core API, CLI, and MCP server.

The project currently includes archive support for:

• standard, unencrypted KiriKiri XP3 archives;

• Active Soft ADPACK32 archives, including CP932 filenames;

• Favorite View Point v2 BIN archives (BIN/FVP).

The XP3 implementation supports:

• archive detection and metadata inspection;

• raw and zlib-compressed indexes, including continued indexes;

• raw and zlib-compressed multi-segment files;

• listing, single-entry extraction, and complete archive extraction through the CLI and MCP;

• listing protected entries, with an explicit unsupported-feature error on extraction.

Game-specific XP3 encryption, obfuscated indexes, PEXP3/EXE-embedded archives, and archive creation are not currently supported.

Requirements and installation

• Node.js 24 or newer

• pnpm 11

pnpm install
pnpm build
pnpm check

All workspace packages are private:

packages/core      bigint binary I/O, format interfaces, registry, safe extraction
packages/codecs    reusable codecs
packages/formats   engine and format implementations
packages/cli       command-line interface
packages/mcp       MCP stdio server

Related MCP server: Mcp7zOp

CLI

After building, invoke the CLI directly with Node:

node packages/cli/dist/index.js formats
node packages/cli/dist/index.js detect data.xp3 --json
node packages/cli/dist/index.js list data.xp3
node packages/cli/dist/index.js extract-entry data.xp3 0 --output extracted
node packages/cli/dist/index.js extract-archive data.xp3 --output extracted

Extraction refuses to overwrite existing files by default. Add --overwrite explicitly to replace regular files. Absolute archive paths, path traversal, Windows alternate data streams and device names, and symbolic-link destinations are always rejected.

MCP

The server uses stdio. Standard output is reserved for protocol messages, while diagnostics are written to standard error.

{
  "mcpServers": {
    "garbro": {
      "command": "node",
      "args": ["C:/path/to/garbro-mcp/packages/mcp/dist/index.js"]
    }
  }
}

The following tools are available:

• detect_archive

• list_entries

• extract_entry

• extract_archive

• list_formats

MCP tools return structured metadata and local paths only. All bigint values are encoded as decimal strings, and large Base64 payloads are never returned.

Tests and differential validation

pnpm test
pnpm test:differential -- --archive fixtures/private/sample.xp3 --reference fixtures/private/garbro-output

The regular test suite uses deterministic, redistributable synthetic fixtures committed to the repository. Differential tests compare this project's output with a private reference directory extracted by GARbro, matching path, size, and SHA-256. fixtures/private/ is excluded from version control.

See docs/formats/xp3.md for XP3 format notes, implementation sources, and known limitations. See docs/support.md for the generated GARbro compatibility baseline, status definitions, and current migration progress.