Rozdíly

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

--- ai:mcp:klienti:higgsfield-mcp-v-claude-code-a-opencode [02.05.2026 08:04] – Nový článek o nasazení Higgsfield MCP v Claude Code a OpenCode Petr Nosek
+++ ai:mcp:klienti:higgsfield-mcp-v-claude-code-a-opencode [02.05.2026 08:23] (aktuální) – Doplnění alternativních komunitních MCP serverů pro Higgsfield 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 a nakonec pomohlo použít token získaný přes Claude Code.
+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.
 ===== Výchozí stav =====
@@ Řádek 120: / Řádek 120: @@
 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.
-===== Funkční workaround: token z Claude Code pro OpenCode =====
+===== 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 =====
+Později jsem našel pokyn pro OpenClaw, že Higgsfield MCP podporuje OAuth device flow. To je pro OpenCode zajímavé, protože device flow nepotřebuje lokální ''redirect_uri'' ani callback port do Docker kontejneru. Uživatel jen otevře autorizační odkaz, potvrdí přihlášení a agent mezitím polluje token endpoint.
+[[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://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:
+  * ''POST /authorize'' – vrátí ''device_code'', ''verification_uri'', ''expires_in'' a ''interval''
+  * ''POST /token'' – po potvrzení uživatelem vrátí ''access_token'', ''token_type'' a ''expires_in''
+==== Ruční spuštění device flow ====
+Získání device kódu:
+<code bash>
+curl -s https://fnf-device-auth.higgsfield.ai/authorize \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+</code>
+Odpověď má tvar:
+<code json>
+{
+  "device_code": "...",
+  "verification_uri": "https://higgsfield.ai/device?code=...",
+  "expires_in": 600,
+  "interval": 5
+}
+</code>
+Uživatel otevře ''verification_uri'' v prohlížeči a přihlásí se do Higgsfield účtu. Po potvrzení se začne pollovat token endpoint:
+<code bash>
+curl -s https://fnf-device-auth.higgsfield.ai/token \
+  -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{"device_code":"SEM_VLOZ_DEVICE_CODE"}'
+</code>
+Po úspěšném potvrzení se vrátí Bearer token:
+<code json>
+{
+  "access_token": "...",
+  "token_type": "Bearer",
+  "expires_in": 86400
+}
+</code>
+Tento token je možné uložit do stejného souboru, který používá OpenCode:
+<code bash>
+install -m 600 /dev/null /home/ubuntu/.config/opencode/higgsfield.token
+# do souboru zapsat pouze access_token, bez uvozovek a bez prefixu Bearer
+</code>
+OpenCode konfigurace zůstává stejná jako u Bearer workaroundu:
+<code json>
+"higgsfield": {
+  "type": "remote",
+  "url": "https://mcp.higgsfield.ai/mcp",
+  "headers": {
+    "Authorization": "Bearer {file:./higgsfield.token}"
+  },
+  "oauth": false,
+  "enabled": true
+}
+</code>
+==== Nevýhoda device flow ====
+Device flow se podařilo dokončit a token fungoval, ale v odpovědi byl parametr:
+<code>
+"expires_in": 86400
+</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ší.
+===== Preferovaný workaround: token z Claude Code pro OpenCode =====
 Protože Claude Code už měl vůči Higgsfield úspěšně získaný OAuth token, nejrychlejší funkční řešení bylo:
@@ Řádek 189: / Řádek 358: @@
 </code>
-Pokud se později začne vracet ''401 Unauthorized'', nejpravděpodobnější příčina je expirovaný token. Pak je potřeba znovu provést přihlášení v Claude Code přes ''/mcp'' a zkopírovat nový ''accessToken'' do ''higgsfield.token''.
+Pokud se později začne vracet ''401 Unauthorized'', nejpravděpodobnější příčina je expirovaný token. Pak jsou dvě možnosti:
+  * znovu provést přihlášení v Claude Code přes ''/mcp'' a zkopírovat nový ''accessToken'' do ''higgsfield.token''
+  * použít device flow, ale počítat s platností tokenu jen 24 hodin
 ===== Rychlý troubleshooting pro budoucí řešení =====
@@ Řádek 203: / Řádek 375: @@
 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.
+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.
 ==== Chyba: redirect_uri nesedí ====
@@ Řádek 215: / Řádek 387: @@
 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.
+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.
 ==== Claude Code auth link se otevře, ale callback neprojde ====
@@ Řádek 230: / Řádek 402: @@
   * Soubor ''higgsfield.token'' držet mimo git a nastavit mu práva jen pro uživatele.
   * Token v článku, logu ani chatu nevypisovat.
-  * Pokud token expiruje nebo je kompromitovaný, znovu se přihlásit přes Claude Code a token obnovit.
+  * Device flow token má podle testu platnost 24 hodin, takže se rychleji stane neplatným.
+  * Pokud token expiruje nebo je kompromitovaný, znovu se přihlásit přes Claude Code nebo spustit device flow a token obnovit.
+  * 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.
 ===== 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''. Praktický workaround je 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''.
+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.
 ===== Zdroje =====
@@ Řádek 240: / Řádek 414: @@
   * [[https://higgsfield.ai/mcp|Higgsfield MCP – oficiální stránka]]
   * [[https://mcp.higgsfield.ai/mcp|Higgsfield MCP endpoint]]
+  * [[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]]
+  * [[https://github.com/geopopos/higgsfield_ai_mcp|geopopos/higgsfield_ai_mcp]]
+  * [[https://github.com/geopopos/geo_higgsfield_ai_mcp|geopopos/geo_higgsfield_ai_mcp]]
   * [[ai:mcp:klienti:gemini-mcp|Gemini MCP v OpenCode]]