# GARBro formats for agents

[![npm version](https://img.shields.io/npm/v/garbro-mcp.svg)](https://www.npmjs.com/package/garbro-mcp)

garbro-mcp lets coding agents inspect and extract supported ADV/Galgame resource files. It is a
Model Context Protocol (MCP) server backed by independent TypeScript implementations of formats and
codecs documented by [GARBro](https://github.com/morkt/GARBro).

[Tool reference](docs/tool-reference.md) | [Configuration](docs/configuration.md) | [Troubleshooting](docs/troubleshooting.md) | [Format support](docs/support.md) | [Design principles](docs/design-principles.md)

> [!WARNING]
> This project is under active development. Format coverage, extraction behavior, and MCP contracts
> may change between experimental releases.

## Key features

- **Discover supported resources:** Scan game directories and identify known archives, images,
  audio, and scripts with validation evidence.
- **Select the data that matters:** Filter archive entries by path, compression, encryption, and
  conservative media category.
- **Extract safely:** Every extraction task preflights destinations and budgets, writes into an
  isolated expiring temporary directory, and preserves source game files.
- **Handle long operations:** Scans, inspections, and extractions all run as background tasks with
  progress, cancellation, and one consistent control interface.
- **Verify automatically:** Extraction reopens every output, checks its size and SHA-256, inspects
  WAV or Ogg structure, and saves complete evidence without an extra agent step.

## Product boundary

garbro-mcp is resource-access infrastructure. It does not reverse-engineer game logic, adapt
unknown engines, decompile executables, or infer relationships such as character-to-voice ownership.
Those tasks remain with the calling agent, a specialized analysis tool, or the user.

Entry categories such as `audio` and `image` describe file media types. They are not claims about a
resource's role in the game. When the available evidence is insufficient, the server reports
`unknown`.

## Requirements

- Node.js 24 or newer
- Read access to the game directory selected in the conversation

## Getting started

Run the published package directly with npx; no repository checkout or global installation is
required:

```shell
npx --yes garbro-mcp@latest --version
npx --yes garbro-mcp@latest --doctor --json
```

Configure your MCP client to start the same command over stdio:

```json
{
  "mcpServers": {
    "garbro": {
      "command": "npx",
      "args": ["--yes", "garbro-mcp@latest"]
    }
  }
}
```

On Windows, use `npx.cmd` if the MCP client does not resolve command shims. For reproducible
environments, pin an exact release such as `garbro-mcp@0.1.0-beta.1` instead of following the
`latest` tag.

Global npm installation and versioned portable bundles remain available for offline or
centrally-managed environments. See [distribution](docs/distribution.md) for those alternatives.

See [configuration](docs/configuration.md) for temporary-directory overrides, source-checkout
setup, and the filesystem policy.

### Your first prompt

Give the game path and desired resources in the request. Delivery is a separate agent action:

```text
Scan the Rewrite game at D:/Games/Rewrite. Identify archives containing audio entries, extract the
audio to temporary storage, and report any extraction or verification failures. Do not modify any
game files. After I review the result, copy the selected files to D:/Exports/Rewrite-audio.
```

The agent submits `scan`, `inspect`, and `extract` tasks through `submit_task`, then uses
`get_task`'s server-side wait. It does not sleep or guess polling intervals. Planning and
post-extraction verification are mandatory internal extraction phases.
The MCP does not choose a permanent destination or copy artifacts there; the calling agent follows
the user's delivery instruction after extraction.

## Tools

See the complete [tool reference](docs/tool-reference.md) for the three task-control tools, task
types, selection modes, budgets, automatic verification, reports, and lifecycle states.

## Format documentation

Format-specific documentation remains a first-class part of this project:

- [Support status and compatibility methodology](docs/support.md)
- [Individual format notes](docs/formats/)
- [Deferred formats and missing prerequisites](docs/deferred-formats.md)
- [GARBro inventory](docs/garbro-inventory.json)
- [Private test-data targets](docs/test-data-targets.md)

Development setup and release procedures are documented in
[development](docs/development.md) and [distribution](docs/distribution.md).

## GARBro reference

This project uses GARBro as a behavioral reference for resource formats and decoding algorithms. It
is an independent TypeScript reimplementation and is not affiliated with, endorsed by, or a
distribution of GARBro. Source attribution and applicable licenses are recorded with each format
implementation and in the format documentation.