Rozdíly

Zde můžete vidět rozdíly mezi vybranou verzí a aktuální verzí dané stránky.

--- ai:mcp:servery:higgsfield-mcp-v-claude-code-a-opencode [03.05.2026 04:05] – Migrace článku z ai:mcp:klienti do ai:mcp:servery Petr Nosek
+++ ai:mcp:servery:higgsfield-mcp-v-claude-code-a-opencode [09.05.2026 07:17] (aktuální) – Oprava dvojitého escapování URL v tabulce Petr Nosek
@@ Řádek 5: / Řádek 5: @@
 [[https://higgsfield.ai/mcp|Higgsfield MCP]] je oficiální MCP konektor pro generování obrázků a videí přes Higgsfield. Oficiální návod používá endpoint [[https://mcp.higgsfield.ai/mcp|https://mcp.higgsfield.ai/mcp]] a autentizaci přes Higgsfield účet, ne API key/API secret.
-Tento zápisek popisuje konkrétní nasazení v Claude Code a OpenCode běžících v Dockeru. Důležité je hlavně zachytit rozdíl: v Claude Code OAuth proběhl rychle, zatímco v OpenCode se objevily chyby kolem OAuth scope. Nakonec fungovaly dvě cesty: device flow s tokenem platným jen 24 hodin a praktičtější převzetí delšího tokenu z Claude Code. Vedle oficiálního remote MCP existují i neoficiální lokální MCP servery nad API key/API secret; ty jsou popsané níže jako jiná architektonická cesta.
+Tento zápisek popisuje konkrétní nasazení v Claude Code a OpenCode běžících v Dockeru. Důležité je hlavně zachytit rozdíl: v Claude Code OAuth proběhl rychle, zatímco v OpenCode se objevily chyby kolem OAuth scope. Nakonec fungovaly dvě cesty: device flow s tokenem platným jen 24 hodin a praktičtější převzetí delšího tokenu z Claude Code. Vedle remote MCP dnes existují i dvě oficiální navazující cesty: [[https://github.com/higgsfield-ai/cli|Higgsfield CLI]] pro terminálové použití a [[https://github.com/higgsfield-ai/skills|Higgsfield AI Skills]] pro agenty. Neoficiální lokální MCP wrappery nad API key/API secret jsou v článku ponechané až jako okrajová alternativa.
 ===== Výchozí stav =====
@@ Řádek 15: / Řádek 15: @@
 Higgsfield na své MCP stránce uvádí, že není potřeba spravovat API klíče. API key a API secret z Higgsfield API proto nejsou totéž jako autentizace pro oficiální MCP endpoint. Pro MCP se používá OAuth přihlášení přes Higgsfield účet.
+Dnes je dobré rozlišovat tři oficiální vrstvy:
+  * **remote MCP endpoint** – integrace přes ''https%%://%%mcp.higgsfield.ai/mcp'', vhodná pro MCP klienty
+  * **Higgsfield CLI** – oficiální terminálový nástroj ''higgsfield'' pro generování obrázků/videí, správu účtu, modelů, workspace, uploadů a Soul ID
+  * **Higgsfield AI Skills** – Markdown skills pro agenty, které obalují práci s Higgsfield CLI a dávají agentovi konkrétní workflow pro generování, Soul ID, produktové fotky a marketplace karty
+===== Oficiální Higgsfield CLI =====
+[[https://github.com/higgsfield-ai/cli|Higgsfield CLI]] je oficiální příkazový nástroj pro práci s Higgsfieldem z terminálu. Podle README umí generovat obrázky a videa přes více než 30 modelů, včetně Nano Banana Pro, FLUX.2, Soul V2, Veo 3.1, Kling v3.0, Seedance 2.0 a Marketing Studio.
+Důležité: CLI není náhrada MCP endpointu ve smyslu remote MCP serveru. Je to ale oficiální cesta, jak Higgsfield používat v prostředí, kde agent umí spouštět shell příkazy. Pokud není potřeba MCP tool interface a stačí terminálové volání, dává oficiální CLI větší smysl než komunitní lokální wrapper nad API key/API secret.
+==== Instalace ====
+README uvádí několik instalačních cest.
+macOS / Linux přes instalační skript:
+<code bash>
+curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh
+</code>
+macOS / Linux přes Homebrew:
+<code bash>
+brew install higgsfield-ai/tap/higgsfield
+</code>
+Cross-platform instalace přes npm:
+<code bash>
+npm install -g @higgsfield/cli
+</code>
+Po instalaci se provede přihlášení:
+<code bash>
+higgsfield auth login
+</code>
+==== Základní použití ====
+Jednoduché vygenerování obrázku s čekáním na výsledek:
+<code bash>
+higgsfield generate create nano_banana_2 --prompt "a quiet beach at sunrise" --wait
+</code>
+Příklad pro Nano Banana Pro:
+<code bash>
+higgsfield generate create nano_banana_2 \
+  --prompt "modern architecture, glass facade, golden hour light" \
+  --aspect_ratio 16:9 \
+  --resolution 2k \
+  --wait
+</code>
+Příklad pro video přes Kling v3.0 se vstupním obrázkem:
+<code bash>
+higgsfield generate create kling3_0 \
+  --prompt "slow camera push through a forest clearing at dawn" \
+  --start-image ./first.png \
+  --duration 5 --mode pro --sound off \
+  --wait
+</code>
+==== Hlavní příkazy ====
+Podle README CLI obsahuje tyto skupiny příkazů:
+  * ''higgsfield auth'' – login, logout a kontrola tokenu
+  * ''higgsfield account'' – stav kreditů a transakce
+  * ''higgsfield workspace'' – výběr billing workspace
+  * ''higgsfield model'' – seznam modelů a schémata parametrů
+  * ''higgsfield generate'' – vytvoření, nacenění, čekání, načtení a listování jobů
+  * ''higgsfield upload'' – upload image/video/audio souborů
+  * ''higgsfield soul-id'' – trénování a správa Soul postav
+  * ''higgsfield marketing-studio'' – branded ads s avatary, produkty a referencemi
+  * ''higgsfield product-photoshoot'' – produktové fotky s mode-specific enhancement
+  * ''higgsfield version'' – informace o buildu
+Praktické flagy:
+  * ''--wait'' – počká na dokončení jobu a vypíše URL výsledku
+  * ''--wait-timeout'' – maximální čekání, výchozí hodnota je podle README ''10m''
+  * ''--wait-interval'' – interval pollingu, výchozí hodnota je ''3s''
+  * ''--json'' – strojově čitelný JSON výstup
+  * ''--no-color'' – vypnutí barevného výstupu
+Příklad pipeline s JSON výstupem:
+<code bash>
+higgsfield generate list --json | jq -r '.[] | select(.status=="completed") | .result_url'
+</code>
+==== Vztah k MCP integraci ====
+Pro Claude Code a OpenCode jsou tím pádem tři praktické varianty:
+  - **MCP endpoint** – nejlepší, pokud MCP klient zvládne OAuth vůči ''https%%://%%mcp.higgsfield.ai/mcp''.
+  - **Oficiální CLI** – vhodné, pokud agent umí spouštět shell příkazy a stačí mu příkaz ''higgsfield'' místo MCP toolů.
+  - **Neoficiální lokální MCP wrappery** – až fallback, pokud je potřeba MCP rozhraní, ale remote OAuth nefunguje a zároveň nestačí CLI.
+===== Oficiální Higgsfield AI Skills =====
+[[https://github.com/higgsfield-ai/skills|Higgsfield AI Skills]] je oficiální sada Markdown-based skills pro AI coding agenty. README uvádí podporu pro Claude Code, Cursor, Codex a další agenty, které umí načítat Markdown skills. Instalace zároveň řeší instalaci Higgsfield CLI a autentizaci jako součást setupu.
+==== Instalace skills ====
+Doporučená cross-agent instalace:
+<code bash>
+npx skills add higgsfield-ai/skills
+</code>
+Alternativa přes GitHub CLI 2.90+:
+<code bash>
+gh skill install higgsfield-ai/skills
+</code>
+Instalace přes Claude Code marketplace:
+<code>
+/plugin marketplace add higgsfield-ai/skills
+/plugin install higgsfield@higgsfield
+</code>
+Fallback přes clone repozitáře:
+<code bash>
+git clone --depth 1 https://github.com/higgsfield-ai/skills.git
+cd skills
+./setup
+</code>
+==== Dostupné skills ====
+Repozitář aktuálně popisuje čtyři hlavní skills:
+^ Skill ^ Vyvolání ^ Účel ^
+| ''higgsfield-generate'' | ''/higgsfield:generate'' | Generování obrázků a videí přes 30+ modelů, Marketing Studio pro branded ads a Virality Predictor pro scoring hotových videí. |
+| ''higgsfield-soul-id'' | ''/higgsfield:soul-id'' | Trénování Soul Character – opakovaně použitelné face-faithful identity. Výstupem je ''reference_id'' pro Soul-aware generování. |
+| ''higgsfield-product-photoshoot'' | ''/higgsfield:product-photoshoot'' | Produktové fotky s prompt enhancementem a režimy jako studio, lifestyle, hero banner, social carousel, ad creative pack nebo virtual try-on. |
+| ''higgsfield-marketplace-cards'' | ''/higgsfield:marketplace-cards'' | Marketplace produktové karty: hlavní produktový obrázek, sekundární obrázky a A+ style moduly. |
+Důležitý princip: skills neřeší jen jednorázový příkaz. Dávají agentovi workflow – například nejdřív natrénovat Soul ID a potom ho použít v generování nebo v Marketing Studio jobech.
+==== Kdy použít skills místo přímého MCP ====
+Skills dávají smysl hlavně tehdy, když:
+  * agent umí načíst Markdown skills a spouštět shell příkazy
+  * je potřeba agentovi dát konkrétní pracovní postup místo ručního skládání parametrů
+  * stačí CLI workflow a není nutné mít každý Higgsfield endpoint jako samostatný MCP tool
+  * jde o opakované úlohy typu produktové fotky, marketplace karty, Soul ID nebo branded ad video
+Pro čisté MCP workflow dál platí sekce níže. Pro agentní práci, kde je povolené volání terminálu, je ale oficiální kombinace **Higgsfield CLI + Higgsfield AI Skills** preferovaná před komunitními lokálními wrappery.
 ===== Claude Code =====
@@ Řádek 91: / Řádek 252: @@
 Claude Code použil předregistrovaného OAuth klienta pro Higgsfield. V uložených credentials bylo vidět, že Claude Code měl pro Higgsfield uložené:
-  * ''serverUrl'': ''https://mcp.higgsfield.ai/mcp''
+  * ''serverUrl'': ''https%%://%%mcp.higgsfield.ai/mcp''
   * ''clientId'': předregistrovaný klient Claude Code
-  * ''redirectUri'': ''http://localhost:65498/callback''
+  * ''redirectUri'': ''http%%://%%localhost:65498/callback''
   * scope včetně ''openid'', ''profile'', ''email'' a ''offline_access''
@@ Řádek 119: / Řádek 280: @@
 Ani poslední úprava nezabrala. V mém setupu zůstal problém v OAuth toku OpenCode: buď se požadoval nepovolený scope ''openid'', nebo neseděl ''redirect_uri'' vůči použitému klientovi.
-===== Alternativní cesta: lokální MCP servery nad API key/API secret =====
-Vedle oficiálního remote endpointu existují také neoficiální lokální MCP servery, které neřeší OAuth proti ''https://mcp.higgsfield.ai/mcp'', ale obalují Higgsfield API a používají API key/API secret. Tím se dá obejít problém OpenCode OAuth flow, ale je to jiná integrace než oficiální Higgsfield MCP.
-V diskusi jsem porovnával hlavně dva repozitáře od stejného autora:
-  * [[https://github.com/geopopos/higgsfield_ai_mcp|geopopos/higgsfield_ai_mcp]]
-  * [[https://github.com/geopopos/geo_higgsfield_ai_mcp|geopopos/geo_higgsfield_ai_mcp]]
-Oba projekty používají lokální Python server a credentials z Higgsfield API. Prakticky to znamená, že OpenCode by nepřipojoval ''type: remote'' endpoint Higgsfieldu, ale lokálně spuštěný příkaz přes ''type: local''.
-==== Rozdíl mezi oběma repozitáři ====
-^ Oblast ^ ''higgsfield_ai_mcp'' ^ ''geo_higgsfield_ai_mcp'' ^
-| Zaměření | Jednodušší MCP server pro základní image/video workflow. | Širší MCP server s více parametry a více typy nástrojů. |
-| Framework | FastMCP. | Oficiální low-level ''mcp'' SDK. |
-| Credentials | ''HF_API_KEY'' a ''HF_SECRET''. | ''HIGGSFIELD_API_KEY'' a ''HIGGSFIELD_SECRET''. |
-| Instalace podle README | Clone repozitáře a instalace závislostí přes ''pip install -r requirements.txt'' nebo Poetry. | Deklaruje instalaci přes ''pip install higgsfield-mcp'' nebo instalaci ze zdrojů. |
-| Nástroje | Jednodušší názvy jako ''generate_image'', ''generate_video'', ''get_generation_status'', ''create_character'', ''list_characters''. | Explicitnější názvy jako ''generate_image_soul'', ''generate_video_dop'', ''generate_speech_video'', ''get_job_status'', ''get_character'', ''delete_character''. |
-| Parametry | Méně voleb, rychlejší na pochopení. | Více voleb: rozměry, batch size, seed, reference image, webhooky, motion strength, start/end frame. |
-| Video | Image-to-video přes DoP/motion preset. | Image-to-video přes DoP, motions array, end frame. |
-| Speech/talking head | V kódu se objevuje ''generate_talking_head''. | README popisuje ''generate_speech_video''. |
-| Character management | Vytvoření a listování character references. | Vytvoření, načtení i mazání character references. |
-| Resources/tools | Má MCP resources jako ''higgsfield://styles'', ''higgsfield://motions'', ''higgsfield://characters''. | Víc věcí řeší přes tools, například ''get_soul_styles'' a ''get_motions''. |
-==== Kdy dává smysl který projekt ====
-''higgsfield_ai_mcp'' dává smysl, pokud jde hlavně o rychlé lokální napojení Higgsfieldu přes API key/API secret a základní generování obrázků nebo videa. Je jednodušší a podle README míří hlavně na rychlé použití s Claude Desktopem a FastMCP.
-''geo_higgsfield_ai_mcp'' dává větší smysl, pokud je potřeba více kontroly nad parametry Higgsfield API: batch generation, seed, rozměry, webhooky, speech video, motion strength nebo správa character references. README u něj obsahuje i quick setup pro Claude Code.
-==== Důležitý konflikt názvů ====
-Oba repozitáře používají stejný Python import namespace i stejný command/distribution název:
-<code>
-higgsfield_mcp
-higgsfield-mcp
-</code>
-Proto je nedává smysl instalovat vedle sebe do stejného Python prostředí. Pokud by se testovaly oba, je lepší použít oddělené virtualenv/uv prostředí nebo kontejnery, jinak si mohou navzájem přepsat package a příkaz.
-==== Princip konfigurace v OpenCode ====
-Pro lokální MCP server by konfigurace v OpenCode nebyla remote OAuth konfigurace, ale lokální příkaz. Konkrétní příkaz záleží na tom, jak je balíček nainstalovaný, ale princip je tento:
-<code json>
-"higgsfield-local": {
-  "type": "local",
-  "command": ["higgsfield-mcp"],
-  "environment": {
-    "HIGGSFIELD_API_KEY": "{file:./higgsfield-api.key}",
-    "HIGGSFIELD_SECRET": "{file:./higgsfield-api.secret}"
-  },
-  "enabled": true
-}
-</code>
-U projektu ''higgsfield_ai_mcp'' je podle README potřeba použít proměnné ''HF_API_KEY'' a ''HF_SECRET'' místo ''HIGGSFIELD_API_KEY'' a ''HIGGSFIELD_SECRET'':
-<code json>
-"environment": {
-  "HF_API_KEY": "{file:./higgsfield-api.key}",
-  "HF_SECRET": "{file:./higgsfield-api.secret}"
-}
-</code>
-==== Výhody a nevýhody lokálních wrapperů ====
-Výhody:
-  * obejdou problematické OAuth flow v OpenCode
-  * používají běžné API key/API secret, které se dají uložit přes ''{file:...}''
-  * běží lokálně a dají se případně upravit
-Nevýhody:
-  * nejsou to oficiální Higgsfield MCP endpointy
-  * mohou pokrývat jen část funkcí oficiálního MCP konektoru
-  * je potřeba řešit instalaci Python prostředí a závislostí
-  * oba porovnávané projekty kolidují názvem balíčku/příkazu
-  * bezpečnost API key/API secret je na lokální konfiguraci
 ===== Alternativní funkční cesta: device flow pro OpenCode =====
@@ Řádek 209: / Řádek 287: @@
 [[https://mcp.higgsfield.ai/.well-known/oauth-protected-resource|OAuth protected resource discovery]] pro Higgsfield uvádí dva authorization servery:
-  * ''https://clerk.higgsfield.ai'' pro authorization-code PKCE flow
+  * ''https%%://%%clerk.higgsfield.ai'' pro authorization-code PKCE flow
-  * ''https://fnf-device-auth.higgsfield.ai'' pro device-code flow
+  * ''https%%://%%fnf-device-auth.higgsfield.ai'' pro device-code flow
 Pro device flow je důležitý server ''fnf-device-auth.higgsfield.ai''. Jeho [[https://fnf-device-auth.higgsfield.ai/openapi.json|OpenAPI schema]] ukazuje dva hlavní endpointy:
@@ Řádek 287: / Řádek 365: @@
 </code>
-To znamená platnost jen 24 hodin. Pro běžné používání OpenCode je to příliš krátké, protože by bylo nutné device flow opakovat každý den nebo řešit automatické obnovování. Proto jsem se po testu vrátil k tokenu převzatému z Claude Code credentials, který byl v daném setupu praktičtější.
+To znamená platnost jen 24 hodin. Navíc device flow nevrací refresh token, takže tiché obnovení není možné – každý den by bylo nutné opakovat celý flow s prohlížečem. Proto jsem se po testu vrátil k tokenu převzatému z Claude Code credentials, který přináší i refresh token a umožňuje automatické obnovování.
 ===== Preferovaný workaround: token z Claude Code pro OpenCode =====
@@ Řádek 293: / Řádek 371: @@
 Protože Claude Code už měl vůči Higgsfield úspěšně získaný OAuth token, nejrychlejší funkční řešení bylo:
-  - vytáhnout Higgsfield access token z Claude Code credentials
+  - vytáhnout Higgsfield access token a refresh token z Claude Code credentials
-  - uložit ho do souboru pro OpenCode
+  - uložit je do souborů pro OpenCode
-  - v OpenCode vypnout OAuth flow a posílat token jako statický Bearer header
+  - v OpenCode vypnout OAuth flow a posílat access token jako statický Bearer header
+**Access token** má vždy platnost **24 hodin** – pevně dané na straně Higgsfield serveru, nedá se změnit. Claude Code při OAuth flow ukládá vedle access tokenu i **refresh token**: ten je dlouhodobý a slouží k tichému získání nového access tokenu bez opakovaného přihlašování v prohlížeči. Oba tokeny je při první extrakci potřeba uložit. Jak využít refresh token k automatickému obnovování, popisuje sekce [[#automaticka_obnova_tokenu_pres_refresh_token|Automatická obnova tokenu]] níže.
 Token se nachází v souboru:
 <code>
-/home/ubuntu/.claude/.credentials.json
+~/.claude/.credentials.json
 </code>
-V sekci ''mcpOAuth'' je položka pro Higgsfield. Token se dá bezpečně zkopírovat do samostatného souboru bez vypisování tokenu do terminálu:
+V sekci ''mcpOAuth'' je položka pro Higgsfield. Tokeny se dají bezpečně zkopírovat do samostatných souborů bez vypisování jejich hodnot do terminálu:
 <code python>
@@ Řádek 309: / Řádek 389: @@
 from pathlib import Path
-credentials_path = Path("/home/ubuntu/.claude/.credentials.json")
+credentials_path = Path.home() / ".claude" / ".credentials.json"
-target_path = Path("/home/ubuntu/.config/opencode/higgsfield.token")
+target_path = Path.home() / ".config" / "opencode" / "higgsfield.token"
+refresh_path = Path.home() / ".config" / "opencode" / "higgsfield_refresh.token"
 with credentials_path.open() as f:
@@ Řádek 317: / Řádek 398: @@
 for item in data.get("mcpOAuth", {}).values():
     if item.get("serverName") == "higgsfield" or item.get("serverUrl") == "https://mcp.higgsfield.ai/mcp":
-        token = item["accessToken"]
+        access_token = item["accessToken"]
+        refresh_token = item.get("refreshToken", "")
         break
 else:
     raise SystemExit("Higgsfield token nebyl v Claude Code credentials nalezen")
-target_path.write_text(token.strip() + "\n")
+target_path.write_text(access_token.strip())
 target_path.chmod(0o600)
+print(f"Access token uložen do {target_path}")
+if refresh_token:
+    refresh_path.write_text(refresh_token.strip())
+    refresh_path.chmod(0o600)
+    print(f"Refresh token uložen do {refresh_path}")
+else:
+    print("Refresh token nebyl nalezen – automatický refresh nebude fungovat")
 </code>
@@ Řádek 340: / Řádek 430: @@
 </code>
-Soubor ''higgsfield.token'' je relativní k adresáři s ''opencode.json'', tedy v tomto případě:
+Soubory ''higgsfield.token'' a ''higgsfield_refresh.token'' jsou relativní k adresáři s ''opencode.json'', tedy typicky v ''~/.config/opencode/''.
+Tím se OAuth flow v OpenCode úplně obejde a OpenCode použije již existující token získaný přes Claude Code.
+===== Automatická obnova tokenu přes refresh token =====
+Higgsfield vydává access tokeny vždy s platností **24 hodin**. Při prvním OAuth flow Claude Code ale uloží do credentials dva tokeny:
+  * **access_token** – krátkodobý Bearer token pro API volání, vyprší za 24 hodin
+  * **refresh_token** – dlouhodobý token pro tiché obnovení; nepotřebuje prohlížeč ani přihlašování
+Refresh flow funguje tak, že skript zavolá Higgsfield OAuth token endpoint s refresh tokenem. Server vydá nový access token a obvykle i rotovaný refresh token (starý se nahradí novým).
+==== Refresh skript ====
+Uložit jako ''~/.config/opencode/refresh-higgsfield-token.sh'' a nastavit jako spustitelný:
+<code bash>
+#!/bin/bash
+# Refreshes Higgsfield OAuth access token using stored refresh token.
+# Higgsfield issues tokens with 24h validity; run this every ~20h via cron.
+set -euo pipefail
+REFRESH_TOKEN_FILE="$HOME/.config/opencode/higgsfield_refresh.token"
+ACCESS_TOKEN_FILE="$HOME/.config/opencode/higgsfield.token"
+CLIENT_ID="zWX6QppKmYmSXa1S"
+TOKEN_ENDPOINT="https://mcp.higgsfield.ai/oauth2/token"
+REFRESH_TOKEN=$(cat "$REFRESH_TOKEN_FILE")
+RESPONSE=$(curl -s -X POST "$TOKEN_ENDPOINT" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "grant_type=refresh_token&refresh_token=${REFRESH_TOKEN}&client_id=${CLIENT_ID}")
+ACCESS_TOKEN=$(echo "$RESPONSE" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d['access_token'])")
+NEW_REFRESH_TOKEN=$(echo "$RESPONSE" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('refresh_token',''))")
+if [ -z "$ACCESS_TOKEN" ]; then
+  echo "ERROR: Failed to refresh token. Response: $RESPONSE" >&2
+  exit 1
+fi
+echo -n "$ACCESS_TOKEN" > "$ACCESS_TOKEN_FILE"
+if [ -n "$NEW_REFRESH_TOKEN" ]; then
+  echo -n "$NEW_REFRESH_TOKEN" > "$REFRESH_TOKEN_FILE"
+fi
+echo "$(date): Higgsfield token refreshed OK"
+</code>
+<code bash>
+chmod +x ~/.config/opencode/refresh-higgsfield-token.sh
+</code>
+Ruční spuštění (test nebo při vypršení tokenu):
+<code bash>
+~/.config/opencode/refresh-higgsfield-token.sh
+</code>
+==== Nastavení cronu na Alpine / busybox ====
+Na Alpine s busyboxem standardní příkaz ''crontab'' bez SUID bitu nefunguje jako běžný uživatel – crontab soubor je potřeba zapsat přímo jako root. Nahraď ''<user>'' svým uživatelským jménem a uprav cestu ke skriptu:
+<code bash>
+sudo bash -c 'echo "0 */20 * * * /home/<user>/.config/opencode/refresh-higgsfield-token.sh >> /tmp/higgsfield-token-refresh.log 2>&1" > /var/spool/cron/crontabs/<user>'
+sudo chown <user> /var/spool/cron/crontabs/<user>
+sudo chmod 600 /var/spool/cron/crontabs/<user>
+</code>
+Interval ''*/20'' znamená spuštění každých 20 hodin – s dostatečnou rezervou před vypršením 24hodinového limitu.
+Spuštění crond, pokud ještě neběží:
+<code bash>
+sudo crond -b -l 8
+</code>
+==== Automatický start crond po restartu (Alpine / OpenRC) ====
+Pokud má crond startovat automaticky při restartu kontejneru nebo systému, přidá se startup skript do ''/etc/local.d/'':
+<code bash>
+sudo bash -c 'cat > /etc/local.d/crond.start << "EOF"
+#!/bin/sh
+crond -b -l 8
+EOF
+chmod +x /etc/local.d/crond.start'
+</code>
+Při dalším startu systému se crond spustí automaticky.
+===== Okrajová alternativa: neoficiální lokální MCP servery nad API key/API secret =====
+Vedle oficiálního remote endpointu, oficiálního CLI a oficiálních skills existují také neoficiální lokální MCP servery, které neřeší OAuth proti ''https%%://%%mcp.higgsfield.ai/mcp'', ale obalují Higgsfield API a používají API key/API secret. Po nalezení oficiálního CLI a skills bych tuto cestu bral jen jako fallback: hodí se hlavně tehdy, když je nezbytné lokální MCP rozhraní a zároveň nefunguje remote OAuth ani nestačí spouštět oficiální CLI.
+V diskusi jsem porovnával hlavně dva repozitáře od stejného autora:
+  * [[https://github.com/geopopos/higgsfield_ai_mcp|geopopos/higgsfield_ai_mcp]]
+  * [[https://github.com/geopopos/geo_higgsfield_ai_mcp|geopopos/geo_higgsfield_ai_mcp]]
+Oba projekty používají lokální Python server a credentials z Higgsfield API. Prakticky to znamená, že OpenCode by nepřipojoval ''type: remote'' endpoint Higgsfieldu, ale lokálně spuštěný příkaz přes ''type: local''.
+==== Rozdíl mezi oběma repozitáři ====
+^ Oblast ^ ''higgsfield_ai_mcp'' ^ ''geo_higgsfield_ai_mcp'' ^
+| Zaměření | Jednodušší MCP server pro základní image/video workflow. | Širší MCP server s více parametry a více typy nástrojů. |
+| Framework | FastMCP. | Oficiální low-level ''mcp'' SDK. |
+| Credentials | ''HF_API_KEY'' a ''HF_SECRET''. | ''HIGGSFIELD_API_KEY'' a ''HIGGSFIELD_SECRET''. |
+| Instalace podle README | Clone repozitáře a instalace závislostí přes ''pip install -r requirements.txt'' nebo Poetry. | Deklaruje instalaci přes ''pip install higgsfield-mcp'' nebo instalaci ze zdrojů. |
+| Nástroje | Jednodušší názvy jako ''generate_image'', ''generate_video'', ''get_generation_status'', ''create_character'', ''list_characters''. | Explicitnější názvy jako ''generate_image_soul'', ''generate_video_dop'', ''generate_speech_video'', ''get_job_status'', ''get_character'', ''delete_character''. |
+| Parametry | Méně voleb, rychlejší na pochopení. | Více voleb: rozměry, batch size, seed, reference image, webhooky, motion strength, start/end frame. |
+| Video | Image-to-video přes DoP/motion preset. | Image-to-video přes DoP, motions array, end frame. |
+| Speech/talking head | V kódu se objevuje ''generate_talking_head''. | README popisuje ''generate_speech_video''. |
+| Character management | Vytvoření a listování character references. | Vytvoření, načtení i mazání character references. |
+| Resources/tools | Má MCP resources jako ''higgsfield%%://%%styles'', ''higgsfield%%://%%motions'', ''higgsfield%%://%%characters''. | Víc věcí řeší přes tools, například ''get_soul_styles'' a ''get_motions''. |
+==== Kdy dává smysl který projekt ====
+''higgsfield_ai_mcp'' dává smysl, pokud jde hlavně o rychlé lokální napojení Higgsfieldu přes API key/API secret a základní generování obrázků nebo videa. Je jednodušší a podle README míří hlavně na rychlé použití s Claude Desktopem a FastMCP.
+''geo_higgsfield_ai_mcp'' dává větší smysl, pokud je potřeba více kontroly nad parametry Higgsfield API: batch generation, seed, rozměry, webhooky, speech video, motion strength nebo správa character references. README u něj obsahuje i quick setup pro Claude Code.
+==== Důležitý konflikt názvů ====
+Oba repozitáře používají stejný Python import namespace i stejný command/distribution název:
 <code>
-/home/ubuntu/.config/opencode/higgsfield.token
+higgsfield_mcp
+higgsfield-mcp
 </code>
-Tím se OAuth flow v OpenCode úplně obejde a OpenCode použije již existující token získaný přes Claude Code.
+Proto je nedává smysl instalovat vedle sebe do stejného Python prostředí. Pokud by se testovaly oba, je lepší použít oddělené virtualenv/uv prostředí nebo kontejnery, jinak si mohou navzájem přepsat package a příkaz.
+==== Princip konfigurace v OpenCode ====
+Pro lokální MCP server by konfigurace v OpenCode nebyla remote OAuth konfigurace, ale lokální příkaz. Konkrétní příkaz záleží na tom, jak je balíček nainstalovaný, ale princip je tento:
+<code json>
+"higgsfield-local": {
+  "type": "local",
+  "command": ["higgsfield-mcp"],
+  "environment": {
+    "HIGGSFIELD_API_KEY": "{file:./higgsfield-api.key}",
+    "HIGGSFIELD_SECRET": "{file:./higgsfield-api.secret}"
+  },
+  "enabled": true
+}
+</code>
+U projektu ''higgsfield_ai_mcp'' je podle README potřeba použít proměnné ''HF_API_KEY'' a ''HF_SECRET'' místo ''HIGGSFIELD_API_KEY'' a ''HIGGSFIELD_SECRET'':
+<code json>
+"environment": {
+  "HF_API_KEY": "{file:./higgsfield-api.key}",
+  "HF_SECRET": "{file:./higgsfield-api.secret}"
+}
+</code>
+==== Výhody a nevýhody lokálních wrapperů ====
+Výhody:
+  * obejdou problematické OAuth flow v OpenCode
+  * používají běžné API key/API secret, které se dají uložit přes ''{file:...}''
+  * běží lokálně a dají se případně upravit
+Nevýhody:
+  * nejsou to oficiální Higgsfield MCP endpointy
+  * po existenci oficiálního CLI a skills jsou méně preferovaná cesta
+  * mohou pokrývat jen část funkcí oficiálního MCP konektoru nebo CLI
+  * je potřeba řešit instalaci Python prostředí a závislostí
+  * oba porovnávané projekty kolidují názvem balíčku/příkazu
+  * bezpečnost API key/API secret je na lokální konfiguraci
 ===== Ověření =====
@@ Řádek 358: / Řádek 618: @@
 </code>
-Pokud se později začne vracet ''401 Unauthorized'', nejpravděpodobnější příčina je expirovaný token. Pak jsou dvě možnosti:
+Pokud se později začne vracet ''401 Unauthorized'', nejpravděpodobnější příčina je expirovaný token. Možnosti jsou:
-  * znovu provést přihlášení v Claude Code přes ''/mcp'' a zkopírovat nový ''accessToken'' do ''higgsfield.token''
+  * spustit refresh skript ''~/.config/opencode/refresh-higgsfield-token.sh'' – obnoví token bez prohlížeče a bez přihlašování
-  * použít device flow, ale počítat s platností tokenu jen 24 hodin
+  * znovu provést přihlášení v Claude Code přes ''/mcp'' a znovu extrahovat oba tokeny (viz sekce výše)
+  * použít device flow, ale počítat s platností tokenu jen 24 hodin a bez možnosti tichého refreshe
+Pro oficiální CLI se dá základní funkčnost ověřit samostatně:
+<code bash>
+higgsfield auth login
+higgsfield model list
+higgsfield generate create nano_banana_2 --prompt "test image" --wait
+</code>
 ===== Rychlý troubleshooting pro budoucí řešení =====
@@ Řádek 375: / Řádek 644: @@
 Význam: OpenCode vytvořil nebo použil OAuth klienta, který nemá povolený scope ''openid'', ale autorizační URL tento scope obsahuje.
-Rychlé řešení: Nepokračovat laděním API key/API secret. U oficiálního Higgsfield MCP jde o OAuth. Pokud OpenCode OAuth stále selhává, použít token z Claude Code jako Bearer header. Alternativně lze použít device flow, ale získaný token má jen 24hodinovou platnost.
+Rychlé řešení: Nepokračovat laděním API key/API secret. U oficiálního Higgsfield MCP jde o OAuth. Pokud OpenCode OAuth stále selhává, použít token z Claude Code jako Bearer header. Alternativně lze použít device flow, ale získaný token má jen 24hodinovou platnost a bez refresh tokenu. Pokud není nutné MCP rozhraní, zvážit oficiální Higgsfield CLI a případně Higgsfield AI Skills.
 ==== Chyba: redirect_uri nesedí ====
@@ Řádek 385: / Řádek 654: @@
 </code>
-Význam: Použitý OAuth klient má předregistrovaný jiný callback než ten, který posílá OpenCode. V mém případě Claude Code používal ''http://localhost:65498/callback'', zatímco OpenCode používal ''http://127.0.0.1:19876/mcp/oauth/callback''.
+Význam: Použitý OAuth klient má předregistrovaný jiný callback než ten, který posílá OpenCode. V mém případě Claude Code používal ''http%%://%%localhost:65498/callback'', zatímco OpenCode používal ''http%%://%%127.0.0.1:19876/mcp/oauth/callback''.
 Rychlé řešení: Nepoužívat Claude Code ''clientId'' přímo v OpenCode, pokud nejde zároveň změnit callback na předregistrovanou hodnotu. Použít hotový token přes Bearer header, případně device flow bez redirect URI.
@@ Řádek 396: / Řádek 665: @@
 Rychlé řešení: publikovat port ''65498'' z kontejneru na ''127.0.0.1:65498'' na hostu a OAuth zopakovat.
+==== CLI hlásí Session expired nebo Not authenticated ====
+Příznak:
+<code>
+Session expired
+Not authenticated
+</code>
+Význam: CLI token expiroval nebo není uložené platné přihlášení.
+Rychlé řešení:
+<code bash>
+higgsfield auth login
+</code>
+==== CLI nezná model ====
+Příznak:
+<code>
+Unknown model "..."
+</code>
+Význam: použitý název modelu není v aktuálním katalogu CLI.
+Rychlé řešení:
+<code bash>
+higgsfield model list
+</code>
 ===== Poznámky k bezpečnosti =====
   * Token nikdy neukládat přímo do ''opencode.json''.
-  * Soubor ''higgsfield.token'' držet mimo git a nastavit mu práva jen pro uživatele.
+  * Soubory ''higgsfield.token'' a ''higgsfield_refresh.token'' držet mimo git a nastavit jim práva jen pro uživatele (''chmod 600'').
   * Token v článku, logu ani chatu nevypisovat.
-  * Device flow token má podle testu platnost 24 hodin, takže se rychleji stane neplatným.
+  * Device flow token má podle testu platnost 24 hodin a neobsahuje refresh token.
-  * Pokud token expiruje nebo je kompromitovaný, znovu se přihlásit přes Claude Code nebo spustit device flow a token obnovit.
+  * Refresh token může být zneplatněn ze strany Higgsfield (změna hesla, odvolání přístupu) – v takovém případě je nutné provést nový OAuth flow v Claude Code.
   * U lokálních wrapperů nad Higgsfield API neukládat API key/API secret přímo do konfigurace; v OpenCode používat ''{file:...}'' a soubory držet mimo git.
+  * Při použití CLI a skills neukládat tokeny ani výstupy s citlivými URL do repozitáře. Pokud se používá ''--json'' v automatizaci, logovat jen nezbytné části odpovědi.
 ===== Shrnutí =====
-Claude Code fungoval, protože použil předregistrovaný OAuth flow a callback ''localhost:65498''. V Dockeru bylo nutné tento port publikovat na hosta. OpenCode v mém prostředí narazil na OAuth problémy se scope ''openid'' a ''redirect_uri''. Device flow přes ''fnf-device-auth.higgsfield.ai'' funguje bez redirect URI, ale vrací token jen na 24 hodin. Prakticky nejlepší workaround byl zkopírovat Higgsfield access token z Claude Code credentials, uložit ho do ''~/.config/opencode/higgsfield.token'' a v OpenCode posílat ''Authorization: Bearer {file:./higgsfield.token}'' s ''oauth: false''. Jako úplně jiná cesta existují lokální komunitní MCP servery nad API key/API secret, hlavně ''higgsfield_ai_mcp'' a ''geo_higgsfield_ai_mcp'', ale ty nejsou totéž co oficiální Higgsfield remote MCP endpoint.
+Claude Code fungoval, protože použil předregistrovaný OAuth flow a callback ''localhost:65498''. V Dockeru bylo nutné tento port publikovat na hosta. OpenCode v mém prostředí narazil na OAuth problémy se scope ''openid'' a ''redirect_uri''. Device flow přes ''fnf-device-auth.higgsfield.ai'' funguje bez redirect URI, ale vrací token jen na 24 hodin bez refresh tokenu. Prakticky nejlepší workaround pro remote MCP byl zkopírovat Higgsfield access token i refresh token z Claude Code credentials, uložit je do ''~/.config/opencode/higgsfield.token'' a ''higgsfield_refresh.token'' a v OpenCode posílat ''Authorization: Bearer {file:./higgsfield.token}'' s ''oauth: false''. Access token vyprší za 24 hodin – pro automatické obnovení slouží refresh skript, který volá Higgsfield OAuth endpoint bez prohlížeče, a cron ho spouští každých 20 hodin. Vedle toho je dnes důležitá oficiální cesta přes Higgsfield CLI a Higgsfield AI Skills; neoficiální lokální MCP wrappery nad API key/API secret dávají smysl už jen jako fallback, pokud je potřeba lokální MCP server a oficiální cesty nestačí.
 ===== Zdroje =====
@@ Řádek 414: / Řádek 717: @@
   * [[https://higgsfield.ai/mcp|Higgsfield MCP – oficiální stránka]]
   * [[https://mcp.higgsfield.ai/mcp|Higgsfield MCP endpoint]]
+  * [[https://github.com/higgsfield-ai/cli|Higgsfield CLI – oficiální repozitář]]
+  * [[https://github.com/higgsfield-ai/skills|Higgsfield AI Skills – oficiální repozitář]]
   * [[https://mcp.higgsfield.ai/.well-known/oauth-protected-resource|Higgsfield OAuth protected resource discovery]]
   * [[https://fnf-device-auth.higgsfield.ai/openapi.json|Higgsfield device auth OpenAPI schema]]