WordPress Abilities API Nedir? Örneklerle Rehber

WordPress Abilities API, sitenizin yapabildiği işleri adı, girdi ve çıktı şeması ve izin kuralıyla tek bir kayıt defterine yazmanızı sağlar. Hem insanlar hem de yapay zeka ajanları gibi dış sistemler bu işleri aynı biçimde keşfedip çalıştırabilir. API, WordPress 6.9 ile çekirdeğe girdi.

Bu rehber bir ability’nin ne olduğunu, PHP ile nasıl kaydedileceğini, REST üzerinden nasıl çalıştırılıp doğrulanacağını ve MCP Adapter ile ilişkisini anlatıyor. Örnek kod resmî geliştirici dokümanı ve 6.9 geliştirici notundaki yapıya dayanır; canlı siteye koymadan önce bir test sitesinde deneyin.

WordPress Abilities API nedir?

Bir “ability”, sitede yapılabilen tek bir işin tanımıdır: örneğin “yayınlanmış yazı sayısını ver”. Her ability şu parçalardan oluşur:

Girdi ve çıktı çalıştırma sırasında bu şemalara göre doğrulanır. Hata durumunda WP_Error döndürmek, resmî notun da kullandığı yoldur. Resmî tanım için Abilities API dokümanına bakın.

Neden Abilities API?

Bugüne kadar bir eklentinin yaptığı işi dışarıdan çağırmak için herkes kendi REST rotasını, kendi izin kontrolünü ve kendi dokümantasyonunu yazıyordu. Abilities API bunu ortak biçime çeviriyor:

• Çekirdek, eklenti ve tema yeteneklerini tek yerden listeleyebilirsiniz.
• Girdi ve çıktı şeması makine tarafından okunabildiği için bir istemci ability’yi önceden anlayabilir.
• İzin kontrolü ability’nin içinde tanımlı olduğundan her çağrı kanalında aynı kural geçerlidir.

Gerekenler

• WordPress 6.9 veya üstü. Daha eski sürümde wp_register_ability fonksiyonu yoktur.
• Kodu koyacağınız bir eklenti (ya da tema functions.php).
• Test için kimlik doğrulama: yönetici kullanıcıya bir uygulama parolası.

Eklenti kodunuz API’nin varlığını kontrol etmeli. Basit bir koruma:

if ( ! function_exists( 'wp_register_ability' ) ) {
	return;
}

Adım adım: ilk ability’yi kaydetme

Örnekte yayınlanmış içerik sayısını döndüren bir ability yazacağız.

1. Kategori kaydı

Kategori wp_abilities_api_categories_init kancasında tanımlanır.

add_action( 'wp_abilities_api_categories_init', 'benim_kategorim' );

function benim_kategorim() {
	wp_register_ability_category(
		'site-bilgisi',
		array(
			'label'       => __( 'Site bilgisi', 'benim-eklentim' ),
			'description' => __( 'Site hakkında bilgi veren yetenekler.', 'benim-eklentim' ),
		)
	);
}

2. Ability kaydı

Ability’ler wp_abilities_api_init kancasında kaydedilir.

add_action( 'wp_abilities_api_init', 'benim_ability_kaydi' );

function benim_ability_kaydi() {
	wp_register_ability(
		'benim-eklentim/icerik-sayisi',
		array(
			'label'               => __( 'Yayınlanmış içerik sayısı', 'benim-eklentim' ),
			'description'         => __( 'Seçilen içerik türünde yayınlanmış kayıt sayısını döndürür.', 'benim-eklentim' ),
			'category'            => 'site-bilgisi',
			'input_schema'        => array(
				'type'       => 'object',
				'properties' => array(
					'post_type' => array(
						'type'        => 'string',
						'description' => __( 'İçerik türü. Varsayılan: post', 'benim-eklentim' ),
					),
				),
			),
			'output_schema'       => array(
				'type'       => 'object',
				'properties' => array(
					'sayi' => array(
						'type'        => 'integer',
						'description' => __( 'Yayınlanmış kayıt sayısı', 'benim-eklentim' ),
					),
				),
			),
			'execute_callback'    => 'benim_icerik_sayisi',
			'permission_callback' => function () {
				return current_user_can( 'edit_posts' );
			},
			'meta'                => array(
				'show_in_rest' => true,
			),
		)
	);
}

function benim_icerik_sayisi( $input ) {
	$post_type = isset( $input['post_type'] ) ? sanitize_key( $input['post_type'] ) : 'post';

	if ( ! post_type_exists( $post_type ) ) {
		return new WP_Error( 'gecersiz_icerik_turu', __( 'Bu içerik türü yok.', 'benim-eklentim' ) );
	}

	$sayilar = wp_count_posts( $post_type );

	return array( 'sayi' => (int) $sayilar->publish );
}

Dikkat edilecek noktalar:

• permission_callback ability’nin kimin tarafından çalıştırılabileceğini belirler. Dışarıya açacaksanız mutlaka yazın; burada yazı düzenleme yetkisi arıyoruz.
• meta.show_in_rest değerini true yapmadıkça ability REST üzerinden görünmez.
• execute_callback girdiyi tek parametre olarak alır. Çıktı, output_schema’ya uymalı; örnekteki (int) dönüşümü bu yüzden var.

3. PHP içinden çalıştırma

Başka bir koddan ability’yi şöyle çağırırsınız:

add_action( 'init', function () {
	$ability = wp_get_ability( 'benim-eklentim/icerik-sayisi' );

	if ( ! $ability ) {
		return;
	}

	$sonuc = $ability->execute( array( 'post_type' => 'page' ) );

	if ( is_wp_error( $sonuc ) ) {
		error_log( $sonuc->get_error_message() );
		return;
	}

	error_log( 'Sayfa sayısı: ' . $sonuc['sayi'] );
} );

wp_has_ability() varlık kontrolü, wp_get_abilities() ise kayıtlı tüm yetenekleri verir. Çalıştırma öncesi ve sonrası için wp_before_execute_ability ve wp_after_execute_ability eylemleri de bulunur.

REST API ile çalıştırma ve doğrulama

show_in_rest açık ability’ler wp-abilities/v1 ad alanında görünür. Temel uç noktalar:

Resmî geliştirici notundaki çalıştırma örneği POST kullanıyor ve girdiyi JSON gövdesinde input anahtarıyla gönderiyor. Harici testte uygulama parolası kullanılır.

Kaydın işe yaradığını doğrulamak için önce listeye bakın:

curl -u 'KULLANICI:UYGULAMA_PAROLASI' \
  https://ornek.com/wp-json/wp-abilities/v1/abilities

Sonra ability’yi çalıştırın:

curl -u 'KULLANICI:UYGULAMA_PAROLASI' \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"input":{"post_type":"page"}}' \
  https://ornek.com/wp-json/wp-abilities/v1/abilities/benim-eklentim/icerik-sayisi/run

Yanıtta çıktı şemasına uygun bir nesne görmelisiniz (örnekte sayi alanı; değer sitenize göre değişir). Ability listede görünmüyorsa meta içinde show_in_rest değerinin true olduğunu ve ad alanının doğru yazıldığını kontrol edin.

JavaScript tarafı (WordPress 7.0)

7.0 ile istemci tarafı karşılığı geldi ve iki pakete bölündü:

• @wordpress/abilities: Depo, kayıt, sorgulama ve çalıştırma. WordPress’e bağımlı değildir.
• @wordpress/core-abilities: Sunucuda PHP ile kayıtlı yetenekleri ve kategorileri REST üzerinden çekip istemci deposuna yazar.

Çekirdek @wordpress/core-abilities paketini yönetici sayfalarında yüklediği için PHP’de kaydettiğiniz ability’ler ek kod olmadan istemcide de görünür. Tarayıcıya özel işler (bir ekrana gitmek, blok eklemek gibi) için registerAbility ile istemci tarafında ability tanımlanır. Ayrıntı için istemci tarafı Abilities API duyurusuna bakın.

WordPress Abilities API ve MCP Adapter ilişkisi

Abilities API yalnızca kayıt ve çalıştırma katmanıdır; yapay zeka istemcileriyle konuşan kısım değildir. Bu köprüyü resmî MCP Adapter kurar. MCP Adapter, ability’leri Model Context Protocol’ün araç, kaynak ve istem biçimine çevirir. Ayrı bir eklentidir; WordPress.org’daki sayfasına göre sürümü 0.7.1, gereksinimi WordPress 6.9+ ve PHP 7.4+.

İlişkiyi üç noktada özetleyebiliriz:

1. Varsayılan olarak gizli. Ability’ler MCP’ye kapalıdır. Açmak için meta içine 'public' => true yazarsınız.
2. Üç meta-araç. Varsayılan sunucu mcp-adapter/discover-abilities, mcp-adapter/get-ability-info ve mcp-adapter/execute-ability araçlarını sunar; istemci ability’lerinizi bunlar üzerinden bulur ve çağırır.
3. Adres. Varsayılan sunucuya /wp-json/mcp/mcp-adapter-default-server üzerinden HTTP ile bağlanılır; WP-CLI ile STDIO de desteklenir.

Örnekteki ability’yi MCP’ye açmak için meta dizisini şöyle genişletirsiniz:

'meta' => array(
	'show_in_rest' => true,
	'public'       => true,
),

public yalnızca ability’nin istemcilere açık olduğunu işaretler; çalıştırma yetkisi vermez. İzin yine permission_callback ile belirlenir. Bu yüzden bir ability’yi açarken en dar yetkiyi seçin ve yazma ya da silme yapan ability’leri bilerek, ayrı ayrı açın.

Bu eklentiyi bir yapay zeka istemcisine bağlamanın yolları için Claude WordPress bağlantısı yöntemleri yazısına, Elementor’a özgü kurulum için Elementor MCP rehberine bakabilirsiniz.

İyi bir ability nasıl tasarlanır?

Kod yazmadan önce kısa bir tasarım yapmak, sonradan değiştirmek zorunda kalmanızı önler.

• Tek iş, tek ability. “Yazı sayısını ver” ile “yazıyı sil” ayrı ability’lerdir. Birleştirirseniz izin ayarını doğru yapamazsınız.
• Okunur isimler. Ad eklenti-adi/fiil-nesne gibi olsun (benim-eklentim/icerik-sayisi). İstemciler adı ve açıklamayı okuyarak ability’nin ne yaptığını anlar; belirsiz açıklama yanlış kullanıma yol açar.
• Dar girdi şeması. Serbest metin yerine mümkün olduğunca sınırlı değerler (sayı, seçenek listesi) kabul edin. Şema ne kadar dar olursa doğrulama o kadar işe yarar.
• En dar yetki. Salt okunur bilgi için edit_posts, ayar değiştiren işler için manage_options gibi gerçekten gereken yetkiyi isteyin.
• Hata durumunda WP_Error. İstisna fırlatmak yerine anlamlı bir hata kodu ve mesaj döndürün.

Şunu da göz önünde bulundurun: ability, sitenizin bir yeteneğini dış dünyaya tanımlar. Yazma ve silme yapan ability’leri yapay zeka istemcilerine açmadan önce ne olabileceğini düşünün. Yanlış anlaşılan bir istek, siz fark etmeden veri değiştirebilir.

Eklentinize ability desteği eklemek ya da sitenizi yapay zeka araçlarına güvenle açmak için yardım isterseniz iletişim sayfasından ulaşabilirsiniz; yaptığım işler hizmetler sayfasında.

Sonuç

Abilities API, bir işi bir kez tanımlayıp REST, PHP, JavaScript ve MCP gibi farklı kanallardan aynı kurallarla çalıştırmanın standart yolu. Başlamak için bir kategori, bir ability ve doğru izin kontrolü yeterli. Sonrasında curl ile listeleyip çalıştırarak kaydın doğru olduğunu görebilirsiniz.

Sürümle ilgili geniş resim için WordPress 7.0 yenilikleri yazısına bakın.