Skill SDK Referansı (@botonom/skill-sdk)

mkdir botonom-skill-warehouse && cd botonom-skill-warehouse
npm init -y
npm install @botonom/skill-sdk

skill.js dosyasını oluşturun:

import { defineSkill, startSkill, z } from "@botonom/skill-sdk";

const skill = defineSkill({
  code: "warehouse",
  version: "1.0.0",
  defaultLocale: "tr",
  locales: {
    tr: { "location.found": "{sku} kodlu ürün {location} rafında bulunmaktadır." },
    en: { "location.found": "Item {sku} is stored at {location}." }
  },
  tools: {
    location: {
      description: "Stoktaki bir ürünün depo raf konumunu bulur.",
      input: { sku: z.string() },
      handler: async ({ sku }, ctx) => ({
        sku,
        location: "A-12-3",
        summary: ctx.t("location.found", { sku, location: "A-12-3" })
      }),
    },
  },
});

startSkill(skill, { port: 3620 });

Servisiniz artık POST /mcp, GET /manifest, POST /events, POST /test ve GET /health endpoint'lerini sunar. Botonom paneline kaydedip bir agent'a kurduğunuzda, agent sohbette warehouse__location aracını doğrudan çağırabilir.

Manifest temel sözleşmedir. GET /manifest ve POST /mcp standartlarını karşılayan her servis geçerli bir Botonom yeteneğidir; Node SDK sadece referans uygulamadır.

• Her yetenek bağımsız bir mikroservistir: tek süreç, tek port, tek Bearer token. Botonom Provider bu servise HTTP üzerinden ulaşır ve MCP (POST /mcp) konuşur.
• code yeteneğindeki bir tool action, yapay zekâ modeline code__action adıyla sunulur.
• Provider, tool handler'ınıza güvenilir bir çalışma bağlamı (ctx) iletir. Burada kimlikler daima UUID formatındadır (asla sıralı auto-increment id kullanılmaz) ve 120 saniyelik kısa ömürlü bir JWT olan X-Botonom-Turn-Token taşır.

import { botonomApi } from "@botonom/skill-sdk";
const data = await botonomApi(ctx, "skills/products/catalog_search", { q: "civata" });

HTTP sözleşmesi: GET /health, GET /manifest, Bearer korumalı POST /mcp ve POST /events endpoint'leridir.

Botonom agent'ları 40'tan fazla dil konuşur. @botonom/skill-sdk ile yetenekler destekledikleri dilleri Shopify App Store / VS Code benzeri locale yapısıyla tanımlar:

• Tanımlama: defineSkill içinde defaultLocale (ör. "tr") ve locales: { tr: {...}, en: {...} } haritası veya localesDir dosya yolu verilir.
• Dinamik Context: Tool handler'larında ctx.language normalleştirilmiş konuşma dilini taşır (X-Botonom-Language header'ı üzerinden gelir).
• Çeviri Fonksiyonu (ctx.t): Yanıtları ctx.t(key, vars?, fallback?) ile yerelleştirin. Dört katmanlı şeffaf fallback hiyerarşisi sayesinde eksik bir çeviri tool'un çökmesine asla yol açmaz.

Tool ve RBAC mantığınızı arka planda bir HTTP sunucusu ayağa kaldırmadan doğrudan test edebilirsiniz:

import { test } from "node:test";
import assert from "node:assert/strict";
import { createMockContext, executeTool } from "@botonom/skill-sdk/test";
import skill from "./skill.js";

test("location tool returns stock location", async () => {
  const result = await executeTool(skill, "location", { sku: "SKU-99" }, {
    roles: ["warehouse_viewer"],
    accountId: "acc_demo_123"
  });

  assert.equal(result.isError, undefined);
  assert.equal(result.location, "A-12-3");
});

• createMockContext(overrides): ctx.t, mock callBotonomApi ve test rol tanımlarını içeren hazır bir test context'i döner.
• executeTool(skill, toolName, input, contextOverrides): Zod şemasını doğrular, izinleri denetler ve handler'ı doğrudan çalıştırır.

Botonom çok kiracılı (multi-tenant) sıkı izolasyon ve ağ sınırları uygular:

• Zero-Trust Turn Token: Çağrılar kısa ömürlü (120s) HMAC-SHA256 token'ları (X-Botonom-Turn-Token) taşır. Platform API'si çağıran hesabın UUID'sini (skillTurn.account) sıkı bir şekilde doğrular; IDOR saldırılarını önler.
• Giden SSRF Koruması: Provider; bulut metadata adreslerine (169.254.169.254), özel RFC1918 yerel ağlarına veya URL içine gömülmüş kimlik bilgilerine yapılan tüm istekleri engeller.
• Canlıda HTTPS Zorunluluğu: Canlı ortama kaydedilen harici yetenek endpoint'leri mutlaka geçerli HTTPS üzerinden sunulmalıdır.
• Zaman Aşımı ve Payload Limitleri: MCP araç istekleri varsayılan 15 saniyede zaman aşımına uğrar; yanıt payload'u bellek güvenliği için 5MB ile sınırlandırılmıştır.

İzinler istem metninde (prompt) değil, veri katmanında ve yeteneğin kendi içinde denetlenir. Yetki kaynağı rol adı değil kabiliyettir (capability); böylece yeteneğiniz müşterinin özel rol adlarına bağımlı kalmaz.

• Her tool bir kabiliyete (code.action, ör. warehouse.location) sahiptir. Şirket yöneticisi Şirket → Roller ve Erişim sekmesinden bu kabiliyeti kendi rollerine atar.
• Çalışma zamanında kontrol paneli kullanıcının izinlerini çözümler ve yeteneğinize iletir; SDK kabiliyeti kontrol eder (deny-by-default). Yetki verilmemiş bir araç modele hiç gösterilmez.

Hali hazırda çalışan standart bir MCP sunucunuz varsa SDK kullanmanıza gerek yoktur. Botonom'a sunucu URL'inizi girin; Botonom manifesti okur, araçları kaydeder ve izinleri aynı güvenlik kurallarıyla yönetir. Mevcut bir servisi platforma dahil etmenin en hızlı yolu budur.