# AssetHub

MCP server that searches 9 3D asset sites at once and shows the license and cost of every model, texture and HDRI.

Plug it into Claude Code (or any MCP client): your AI asks once, gets one ranked list from Sketchfab, Poly Haven, ambientCG, Poly Pizza, Kenney, Quaternius, Gazebo Fuel (Google Scanned Objects), NASA 3D Resources and the Tripo Studio public library, and downloads what you pick with a license file next to it.

[Leia em português](README.pt-BR.md)

[![License: MIT](https://img.shields.io/github/license/FFloriani/assethub)](LICENSE)
[![Node](https://img.shields.io/badge/node-%E2%89%A522.13-339933)](package.json)

[Why it exists](#why-it-exists) · [Sites](#sites) · [Install](#install) · [Connect](#connect-it-to-your-ai) · [Tools](#tools) · [Configuration](#configuration) · [Tests](#tests) · [Add a site](#add-a-site)

> The tool names, parameters and messages are in Portuguese (pt-BR). Your AI reads them fine and answers in the language you use.

<img src="docs/galeria-dragon.jpg" alt="AssetHub gallery for the search &quot;dragon&quot;: results from Tripo, Sketchfab and Google Scanned Objects side by side, each card with the source, the license (for example CC-BY, commercial use, credit required) and the download cost" width="720">

## Why it exists

- **The pain:** game assets are spread over many sites. Each one has its own search, its own license wording and its own download flow, so finding a usable dragon means opening five tabs and reading five license pages.
- **What changes here:** one search returns one list, interleaved across sites, with the license read for every item ("commercial use", "credit required", "NOT commercial", "check the terms"). Downloads come with a `LICENCA.txt` holding the author, the source and the credit line.
- **Paid downloads never happen by accident:** a download that costs credits returns the cost and your balance first, and only goes through on a second call with `aceitar_custo: true`. The daily limit is enforced in code, not in the prompt.
- **What it does not do:** it does not generate models, clean meshes or retopologize, and it does not certify licenses. It reports what each site says.

## What it does

- **One search, every site (`assethub_buscar`):** all sites are asked in parallel. A site that fails or times out shows up with its error instead of breaking the search. Results whose name contains your words come first.
- **License filter:** `uso: "comercial"` keeps only what allows a commercial game, and `uso: "cc0"` keeps only public domain. CC licenses are parsed into BY, NC, ND and SA, and editorial licenses count as not commercial.
- **Type filter:** `modelo` (models, including packs), `material` (PBR textures), `hdri`, `pack`.
- **Gallery:** every search writes an HTML page with thumbnails, license badges, cost, and filters by site, license and free.
- **Download with credit (`assethub_baixar`):** GLB, glTF with textures, FBX, OBJ, HDR or the site's zip, saved under `downloads/<site>/<item>/` with a `LICENCA.txt` that holds the exact credit line when the license requires one.
- **Cost guard:** the balance is read before and after every paid download, and the spend recorded is the measured one. `assethub_gastos` shows today's spend.
- **Memory (`assethub_historico`):** everything that showed up in past searches is stored locally in SQLite, so you can search it again without asking the sites.
- **Long downloads in parts:** a Quaternius pack hosted on Google Drive is fetched one file at a time, up to 40 s per call. The next call resumes where the last one stopped.

## Sites

| Site | What it has | License | Needs | Download |
|---|---|---|---|---|
| Tripo Studio (public library) | AI-generated models | Tripo's terms (unclear for third parties) | your site login cookie | **5 Tripo credits each**, even if the model is already exported |
| Sketchfab | downloadable models | per model (CC0, CC BY and variants, Standard) | search: nothing; download: API token | free |
| Poly Haven | models, textures, HDRIs | CC0 | nothing | free |
| ambientCG | PBR textures, HDRIs, a few models | CC0 | nothing | free (zip) |
| Poly Pizza | low poly models | CC0 or CC BY, per model | nothing (reads the site); an API key switches to the official API | free (GLB) |
| Kenney | game packs (3D, 2D, audio) | CC0 | nothing | free (zip of the pack) |
| Quaternius | model packs | CC0 for older packs (their License.txt says so); Quaternius Asset License v1.0 for newer ones | nothing | free: older packs from the public Google Drive folder, in the format you choose; newer ones from itch.io (zip) |
| Gazebo Fuel (Google Scanned Objects) | real objects, 3D scanned | per model (mostly CC BY 4.0) | nothing | free (zip with OBJ and textures) |
| NASA 3D Resources | spacecraft, probes, planets | free of copyright; NASA brand rules apply | nothing | free |

The Tripo connector uses the site's internal API with your login, not Tripo's paid API. [Tripo's terms](https://www.tripo3d.ai/terms) forbid automated software and scraping of the site: the risk is on the account that uses it.

## Install

Requires Node 22.13+ (tested on 24).

```bash
git clone https://github.com/FFloriani/assethub.git
cd assethub
npm install
npm run build
node dist/cli.js buscar "treasure chest"
```

The last command prints a JSON list (`total`, `fontes`, `achados`) and writes the gallery to `galerias/`. Tripo stays off until you add its login.

## Connect it to your AI

Claude Code (use your own path; on Windows, forward slashes work):

```bash
claude mcp add-json assethub '{"type":"stdio","command":"node","args":["/path/to/assethub/dist/index.js"]}' --scope user
```

Other MCP clients take the same command and argument in their JSON config:

```json
{
  "mcpServers": {
    "assethub": { "command": "node", "args": ["/path/to/assethub/dist/index.js"] }
  }
}
```

Then ask, for example: *"find me a low poly treasure chest I can use in a commercial game"*.

## Tools

| Tool | What it does |
|---|---|
| `assethub_buscar` | searches every site at once. Takes `consulta`, `tipo`, `uso`, `fontes`, `limite_por_fonte`, `limite_total` and `galeria`, and returns refs (`site:id`), license, cost, triangles, page and thumbnail |
| `assethub_ver` | details of one result by `ref` |
| `assethub_baixar` | downloads it and writes `LICENCA.txt`. A paid download only goes through with `aceitar_custo: true` |
| `assethub_fontes` | which sites are on, what is missing (key, token, login) and the balance of the paid ones |
| `assethub_historico` | searches what showed up before, offline |
| `assethub_galeria` | writes the gallery of a past search again |
| `assethub_gastos` | today's spend, the daily limit and the last downloads with the balance before and after |

## Configuration

Copy `config.exemplo.json` to `config.local.json`. The local file is ignored by git, because it holds logins.

| Key | What it is |
|---|---|
| `tripo.sessao` | the `ory_kratos_session` cookie from a logged-in Tripo Studio session. It lasts 30 days; the 15-minute token is renewed automatically |
| `tripo.dispositivo` | the `x-tripo-device-id` your browser sends |
| `sketchfab.token` | your API token from <https://sketchfab.com/settings/password> (only needed to download) |
| `polypizza.chave` | optional key from <https://poly.pizza/settings/api> |
| `pasta_downloads` | where downloads go (default: `downloads/` in this folder) |
| `limite_creditos_por_dia` | cap on paid credits per day, summed over all sites (default 25) |

Environment variables take precedence: `TRIPO_SESSION`, `SKETCHFAB_API_TOKEN`, `POLY_PIZZA_API_KEY`, `ASSETHUB_CONFIG`, `ASSETHUB_DOWNLOADS`, `ASSETHUB_BANCO`.

## Command line

The same actions without an AI, useful for testing:

```bash
node dist/cli.js buscar "wood planks" --tipo material --uso cc0
node dist/cli.js fontes
node dist/cli.js historico "dragon"
node dist/cli.js baixar polyhaven:Barrel_01 --formato gltf
node dist/cli.js gastos
```

A paid download needs `--aceitar-custo`.

## Tests

- `npm test`: 34 tests, offline. They cover license parsing, ranking, filters, the cost guard (including a paid download that fails midway), memory, the HTML readers and every connector with sample responses.
- `node scripts/testar-tudo.mjs`: 42 live checks through MCP, as an AI uses it. They cover search, details and a real download from every site, with each file checked by its first bytes, plus refusals, filters, history, gallery and two clients at once. It spends nothing.
- `node scripts/testar-download-pago.mjs tripo "<query>" --gastar`: the paid path end to end. **It spends credits.**

Last run (29 Oct 2026): 41 of 42 live checks passed ([report](docs/teste-completo-2026-10-29.txt)). The one left was a popular Quaternius pack on Google Drive, which Google answered with "Quota exceeded … it may take up to 24 hours". 47 of its 57 files came through and were checked.

<details>
<summary>Downloads opened in Blender</summary>

<img src="docs/downloads-no-blender.png" alt="Three downloads rendered in Blender: a Poly Haven barrel with 4 textures, the NASA Apollo Lunar Module and a tower piece from Kenney's Castle Kit" width="720">

</details>

## Troubleshooting

- **"o Tripo recusou: a conta está no limite de tarefas ao mesmo tempo":** a generation is running in your Tripo Studio. Wait for it to finish; Tripo cancels the charge of the refused attempt.
- **A download returns `parcial: true`:** Google Drive is rate limiting. Call `assethub_baixar` again with the same `ref` and folder later; it resumes.
- **"o site devolveu uma página … em vez do arquivo":** the site sent an error page (quota, bot check) instead of the file. Nothing was saved under the model's name.
- **Python or Blender hang with no output on Windows** (only for the helper scripts, not the server): a stuck WMI service makes Python 3.12+ wait forever in `platform.system()`. Run them with `PYTHONPATH=scripts/semwmi`; for Blender, add `--python-use-system-env`.

## Add a site

Each site is one file in `src/conectores/` implementing the `Conector` interface from `src/tipos.ts`. The step-by-step guide, which Claude Code can follow as a skill, is in [skill/assethub-novo-site/SKILL.md](skill/assethub-novo-site/SKILL.md). It covers the official API first, then a public HTML list, then a HAR recording turned into a client with [reverse-api-engineer](https://github.com/kalil0321/reverse-api-engineer).

## Status

Experimental (0.1.0), tested on Windows 11 with Node 24 and Claude Code. Sites change their pages without notice, so connectors may break; issues are welcome.

## Credits and license

The Poly Haven, ambientCG, Sketchfab, Poly Pizza, Kenney, Quaternius, Google Scanned Objects and NASA connectors are TypeScript ports of the MIT-licensed asset providers from [dcc-mcp](https://github.com/dcc-mcp), fixed where the sites had changed. Details in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

[MIT](LICENSE) © 2026 Felipe Floriani. The assets you download keep their own licenses.