MCP-szerver hibaelhárítása

Ha a szerver nem csatlakozik, vagy egy eszközhívás hibával tér vissza, innen indulj. Minden pont egy tünetet és a javítását írja le.

Kapcsolat

Nem lehet csatlakozni a MainWP vezérlőpulthoz

A szerver nem éri el a vezérlőpultot, az eszközhívások kapcsolati hibát adnak. Rétegenként, sorban teszteld. Először azt, hogy az URL válaszol-e:

curl -I https://a-te-vezerlopultod.hu/wp-json/

A 200-as válasz azt jelenti, hogy a WordPress REST elérhető. Utána a hitelesítést:

curl -u "felhasznalonev:alkalmazasjelszo" https://a-te-vezerlopultod.hu/wp-json/wp/v2/users/me

Ennek a profilodat kell visszaadnia. Végül az Abilities API-t:

curl -u "felhasznalonev:alkalmazasjelszo" "https://a-te-vezerlopultod.hu/wp-json/wp-abilities/v1/abilities?per_page=1"

Ha csak az utolsó lépés bukik el, a MainWP Abilities API nem érhető el a vezérlőpulton: ellenőrizd, hogy a MainWP vezérlőpult 6.0-s vagy újabb, és naprakész-e.

SSL-tanúsítvány hiba

UNABLE_TO_VERIFY_LEAF_SIGNATURE vagy hasonló. Élesben a tanúsítványt javítsd: telepítsd a teljes láncot, egyeztesd a tartományt, ellenőrizd a lejáratot. Csak önaláírt tanúsítványos, helyi fejlesztésnél állítsd be: "skipSslVerify": true.

A dashboardUrl HTTP-t használ, amely nyílt szövegben továbbítja a hitelesítő adatokat

A szerver blokkolja a HTTP-címeket, mert a hitelesítő adatok titkosítatlanul utaznának. Állíts be HTTPS-t a vezérlőpulton. Ha szándékosan HTTP-n futtatsz helyi fejlesztésben, állítsd be: "allowHttp": true.

ECONNREFUSED vagy ETIMEDOUT

A vezérlőpult nem érhető el az AI-klienst futtató gépről. Ellenőrizd, hogy az URL és a port helyes-e, fut-e a vezérlőpult, és nincs-e tűzfal vagy VPN az úton. A DNS-hibákat úgy különítheted el, hogy a gépnév helyett a szerver IP-címével próbálkozol.

Hitelesítés

401 Unauthorized

Annak a felhasználónak a WordPress-belépési nevét vagy e-mail-címét add meg, akié az Application Password, ne a megjelenített nevét. Az Application Passwordöt használd, ne a fiók belépési jelszavát; a megjelenítésben látható szóközökkel és anélkül is működik. Néhány biztonsági bővítmény letiltja az Application Passwordöket.

Ha a telepítés credentials_rejected állapotot jelez, a mainwp_get_setup_status újrapróbálkozás nélkül megmutatja az elutasított felhasználót és a konfigurációs forrásokat. Javítsd a ténylegesen érvényes forrást, és indítsd újra a klienst. Részletek: Az MCP-szerver beállításai, „Elutasított hitelesítő adatok”.

403 Forbidden

Nézd meg a válasz részleteit. Lehet, hogy a felhasználóból hiányzik egy szükséges WordPress-jogosultság, vagy egy biztonsági bővítmény, tűzfal vagy proxy blokkolja a kérést. Az ismert WordPress-hitelesítési elutasítási kódot tartalmazó 403 azt is jelentheti, hogy az Application Password hitelesítése nem sikerült. Egy puszta 403 még nem bizonyítja, hogy a hitelesítő adatok hibásak.

A bearer token nem működik

Ez várt viselkedés. A MAINWP_TOKEN bearer hitelesítés nem működik a WordPress Abilities API ellen, mert az a WordPress saját hitelesítésén megy át. Állítsd be helyette a MAINWP_USER és a MAINWP_APP_PASSWORD változót Application Passworddel.

Eszközhibák

Az eszköz nem található

Ellenőrizd a helyesírást: az eszköznevekben aláhúzás van (list_sites_v1, nem list-sites-v1). Ha a név helyes, lehet, hogy az allowedTools vagy blockedTools beállításod elrejti az eszközt, vagy a képesség nem létezik a vezérlőpult verzióján.

SAFE_MODE_BLOCKED

A biztonságos mód be van kapcsolva, és az AI romboló műveletet próbált végrehajtani. A biztonságos mód ilyenkor a dolgát teszi. Ha valóban engedélyezni akarod a romboló műveleteket, állítsd be: "safeMode": false.

Megerősítés szükséges

A romboló eszközök kétlépéses folyamatot követnek: előnézet, a te jóváhagyásod, végrehajtás. Ha az AI nem tartja be, kérd kifejezetten: „Először mutasd meg, mit fogsz törölni.” Felügyelet nélküli automatizálásnál, ha ellenőrizted a célpontokat, kikapcsolhatod: "requireUserConfirmation": false.

Megerősítési folyamat

PREVIEW_REQUIRED

Az AI érvényes előnézet nélkül próbált romboló műveletet végrehajtani: nem kért előnézetet, a token már fel van használva (a tokenek egyszer használhatók), vagy a token más argumentumokhoz tartozik. Általában az AI viselkedési hibája. Fogalmazd át: „Mutasd meg, mit fogsz törölni, utána jóváhagyom.”

CONFIRMATION_REQUIRED, az előnézet értéke null

Ez nem hiba. A képesség megerősítést igényel, de nem tud száraz futtatási előnézetet készíteni, ezért nincs mit mutatni. A válasz ettől még tartalmaz megerősítő tokent: az AI-nak el kell mondania, mit fog tenni a művelet, és meg kell várnia a kifejezett jóváhagyásodat, mielőtt megerősíti.

PREVIEW_EXPIRED

Az előnézet és a megerősítésed között több mint 5 perc telt el. Mondd újra, hogy „igen, hajtsd végre”, és az AI új előnézetet kér.

CONFLICTING_PARAMETERS

Az AI egyszerre küldte a user_confirmed: true és a dry_run: true értéket. A kettő ellentétes jelentésű (végrehajtás, illetve csak előnézet), ezért csak az egyiket szabad küldeni.

CONFIRMATION_UNSUPPORTED: a romboló művelet nem erősíthető meg

A képesség rombolónak van minősítve, de a sémája nem deklarál használható confirm paramétert, így a megerősítési folyamat nem futhat, és a szerver megtagadja a végrehajtást. A beépített törlő eszközök mind deklarálják a confirm paramétert, náluk ez nem fordul elő. Ha egy harmadik féltől származó képesség váltja ki, javítsd a jelöléseit a vezérlőpult oldalán, vagy kezeld kifejezetten az allowedTools és blockedTools beállítással.

Erőforráskorlátok

RESOURCE_EXHAUSTED: a munkamenet adatkorlátja túllépve

A válaszok összesített adatmennyisége átlépte a maxSessionData értékét. Indítsd újra az MCP-szervert a számláló nullázásához, emeld a korlátot, vagy használj szűkebb lekérdezéseket és lapozást.

A válasz túl nagy

Egyetlen válasz átlépte a maxResponseSize értékét. Emeld a korlátot, vagy szűkítsd a választ szűrőkkel (állapotszűrők, kisebb per_page).

A bemenet túl hosszú, vagy a kérés URL-je túl hosszú

Nézd meg a hibában a paramétert és a ténylegesen érvényes korlátot. A karakterláncok alapból 10 000 karakterig fogadhatók, kivéve ha az eszköz bemeneti sémája érvényes maxLength értéket deklarál. A GET és DELETE kéréseknél a teljes kódolt URL-nek is van egy 8000 karakteres korlátja. Csökkentsd a bemenetet, vagy ahol az eszköz támogatja, bontsd részekre a műveletet. A válaszméret-beállítások emelése ezeket a korlátokat nem változtatja. A séma felső határáról, a beágyazási korlátokról és az stdio-megkötésekről a Az MCP-szerver beállításai fejezet „Bemeneti korlátok” része szól.

A kérésszám korlátja túllépve

Túl sok API-hívás ment egy percen belül. Várj és próbáld újra, vagy emeld a rateLimit értékét. A 0 kikapcsolja a korlátozást, éles környezetben ez nem ajánlott.

Konfiguráció

A konfigurációs fájl nem található

A szerver először a ./settings.json fájlt (a saját munkakönyvtárában), utána a ~/.config/mainwp-mcp/settings.json fájlt keresi. Ellenőrizd, hogy a fájl ott van-e, ahonnan a szerver fut, és érvényes JSON-e:

jq . settings.json

A környezeti változók nem érvényesülnek

A változókat exportálni kell (export MAINWP_URL="https://..."), a nevek kis- és nagybetűkre érzékenyek, és az értékekben ne legyenek beágyazott idézőjelek. Ne feledd, hogy az AI-eszközöd konfigurációjában az eszközönkénti env blokkok felülírják a settings.json értékeit.

Az AI-eszköz nem mutatja a MainWP eszközeit

Először ellenőrizd a konfigurációs fájl JSON-ját, és indítsd újra a gazdaalkalmazást: a legtöbb eset ezzel megoldódik. Kliensspecifikus ellenőrzések:

• Claude Desktop: ellenőrizd a konfigurációs fájl elérési útját az operációs rendszeredhez.
• Claude Code: nézd meg a ~/.claude.json fájlt.
• VS Code: legalább 1.101-es verzió kell, megnyitott munkaterület (nem egyetlen fájl) és bekapcsolt Agent Mode.

Az egyes kliensek konfigurációs helyeit az AI-kliensek csatlakoztatása fejezetben találod.

Ha csak a mainwp_get_setup_status és a mainwp_configure eszközt látod, hívd meg a mainwp_get_setup_status eszközt az állapot azonosításához. Lehet unconfigured (hiányoznak a kapcsolati adatok), degraded (a kapcsolat ellenőrzése nem sikerült) vagy credentials_rejected (a vezérlőpult elutasította a betöltött hitelesítő adatokat). Lásd: Az MCP-szerver beállításai, „Első indítás” és „Elutasított hitelesítő adatok”.

Az asszisztens szerint a telepítés nem cseréli le a hitelesítő adataimat

Megkérted az asszisztenst, hogy csatlakoztassa újra a szervert, vagy állítsa be új Application Passworddel, és a mainwp_configure azzal az üzenettel utasította el, hogy a szerverben már vannak betöltött hitelesítő adatok.

Ez szándékos, nem hiba. A csevegésen át történő telepítés a még kapcsolat nélküli szervert csatlakoztatja, a te kézzel beállított adataidat soha nem írja felül. Az indoklás a beállítások fejezetben van („Miért nem cseréli le a telepítés a meglévő adataidat?”): az asszisztens a kapott szöveg alapján cselekszik, a szöveg pedig olyan helyről is hozhat utasítást, ahonnan nem szeretnéd, ezért az a szerver, amelyet egy beszélgetésből át lehet irányítani, átirányítható valaki más vezérlőpultjára is.

Hogy mit tegyél, az attól függ, miért nem működik a kapcsolat:

• A vezérlőpult nem volt elérhető, újraindult vagy átmenetileg nem válaszolt. Kérd meg az asszisztenst, hogy ellenőrizze újra a kapcsolatot: ez a mainwp_get_setup_status hívást jelenti. Az a szerverben már meglévő hitelesítő adatokkal újrapróbálkozik, és amint a vezérlőpult válaszol, csatlakozik. Más teendő nincs.
• A tárolt jelszó hibás, leggyakrabban azért, mert lecserélted. Ha az állapot credentials_rejected, a szerver nem küldi el újra. A mainwp_get_setup_status segítségével azonosítsd a konfigurációs forrást, majd te magad frissítsd:
  1. A WordPressben a profiloldaladon hozz létre egy Application Passwordöt, vagy másold ki az újonnan létrehozottat.
  2. Frissítsd a connectionSources mezőben megjelölt forrást: az env vagy a settings.json fájlt. Fájlalapú értékeknél a munkakönyvtár settings.json fájlja töltődik be előbb, mint a ~/.config/mainwp-mcp/settings.json. Fájl szerkesztése előtt nézd meg az overriddenSettingsKeys mezőt: a környezeti értékek elsőbbséget élveznek.
  3. Indítsd újra az MCP-klienst, hogy a szerver felvegye.
• Másik vezérlőpultra akarod irányítani a szervert. Ugyanaz: szerkeszd az URL-t és a hitelesítő adatokat ott, ahol be vannak állítva, majd indítsd újra a klienst.

Ha a szervernek egyáltalán nincsenek hitelesítő adatai, mindez nem érvényes, és a csevegéses telepítés rendesen működik: kérd meg az asszisztenst, hogy állítsa be a MainWP-kapcsolatot, és végigvezet.

Hibakeresés

Gyakorlati hibakereséshez futtasd közvetlenül a szervert, és figyeld a stderr kimenetet:

MAINWP_URL="https://a-te-vezerlopultod.hu" \
MAINWP_USER="admin" \
MAINWP_APP_PASSWORD="xxxx xxxx xxxx xxxx xxxx xxxx" \
npx -y @mainwp/mcp

Az egészséges szerver indulási üzeneteket ír a stderr-re, majd csendben vár az MCP-parancsokra az stdin-en. Ha letöltötted a szerver tárolóját, az npm run inspect megnyitja az MCP Inspectort: ez webes felület, amelyben listázhatod az eszközöket, egyéni argumentumokkal futtathatod őket, és láthatod a nyers kérés- és válaszadatokat. Ha így sem jutsz előre, hozz létre hibajegyet a szerver GitHub-tárolójában a stderr kimenettel és a konfigurációddal (a hitelesítő adatok nélkül).

A védelmek működéséről az Az MCP-szerver biztonsága fejezetben olvashatsz.