Imperative API

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

Dipublikasikan: 18 Mei 2026, Terakhir diperbarui: 1 Juni 2026

Penjelasan Web Ekstensi Status Chrome Intent
GitHub Uji coba developer Uji coba developer View Intent to Experiment

Anda dapat menggunakan WebMCP Imperative API untuk menentukan banyak jenis alat dengan JavaScript standar. Alat Anda dapat menjalankan berbagai fungsi, seperti input formulir, navigasi situs, dan pengelolaan status.

Sebelum menggunakan API ini, baca tentang contoh kasus penggunaan.

Memberikan konteks model

Gunakan antarmuka modelContext untuk mendaftarkan alat. Pendaftaran alat memerlukan nama, deskripsi, dan skema input dengan properti yang relevan,

Gunakan registertool untuk menambahkan satu alat ke konteks model.

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}`;
  },
});

Mendapatkan status pesanan

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.
  },
});

Anda dapat menghapus alat dengan AbortSignal, jika diteruskan sebagai parameter opsional.

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();

Menemukan alat

Untuk melihat alat yang tersedia, gunakan document.modelContext.getTools(). Metode asinkron ini menampilkan daftar alat yang diizinkan untuk diakses oleh dokumen panggilan.

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, ...},
// }

Secara default, getTools() hanya menampilkan alat asal yang sama yang didaftarkan oleh dokumen panggilan atau dokumen asal yang sama lainnya di pohon frame. Untuk mengambil alat lintas origin, Anda harus mencantumkan originnya secara eksplisit dalam opsi fromOrigins. Array ini hanya mendukung origin yang aman.

Alat dari dokumen lintas origin hanya disertakan jika:

  1. Origin hosting tercantum dalam opsi fromOrigins.
  2. Alat telah diekspos secara eksplisit ke origin Anda.
// 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']
});

Menjalankan alat

Untuk menjalankan alat yang ditemukan di getTools() secara manual, panggil document.modelContext.executeTool() dengan argumen input sebagai string JSON yang valid. Metode asinkron ini menampilkan hasil eksekusi alat, atau null saat navigasi dipicu.

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

// 'Added to-do: Buy milk'

Anda dapat membatalkan eksekusi alat yang tertunda dengan AbortSignal, jika diteruskan sebagai parameter opsional.

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

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

Acara

Frame dapat memproses peristiwa toolchange di document.modelContext untuk mendapatkan notifikasi saat daftar alat yang tersedia telah berubah.

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

Iframe lintas origin

WebMCP mendukung iframe lintas origin yang menggunakan kebijakan izin dan gating origin eksplisit.

Kebijakan izin

Pendaftaran alat dinonaktifkan secara default di iframe lintas origin. Halaman harus mendelegasikan akses menggunakan tools Kebijakan Izin:

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

Eksposur origin

Alat tidak tersedia untuk dokumen lintas origin secara default. Anda dapat menggunakan array exposedTo dalam registerTool untuk mencantumkan origin tertentu yang diizinkan untuk melihat dan menjalankan alat. Array ini hanya mendukung origin yang aman.

// https://partner.org

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

Berinteraksi dan berbagi masukan

WebMCP sedang dalam diskusi aktif dan dapat berubah di masa mendatang. Jika Anda mencoba API ini dan memiliki masukan, kami ingin mendengarnya.