WordPress Abilities API

WordPress Abilities API to rejestr operacji, które wtyczka, motyw albo sam rdzeń deklaruje w jednym, przewidywalnym formacie: nazwa, kategoria, schemat wejścia i wyjścia, sprawdzenie uprawnień i funkcja wykonująca. Ta strona jest referencją: co to jest, jak zarejestrować ability, jakie są endpointy REST, jak działają uprawnienia, co dodały wersje 7.0 i 7.1 oraz gdzie wchodzi MCP Adapter. Jeśli szukasz przykładów workflowów zbudowanych na abilities, zajrzyj do artykułu Abilities API w praktyce, czyli workflowy AI w WordPressie.

#Co to jest WordPress Abilities API

Dev note z make.wordpress.org definiuje pojedynczą ability tak:

“Ability to samodzielna jednostka funkcjonalności ze zdefiniowanymi danymi wejściowymi, wyjściowymi, uprawnieniami i logiką wykonania.”

Jonathan Bossenger, Make WordPress Core, Abilities API in WordPress 6.9, tłumaczenie własne

Wszystkie zarejestrowane abilities trafiają do centralnego rejestru. Z tego rejestru korzysta kod PHP na serwerze, klient JavaScript w panelu, REST API i agenci AI podłączeni przez MCP Adapter. Wtyczka opisuje operację raz, a każdy z tych kanałów widzi ją w tym samym kształcie, z tym samym schematem i tym samym sprawdzeniem uprawnień.

Ogłoszenie wydania 6.9 ujmuje to od strony uprawnień:

“Nowe Abilities API zapewnia ustandaryzowany, czytelny maszynowo system uprawnień, który otwiera drogę do przepływów pracy nowej generacji opartych na AI i automatyzacji.”

WordPress News, WordPress 6.9 “Gene”, tłumaczenie własne

Każda ability należy do dokładnie jednej kategorii:

“Każda ability musi należeć do dokładnie jednej kategorii. Kategorie mają slug, etykietę i opis.”

Common APIs Handbook, Abilities API, tłumaczenie własne

#Od której wersji WordPress jest Abilities API

Abilities API weszło do rdzenia w WordPressie 6.9, wydanym 2 grudnia 2025. Handbook mówi to wprost w ramce na górze strony:

“Abilities API jest dostępne tylko w WordPressie 6.9 i nowszych.”

Common APIs Handbook, Abilities API, tłumaczenie własne

Kolejne wydania rozbudowały API, nie zmieniając jego podstaw:

Wtyczka, która ma działać także na instalacjach starszych niż 6.9, sprawdza obecność funkcji przed rejestracją: dev note z make.wordpress.org zaleca warunek function_exists( 'wp_register_ability' ), którym otwiera się też przykład poniżej.

Szerszy kontekst wydania 7.0, w tym resztę zmian związanych z AI, opisuje nasz przewodnik po WordPressie 7.0 i integracji z AI.

#Jak zarejestrować ability w WordPress

Rejestracja ma dwa kroki: najpierw kategoria, potem ability. Każdy krok ma swój hook i kolejność ma znaczenie.

#Rejestracja kategorii ability

“Kategorie muszą zostać zarejestrowane przed abilities, które się do nich odwołują, za pomocą hooka wp_abilities_api_categories_init.”

Make WordPress Core, Abilities API in WordPress 6.9, tłumaczenie własne

Kategoria ma slug, etykietę i opis. Argument category przy rejestracji ability jest wymagany i musi wskazywać slug kategorii, która już istnieje w rejestrze.

#Hook wp_abilities_api_init

Samą ability rejestruje się na osobnej akcji. Rejestracja w innym miejscu nie przejdzie:

“Abilities muszą być rejestrowane na hooku akcji wp_abilities_api_init. Próba zarejestrowania abilities poza tym hookiem wywoła komunikat _doing_it_wrong(), a rejestracja Ability się nie powiedzie.”

Make WordPress Core, Abilities API in WordPress 6.9, tłumaczenie własne

#Przykład wp_register_ability

Sygnatura funkcji według Code Reference:

function wp_register_ability( string $name, array $args ): ?WP_Ability {

Źródło: Code Reference, wp_register_ability().

Przy sukcesie funkcja zwraca zarejestrowaną instancję WP_Ability, przy błędzie null. Minimalny przykład: kategoria i jedna ability tylko do odczytu, która zwraca liczbę opublikowanych wpisów.

if ( function_exists( 'wp_register_ability' ) ) {

	add_action( 'wp_abilities_api_categories_init', function () {
		wp_register_ability_category( 'moja-wtyczka', array(
			'label'       => 'Moja wtyczka',
			'description' => 'Operacje udostępniane przez Moją wtyczkę.',
		) );
	} );

	add_action( 'wp_abilities_api_init', function () {
		wp_register_ability( 'moja-wtyczka/liczba-wpisow', array(
			'label'               => 'Liczba opublikowanych wpisów',
			'description'         => 'Zwraca liczbę opublikowanych wpisów.',
			'category'            => 'moja-wtyczka',
			'output_schema'       => array( 'type' => 'integer' ),
			'permission_callback' => function () {
				return current_user_can( 'edit_posts' );
			},
			'execute_callback'    => function () {
				return (int) wp_count_posts()->publish;
			},
			'meta'                => array(
				'show_in_rest' => true,
				'annotations'  => array( 'readonly' => true ),
			),
		) );
	} );
}

Ta ability nie przyjmuje danych, więc nie ma input_schema. Zwraca wartość, więc output_schema jest obowiązkowy.

#Nazwa ability i przestrzeń nazw

“Format powinien mieć postać namespace/ability-name”

Make WordPress Core, Abilities API in WordPress 6.9, tłumaczenie własne

Nazwa składa się z małych liter, cyfr, myślników i ukośnika. Przestrzeń nazw to zwykle slug wtyczki, co zapobiega kolizjom między wtyczkami, które rejestrują podobne operacje.

#Schematy input_schema i output_schema

Schematy nie są dodatkiem dla dokumentacji. Rdzeń waliduje według nich dane wejściowe przed wykonaniem i dane wyjściowe po wykonaniu.

“Definiowanie schematów jest obowiązkowe, gdy istnieje wartość do przekazania lub zwrócenia.”

Make WordPress Core, Abilities API in WordPress 6.9, tłumaczenie własne

Walidator nie obsługuje pełnej specyfikacji JSON Schema:

“WordPress implementuje walidator oparty na podzbiorze JSON Schema w wersji 4.”

Make WordPress Core, Abilities API in WordPress 6.9, tłumaczenie własne

W praktyce oznacza to pisanie schematów w składni draft 4 i ostrożność ze słowami kluczowymi spoza tego podzbioru.

#Callbacki permission_callback i execute_callback

Oba callbacki są wymagane. Code Reference opisuje je tak:

“Wymagane. Funkcja callback sprawdzająca uprawnienia przed wykonaniem.”

Code Reference, wp_register_ability(), tłumaczenie własne

“Wymagane. Funkcja callback wykonywana, gdy ability zostaje wywołana.”

Code Reference, wp_register_ability(), tłumaczenie własne

Callback uprawnień widzi te same dane co callback wykonania, więc może podjąć decyzję zależną od konkretnego wejścia, na przykład pozwolić edytować tylko wpis, którego użytkownik jest autorem:

“Otrzymuje te same dane wejściowe co callback execute i musi zwrócić wartość logiczną lub WP_Error”

Code Reference, wp_register_ability(), tłumaczenie własne

#Obsługa błędów w execute_callback

Błąd zwraca się jako obiekt, a nie wyjątek czy pusty wynik:

“Abilities powinny łagodnie obsługiwać błędy, zwracając obiekty WP_Error:”

Make WordPress Core, Abilities API in WordPress 6.9, tłumaczenie własne

#Adnotacje readonly, destructive i idempotent

Adnotacje w meta.annotations opisują charakter operacji. readonly oznacza ability, która niczego nie zmienia:

“Opcjonalne. Jeśli true, ability nie modyfikuje swojego środowiska.”

Code Reference, wp_register_ability(), tłumaczenie własne

Pozostałe dwie adnotacje to destructive i idempotent. Nie są ozdobnikiem: od nich zależy metoda HTTP przy wywołaniu przez REST, a klient, na przykład agent AI, może po nich ocenić, czy operację wolno powtórzyć.

Na tej stronie działa nasz własny serwer MCP, opisany w /.well-known/mcp/server-card.json, i wystawia wyłącznie narzędzia do odczytu. Ta sama zasada sprawdza się przy abilities: pierwsza wersja integracji z agentem to abilities z readonly: true, wywoływane przez GET. Operacje zapisu dochodzą później, każda z własnym permission_callback.

#Endpointy REST Abilities API

W WordPressie 6.9 ability nie trafia do REST API automatycznie. Trzeba to zadeklarować:

“Jest to możliwe przez ustawienie argumentu meta.show_in_rest na true podczas rejestrowania ability.”

Make WordPress Core, Abilities API in WordPress 6.9, tłumaczenie własne

Endpointy działają w przestrzeni nazw wp-abilities/v1: lista abilities, pojedyncza ability i wykonanie. Ścieżka wykonania wygląda tak:

GET|POST|DELETE /wp-abilities/v1/abilities/{name}/run

Źródło: Make WordPress Core, Abilities API in WordPress 6.9.

#Uwierzytelnianie w Abilities API

“Dostęp do wszystkich endpointów REST API Abilities wymaga uwierzytelnionego użytkownika.”

Make WordPress Core, Abilities API in WordPress 6.9, tłumaczenie własne

Dotyczy to także listy abilities. Działa ciasteczko sesji, application passwords albo własny mechanizm uwierzytelniania. Anonimowy klient nie zobaczy nawet tego, jakie abilities istnieją na stronie.

#Jak wywołać ability przez REST

Metodę HTTP dla endpointu run wyznaczają adnotacje. Ability readonly wywołuje się przez GET, ability jednocześnie destructive i idempotent przez DELETE, a w pozostałych przypadkach:

“Wszystkie pozostałe przypadki: używa POST”

Jorge Costa, Make WordPress Core, Client-Side Abilities API in WordPress 7.0, tłumaczenie własne

Dokumentacja REST w repozytorium projektu podkreśla, że dla abilities tylko do odczytu to wymóg, a nie zalecenie:

”- Abilities tylko do odczytu muszą używać GET (readonly: true)”

GitHub, WordPress/abilities-api, docs/rest-api.md, tłumaczenie własne

Przy GET i DELETE dane wejściowe nie idą w ciele żądania, tylko w parametrze input jako JSON zakodowany w URL.

#Abilities API w JavaScript

WordPress 7.0 dodał klienta po stronie przeglądarki w dwóch pakietach. @wordpress/abilities to sam magazyn abilities, a @wordpress/core-abilities ładuje abilities zarejestrowane na serwerze przez REST:

“To załaduje zarówno @wordpress/core-abilities, jak i jego zależność @wordpress/abilities, a także automatycznie pobierze i zarejestruje wszystkie abilities po stronie serwera.”

Jorge Costa, Make WordPress Core, Client-Side Abilities API in WordPress 7.0, tłumaczenie własne

Błędy w kliencie JS mają stałe kody. Nieudana walidacja daje ability_invalid_input albo ability_invalid_output, a odmowa uprawnień:

“Jeśli callback uprawnień zwróci false, zgłaszany jest błąd z kodem ability_permission_denied.”

Jorge Costa, Make WordPress Core, Client-Side Abilities API in WordPress 7.0, tłumaczenie własne

#Abilities API w WordPress 7.1

Ogłoszenie wydania 7.1 streszcza zmiany jednym zdaniem:

“Abilities API rozwija infrastrukturę wprowadzoną w WordPressie 6.9 o filtrowalny cykl życia wykonania, niestandardową walidację i wspólne wykrywanie.”

WordPress News, WordPress 7.1 “Mary Lou”, tłumaczenie własne

#Flaga public w Abilities API

WordPress 7.1 wprowadził meta.public, wspólną flagę ekspozycji dla klientów. Wypełnia ona show_in_rest, ale jawnie podane show_in_rest ma pierwszeństwo, a domyślną wartością pozostaje false:

$show_in_rest = $meta['show_in_rest'] ?? $meta['public'] ?? false;

Źródło: Milana Cap, Make WordPress Core, A unified public exposure flag for Abilities in WordPress 7.1.

Flaga decyduje o widoczności, nie o dostępie:

“Flaga public kontroluje wykrywalność i udostępnianie klientom.”

Milana Cap, Make WordPress Core, A unified public exposure flag for Abilities in WordPress 7.1, tłumaczenie własne

Ability oznaczona jako publiczna nadal przechodzi przez permission_callback. Flaga public go nie zastępuje.

#Filtry cyklu wykonania ability

“Abilities API udostępniało wcześniej akcje wp_before_execute_ability i wp_after_execute_ability.”

Make WordPress Core, New execution lifecycle filters for the Abilities API in WordPress 7.1, tłumaczenie własne

Do tych dwóch akcji z 6.9 wersja 7.1 dodała cztery filtry:

Akcje pozwalały tylko obserwować wykonanie. Filtry pozwalają w nie ingerować, na przykład znormalizować wejście albo zmienić wynik sprawdzenia uprawnień.

#Abilities API a MCP Adapter

Abilities API nie zawiera serwera Model Context Protocol. Tę rolę pełni osobny pakiet:

“Oficjalny pakiet WordPressa do integracji z MCP, który udostępnia abilities WordPressa jako narzędzia, zasoby i prompty Model Context Protocol (MCP) dla agentów AI.”

GitHub, WordPress/mcp-adapter, README, tłumaczenie własne

Domyślne ustawienie jest zachowawcze:

“Abilities WordPressa są domyślnie prywatne.”

GitHub, WordPress/mcp-adapter, README, tłumaczenie własne

Żeby ability była widoczna dla klienta MCP, trzeba ustawić meta.public (albo meta.mcp.public) na true. Domyślny serwer adaptera wystawia trzy meta-narzędzia, przez które agent odkrywa i wywołuje abilities. Połączenie:

“Połącz się przez WP-CLI po STDIO albo skieruj klienta HTTP na /wp-json/mcp/mcp-adapter-default-server.”

GitHub, WordPress/mcp-adapter, README, tłumaczenie własne

STDIO przez WP-CLI pasuje do pracy lokalnej i na stagingu, HTTP do agenta działającego poza serwerem. W obu przypadkach o tym, co agent może zrobić, decydują te same permission_callback i adnotacje, które opisaliśmy wyżej.

Szerzej o tym, jak podłączyć WordPressa do agentów AI przez MCP, piszemy w przewodniku integracja MCP z AI w WordPressie. Jeśli potrzebujesz własnego serwera MCP albo zestawu abilities zaprojektowanego pod konkretny sklep czy serwis, opisaliśmy to na stronie budowa serwera MCP dla WordPressa.

#Jak sprawdzić, czy WordPress obsługuje Abilities API

Najprościej w kodzie: function_exists( 'wp_register_ability' ) zwraca true od wersji 6.9. Z zewnątrz, mając konto z application password, wystarczy zapytać o przestrzeń nazw wp-abilities/v1 w REST API strony. Jeśli jej nie ma, strona działa na wersji starszej niż 6.9 albo coś blokuje REST API. Lista zwróci tylko abilities z show_in_rest albo public ustawionym na true, więc pusta lista nie znaczy, że wtyczki nie rejestrują żadnych abilities.

Ostatnia weryfikacja źródeł: 6 października 2026.