API publique MGS Toolbox

Tout ce que montre le MGS Toolbox est disponible ici : 88 metals, 141 minerals, 350 ingredients, 54 potions, 58 gems, les règles de la Crafting Table, et le catalogue MGS Audio (pistes, compositeurs, albums, packs, taxonomie). Chaque élément porte url, la page à lier, et embed_url, une carte à intégrer en iframe. Les textes existent en anglais et en français.

Ce que vous pouvez construire

Démarrage rapide

curl "https://michaelghelfistudios.com/api/v1/search?q=mithral"
curl "https://michaelghelfistudios.com/api/v1/metals/mithral?lang=fr"
curl "https://michaelghelfistudios.com/api/v1/minerals?system=cubic&gem_quality=true&limit=5"
curl "https://michaelghelfistudios.com/api/v1/audio/tracks/random?genre=Combat&type=music"

Depuis un navigateur ou un bot, sans en-tête particulier (CORS ouvert) :

const res = await fetch('https://michaelghelfistudios.com/api/v1/ingredients/random?environment=swamp&lang=en');
const { data } = await res.json();
console.log(data.name, data.rarity, data.url);   // "Bog Iris", "uncommon", "https://…/apps/rerum/bog_iris"

Chaque réponse est une enveloppe :

{
  "success": true,
  "data": …,                       // un élément, un tableau ou un objet
  "meta": { "version": "v1", "lang": "en", "total": 141, "limit": 50, "offset": 0,
            "license": { "name": "…", "url": "…", "attribution": "…" } },
  "links": { "self": "…", "docs": "https://michaelghelfistudios.com/api/v1/docs" }
}

Conventions

Intégrations & oEmbed

Cartes

Chaque fiche, piste, artiste et album a une carte sur /apps/embed/{kind}/{id} (kinds : metal, mineral, ingredient, potion, gem, track, artist, album). Options : ?lang=fr, ?theme=light|dark (par défaut, le thème du visiteur). Le bouton « Partager » de chaque page d’encyclopédie copie ce code pour vous. Les minéraux de la Crystal Forge montrent leur spécimen rendu (aussi image_url dans l’API et thumbnail_url en oEmbed) ; les cartes de pistes jouent l’extrait de 30 secondes du site, l’API JSON elle-même ne renvoie toujours aucune URL audio.

<iframe src="https://michaelghelfistudios.com/apps/embed/metal/iron?lang=fr" width="100%" height="340"
        style="border:0;max-width:480px" loading="lazy" title="Iron — Metal Encyclopedia"></iframe>

Les cartes envoient leur hauteur à la page hôte, pour qu’une iframe s’ajuste à son contenu :

window.addEventListener('message', (e) => {
  if (e.data?.type !== 'mgs-embed') return;
  document.querySelectorAll('iframe').forEach((f) => { if (f.src === e.data.href) f.height = e.data.height; });
});

oEmbed

Collez le lien d’une page dans WordPress, Discord, Notion, Ghost, Discourse ou toute plateforme qui découvre oEmbed, et il devient la carte de lui-même : chaque page annonce https://michaelghelfistudios.com/api/v1/oembed?url=…. Les intégrateurs peuvent l’appeler directement :

curl "https://michaelghelfistudios.com/api/v1/oembed?url=https%3A%2F%2Fmichaelghelfistudios.com%2Fapps%2Fcrystal%2Fquartz&maxwidth=400"

Lecteur d’album

Les albums ont un vrai lecteur avec un extrait de chaque piste : https://michaelghelfistudios.com/audio/embed/{albumId} (450 px de haut). C’est ce qu’oEmbed renvoie pour une page d’album.

Encyclopédies entières

Les encyclopédies elles-mêmes acceptent d’être encadrées (/apps/metals/, /apps/crystal/, /apps/rerum/) ; c’est ainsi que le module Foundry VTT les affiche dans un monde.

Serveur MCP

Les mêmes catalogues sous forme de serveur MCP, pour les assistants IA et les agents : https://michaelghelfistudios.com/api/v1/mcp (Streamable HTTP, sans état, sans clé, lecture seule). Outils : search_encyclopedia, get_entry, list_entries, random_entry, list_facets, craft_rules, search_tracks, random_track, get_track, list_composers, list_albums, audio_taxonomy. Chaque résultat porte l’url des fiches et les instructions du serveur demandent à l’assistant de la citer.

Claude Code :

claude mcp add --transport http mgs-toolbox https://michaelghelfistudios.com/api/v1/mcp

Claude Desktop, Cursor, VS Code, Windsurf et la plupart des clients acceptent un serveur distant par URL dans leurs réglages MCP ; la forme JSON est :

{
  "mcpServers": {
    "mgs-toolbox": { "type": "http", "url": "https://michaelghelfistudios.com/api/v1/mcp" }
  }
}

Les clients qui ne parlent que stdio peuvent passer par npx mcp-remote https://michaelghelfistudios.com/api/v1/mcp. Le serveur est référencé dans le registre MCP officiel sous com.michaelghelfistudios/toolbox. Même limite de débit et mêmes conditions que l’API JSON.

Vos propres données

Vos villes Fantasy City Simulator et vos campagnes de la Crafting Table, depuis vos propres outils : un bot Discord qui poste la nourriture et l’or de la ville, une page de wiki qui liste ses habitants, un script qui exporte l’inventaire du groupe. En lecture seule, sous une clé API personnelle que vous créez dans le hub (menu → Clés API) et révoquez quand vous voulez.

Envoyez-la en jeton Bearer sur les routes /me, et nulle part ailleurs : elle n’est acceptée nulle part ailleurs.

curl -H "Authorization: Bearer mgsk_…" "https://michaelghelfistudios.com/api/v1/me/settlements"
curl -H "Authorization: Bearer mgsk_…" "https://michaelghelfistudios.com/api/v1/me/settlements/42/inhabitants?lang=fr"

Une clé porte les portées choisies à sa création : profile (qui vous êtes), fcs:read (villes, tableau de bord, habitants, campagnes), craft:read (les campagnes de la Crafting Table que vous menez et leurs inventaires ; Patreon, comme sur le site). Tout est en lecture seule.

Il n’y a pas d’audio sur cette surface, c’est voulu : une clé ne liste jamais les droits, ne télécharge jamais, ne diffuse jamais. Ce que vous pouvez faire avec le catalogue musical, c’est ce que les endpoints publics offrent à tout le monde.

Les clés sont stockées hachées, ressemblent à mgsk_… pour que les scanners de secrets les reconnaissent, comptent dans la même limite de débit que l’API publique, et affichent leur dernière utilisation dans le hub. Une clé perdue ? Révoquez-la et créez-en une autre.

Endpoints

Générée depuis la description OpenAPI. La référence est en anglais dans les deux langues.

Reference data

Metals, minerals, ingredients, potions, gems and the crafting rules.

Audio catalogue

Tracks, composers, albums, packs and taxonomy of MGS Audio.

Your own data

Read-only access to the account's Fantasy City Simulator and Crafting Table data, with a personal API key (Authorization: Bearer mgsk_…). No audio here, by design.

Embeds

oEmbed and cards.

Meta

Index and documents.

Conditions

MGS Toolbox open data terms. Version courte : utilisez-les, mettez un lien retour, ne clonez pas le site, ne redistribuez pas la musique.

Libre d’utilisation

Outils personnels, communautaires ou commerciaux : bots Discord, modules de VTT, plugins de prise de notes, wikis, générateurs, votre propre site. Sans clé, sans inscription, sans frais.

Lien retour

Partout où vous montrez une fiche, montrez d’où elle vient : le champ url de chaque élément est la page à lier. Une courte mention de Michael Ghelfi Studios suffit quand un lien est impossible (un message de chat, un assistant vocal).

Pas de miroir

Ne republiez pas les catalogues sous forme de pages autonomes qui remplaceraient les encyclopédies (une copie de chaque métal, minéral ou ingrédient avec son texte complet). Citer des fiches dans vos contenus, outils et jeux, c’est ce pour quoi l’API existe ; cloner le site, non.

La musique reste sous licence

Les endpoints audio décrivent le catalogue : titres, compositeurs, ambiances, pages, lecteurs à intégrer. Ils ne livrent jamais de fichier audio, et lister une piste n’accorde aucun droit sur l’enregistrement. Les licences de la musique elle-même se vendent sur le site.

Restez raisonnable

Mettez les réponses en cache (elles portent un Cache-Control), identifiez votre projet dans l’en-tête User-Agent, et restez sous la limite de débit publiée. Un trafic abusif est bloqué, pas ralenti.

Sans garantie, sans verrou

Les données sont fournies en l’état et peuvent évoluer avec les encyclopédies. Un changement incompatible aura un nouveau préfixe de version ; v1 reste en ligne au moins un an après l’arrivée d’une v2.

Ligne d’attribution : Data © Michael Ghelfi Studios — https://michaelghelfistudios.com

Versions et contact

Ceci est la v1. Des champs peuvent être ajoutés à tout moment ; rien n’est retiré ni renommé sans nouveau préfixe. L’index donne la taille actuelle des catalogues. Une question, un projet à montrer, un besoin de limite plus haute : michaelghelfistudios.com.