Imperative API

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky
François Beaufort
François Beaufort
GitHub

Yayın tarihi: 18 Mayıs 2026, Son güncelleme tarihi: 1 Haziran 2026

Açıklayıcı Web Uzantılar Chrome Durumu Amaç
GitHub Geliştirici denemesi Geliştirici denemesi Görünüm Deneme Amacı (Intent to Experiment)

Standart JavaScript ile birçok araç türünü tanımlamak için WebMCP Imperative API'yi kullanabilirsiniz. Araçlarınız, form girişi, site gezinme ve durum yönetimi gibi farklı işlevleri yerine getirebilir.

Bu API'yi kullanmadan önce kullanım alanları örnekleri hakkında bilgi edinin.

Model bağlamı sağlama

Araçları kaydetmek için modelContext arayüzünü kullanın. Araç kaydı için ad, açıklama ve alakalı özelliklere sahip giriş şeması gerekir.

Model bağlamına tek bir araç eklemek için registertool simgesini kullanın.

WebMCPza Maker

document.modelContext.registerTool({
  name: 'toggle_layer',
  description: 'Control pizza layers (sauce, cheese). Use "add", "remove", or "toggle".',
  inputSchema: {
    type: 'object',
    properties: {
      layer: { type: 'string', enum: ['sauce-layer', 'cheese-layer'] },
      action: { type: 'string', enum: ['add', 'remove', 'toggle'] },
    },
    required: ['layer'],
  },
  execute: async ({ layer, action }) => {
    await toggleLayer(layer, action);
    return `Performed ${action || 'toggle'} on layer: ${layer}`;
  },
});

Sipariş durumunu alma

document.modelContext.registerTool({
  name: 'get_order_status',
  description: 'Search orders in a given timeframe. Returns order number, shipping status and location',
  inputSchema: {
    "type": "object",
    "properties": {
      "timeframe": { "type": "string", "oneOf": [
        { "type": "string", "const": "today", "title": "Today" },
        { "type": "string", "const": "yesterday", "title": "Yesterday" },
        { "type": "string", "const": "last_7_days", "title": "Last 7 Days" },
        { "type": "string", "const": "last_30_days", "title": "Last 30 Days" },
        { "type": "string", "const": "last_6_months", "title": "Last 6 Months" }],
      "enum": [ "today", "yesterday", "last_7_days", "last_30_days", "last_6_months" ],
      "description": "Timeframe for the order lookup." }
    },
    "required": [ "timeframe" ]
  },
  execute: async ({ timeframe }) => {
    // Add your API or database logic here to fetch and return the order data as a string.
  },
});

İsteğe bağlı parametre olarak iletildiğinde AbortSignal ile bir aracı kaldırabilirsiniz.

const addTodoTool = {
  name: "addTodo",
  description: "Add a new item to the to-do list",
  inputSchema: {
    type: "object",
    properties: { text: { type: "string" } },
  },
  execute: async ({ text }) => {
    // You should handle the persistence logic here (omitted for demo)
    return `Added to-do: ${text}`;
  },
  annotations: {
    readOnlyHint: false,
    untrustedContentHint: true
  },
};
const controller = new AbortController();
document.modelContext.registerTool(addTodoTool, { signal: controller.signal });

// Unregister the tool later...
controller.abort();

Araçları keşfedin

Kullanılabilir araçları görmek için document.modelContext.getTools() simgesini kullanın. Bu eşzamansız yöntem, çağıran dokümanın erişmeye yetkili olduğu araçların listesini döndürür.

const [tool] = await document.modelContext.getTools();
console.log(tool);

// {
//   annotations: { readOnlyHint: false, untrustedContentHint: true },
//   description: "Add a new item to the to-do list",
//   inputSchema: '{"type":"object","properties":{"text":{"type":"string"}}}',
//   name: "addTodo",
//   origin: "https://example.com",
//   window: Window {window: Window, self: Window, ...},
// }

Varsayılan olarak getTools(), yalnızca çağıran belge veya çerçeve ağacındaki diğer aynı kaynaklı belgeler tarafından kaydedilen aynı kaynaklı araçları döndürür. Kaynaklar arası araçları almak için kaynaklarını fromOrigins seçeneğinde açıkça listelemeniz gerekir. Bu dizi yalnızca güvenli kaynakları destekler.

Kaynaklar arası dokümanlardaki araçlar yalnızca şu durumlarda eklenir:

  1. Barındırma kaynağı, fromOrigins seçeneğinde listelenir.
  2. Araç, kaynağınıza açıkça maruz kalmıştır.
// https://example.com

// Get same-origin tools only
const sameOriginTools = await document.modelContext.getTools();

// Get same-origin tools plus tools from specific cross-origin documents
const allTools = await document.modelContext.getTools({
  fromOrigins: ['https://partner.org']
});

Aracı yürüt

getTools() içinde keşfedilen bir aracı manuel olarak yürütmek için giriş bağımsız değişkenleriyle document.modelContext.executeTool() işlevini geçerli bir JSON dizesi olarak çağırın. Bu eşzamansız yöntem, araç yürütme sonucunu veya gezinme tetiklendiğinde null değerini döndürür.

const result = await document.modelContext.executeTool(tool, '{"text": "Buy milk"}');
console.log(result);

// 'Added to-do: Buy milk'

İsteğe bağlı bir parametre olarak iletildiğinde AbortSignal ile bekleyen bir araç yürütmesini iptal edebilirsiniz.

const controller = new AbortController();
document.modelContext.executeTool(tool, '{"text": "Buy milk"}', {
  signal: controller.signal,
});

// Cancel tool execution later...
controller.abort();

Etkinlikler

Kullanılabilir araçların listesi değiştiğinde bildirim almak için çerçeveler, document.modelContext üzerinde toolchange etkinliğini dinleyebilir.

document.modelContext.addEventListener("toolchange", (event) => {
  // Tools have changed.
});

Kaynaklar arası iframe'ler

WebMCP, hem izin politikalarını hem de açık kaynak sınırlamayı kullanan kaynaklar arası iframe'leri destekler.

İzin politikası

Kaynaklar arası iframe'lerde araç kaydı varsayılan olarak devre dışıdır. Bir sayfa, tools izin politikası kullanarak erişimi temsilciye devretmelidir:

<iframe src="https://example.com" allow="tools"></iframe>

Kaynak görünürlüğü

Araçlar, varsayılan olarak kaynaklar arası dokümanlarda kullanılamaz. Bir aracı görüntülemesine ve yürütmesine izin verilen belirli kaynakları listelemek için registerTool içinde exposedTo dizisini kullanabilirsiniz. Bu dizi yalnızca güvenli kaynakları destekler.

// https://partner.org

document.modelContext.registerTool({
  name: 'my_shared_tool',
  description: 'Shared across origins',
  // ...
}, {
  exposedTo: ['https://example.com']
});

Etkileşim kurma ve geri bildirim paylaşma

WebMCP aktif olarak tartışılmaktadır ve gelecekte değişebilir. Bu API'yi denerseniz geri bildiriminizi bizimle paylaşmanızı rica ederiz.