Kendi WebMCP aracınızı ekleyin.

Başlamadan önce

WordPress sitenizde Cartonoma 0.8.2 veya üzeri etkin olmalı. Cartonoma ayarlarında herkese açık keşif ve WebMCP açık olmalı. Bu örnek için WooCommerce, Cartonoma hesabı veya ücretli paket gerekmez.

Kod WordPress eklentinizde çalışır. Cartonoma araç tanımını kaydeder, girdiyi doğrular ve sonucu döndürür. Destekleyen tarayıcılarda araçlar WebMCP üzerinden de sunulur. REST ile denemek için tarayıcının WebMCP desteğine ihtiyacınız yoktur.

Çalışan PHP örneği

Örnek, toplam öğe sayısını bir yaprağa sığan öğe sayısına böler ve yukarı yuvarlar. 10 öğe ve yaprak başına 3 öğe için 4 yaprak gerekir. Bu yalnızca adet hesabıdır; ölçü, yerleşim, fire veya fiyat hesabı yapmaz.

Aşağıdaki dosyayı oluşturun ve kodun tamamını içine yapıştırın:

wp-content/plugins/cartonoma-example-tools/cartonoma-example-tools.php

<?php
/**
 * Plugin Name: Cartonoma Example Tools
 * Description: Developer example: calculate sheet count without creating a quote.
 * Version: 1.0.0
 * Requires PHP: 7.4
 * License: GPL-2.0-or-later
 */
defined('ABSPATH') || exit;

add_action('cartonoma_register_tools', static function (\Cartonoma\Tools\ToolRegistry $registry): void {
    $registry->register('example_sheet_count', [
        'version' => '1', 'owner' => plugin_basename(__FILE__),
        'title' => 'Calculate sheet count', 'description' => 'Calculate sheets needed from item quantity and items per sheet. This example does not create a quote.',
        'access' => 'public', 'readOnly' => true,
        'inputSchema' => ['type' => 'object', 'additionalProperties' => false, 'required' => ['quantity', 'per_sheet'], 'properties' => [
            'quantity' => ['type' => 'integer', 'minimum' => 1, 'maximum' => 100000],
            'per_sheet' => ['type' => 'integer', 'minimum' => 1, 'maximum' => 1000],
        ]],
        'outputSchema' => ['type' => 'object', 'additionalProperties' => false, 'required' => ['sheets'], 'properties' => [
            'sheets' => ['type' => 'integer', 'minimum' => 1, 'maximum' => 100000],
        ]],
        'permission_callback' => static function (): bool { return true; },
        'execute_callback' => static function (array $input): array { return ['sheets' => (int) ceil($input['quantity'] / $input['per_sheet'])]; },
    ]);
});

WordPress → Eklentiler ekranından “Cartonoma Example Tools” eklentisini etkinleştirin. Yönetim ekranındaki araç adı “Calculate sheet count” olarak görünür.

Yayımlayın ve deneyin

1. Cartonoma → Geliştirici araçları ekranını açın.
2. “Calculate sheet count” kartında girdi ve çıktı şemalarını inceleyin.
3. “Aracı yayımla” düğmesine basın. Bu işlem aracı ziyaretçilere ve yapay zekâ asistanlarına açar.
4. JSON girdisine aşağıdaki nesneyi yazıp “Aracı çalıştır” düğmesine basın.

{ "quantity": 10, "per_sheet": 3 }

{ "sheets": 4 }

Denemeyi kapatmak için “Aracı yayından kaldır” düğmesini kullanın. Eklentiyi etkisizleştirmek de aracı kullanımdan kaldırır. Araç sürümü, şeması veya sahibi değişirse yeniden yayımlamanız gerekir. Başlık ve açıklama çevirileri tek başına onayı kaldırmaz; davranış veya açıklamanın anlamı değiştiğinde araç sürümünü artırın.

JavaScript ve REST

İstekleri Cartonoma’nın kurulu olduğu WordPress sitenize gönderin. cartonoma.com üzerindeki bu sayfa dokümantasyondur; örnek uç noktayı burada çalıştırmaz.

GET /wp-json/cartonoma/v1/tools/manifest

Yönetim ekranındaki “Araç bildirimini aç” bağlantısı sitenizin doğru adresini gösterir. Düz kalıcı bağlantılarda adres /?rest_route=/cartonoma/v1/tools/manifest biçiminde olabilir. Çağrı için listedeki executeUrl değerini kullanın.

{
  "tool": "example_sheet_count",
  "input": { "quantity": 10, "per_sheet": 3 }
}

// Run on the WordPress site hosting the tool.
// Use the manifest URL shown in Cartonoma → Developer tools.
const manifestUrl = '/wp-json/cartonoma/v1/tools/manifest';
const manifestResponse = await fetch(manifestUrl, {
  credentials: 'omit', cache: 'no-store'
});
if (!manifestResponse.ok) throw new Error('Manifest unavailable');
const manifest = await manifestResponse.json();
const tool = manifest.tools.find(t => t.name === 'example_sheet_count');
if (!tool) throw new Error('Activate and publish the example tool first');
if (new URL(tool.executeUrl, location.href).origin !== location.origin) {
  throw new Error('Use a same-origin execution URL');
}
const response = await fetch(tool.executeUrl, {
  method: 'POST', credentials: 'omit', cache: 'no-store',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    tool: tool.name,
    fingerprint: tool.fingerprint,
    input: { quantity: 10, per_sheet: 3 }
  })
});
const result = await response.json();
if (!response.ok) throw new Error(result.message || 'Tool call failed');
console.log(result); // { sheets: 4 }

curl 'https://YOUR-WORDPRESS-SITE.example/wp-json/cartonoma/v1/tools/execute' \
  -H 'Content-Type: application/json' \
  --data '{"tool":"example_sheet_count","input":{"quantity":10,"per_sheet":3}}'

Manifest yalnızca kullanılabilir kayıt araçlarını listeler. Site bilgisi, içerik araması ve yayımlanan özel araçları içerir; eski WooCommerce tarayıcı araçlarının tam listesi değildir. fingerprint isteğe bağlıdır; örnekte gönderilmesi, tanımı değişen bir aracı eski bilgilerle çağırmanızı önler.

Araç tanımı

cartonoma_register_tools eylemi bir ToolRegistry nesnesi verir. register(name, definition) başarılıysa true, tanım geçersizse WP_Error döndürür. Üretim eklentinizde bu dönüş değerini kontrol edin.

Desteklenen şema kapsamı

Türler: object, array, string, integer ve boolean. Alanlar: type, properties, required, additionalProperties, items, enum, minimum, maximum, maxLength, maxItems, description ve default. Girdi ve çıktı kökü object olmalı; nesnelerde additionalProperties: false kullanın. $ref, oneOf ve format gibi diğer alanlar desteklenmez.

Girdi üst sınırı 16 KiB, çıktı üst sınırı 256 KiB’dir. Bir site en fazla 64 özel araç kaydedebilir. Yeni çağrı uç noktası araç başına, site genelinde dakikada 60 istekle sınırlıdır. Uzun süren callback işlemleri için kendi süre sınırınızı koyun; tarayıcı isteğini iptal etmek çalışan PHP işlemini zorla durdurmaz.

Sorun giderme

404 · cartonoma_tool_unavailable

Eklenti etkin mi, araç yayımlanmış mı ve WebMCP açık mı kontrol edin. permission_callback tam olarak true döndürmeli.

400 · cartonoma_tool_input_invalid

JSON nesnesini ve şemadaki zorunlu alanları kontrol edin. Yönetim ekranına yalnızca input nesnesini, REST çağrısına tool ve input alanlarını içeren gövdeyi gönderin.

409 · cartonoma_tool_changed

Manifesti yeniden alın. Gerekirse yönetim ekranında aracı tekrar yayımlayın.

429 · cartonoma_tool_busy / cartonoma_tool_rate_limited

Yanıttaki Retry-After süresini bekleyip tekrar deneyin.

500 · cartonoma_tool_failed / cartonoma_tool_output_invalid

Callback hatasını sunucuda inceleyin. Sonuç bir dizi olmalı ve outputSchema ile eşleşmeli; ziyaretçiye özel hata ayrıntıları göndermeyin.