Imperative API

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

Dipublikasikan: 18 Mei 2026

Penjelasan Web Ekstensi Status Chrome Intent
GitHub Uji coba developer Uji coba developer Uji coba developer Uji coba developer View Niat untuk Bereksperimen

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

Sebelum menggunakan API ini, baca 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

navigator.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: ({ layer, action }) => {
    toggleLayer(layer, action);
    return `Performed ${action || 'toggle'} on layer: ${layer}`;
  },
});

Mendapatkan status pesanan

navigator.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: ({ timeframe }) => {
    // Add your API or database logic here to fetch and return the order data as a string.
  },
});

Anda dapat menghapus alat dengan AbortSignal, saat 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: ({ 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();
navigator.modelContext.registerTool(addTodoTool, { signal: controller.signal });

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

Temukan alat

Untuk melihat alat yang tersedia, gunakan navigator.modelContext.getTools(). Metode asinkron ini menampilkan daftar alat yang diizinkan untuk diakses oleh dokumen pemanggil berdasarkan asalnya.

const [tool] = await navigator.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, ...},
// }

Jalankan alat

Untuk menjalankan alat yang ditemukan di getTools() secara manual, panggil navigator.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 navigator.modelContext.executeTool(tool, '{"text": "Buy milk"}');
console.log(result);

// 'Added to-do: Buy milk'

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

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

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

Acara

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

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

Iframe lintas origin

WebMCP mendukung iframe lintas origin yang menggunakan kebijakan izin dan pembatasan 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 asal

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

navigator.modelContext.registerTool({
  name: 'my_shared_tool',
  description: 'Shared across origins',
  // ...
}, {
  exposedTo: ['https://trusted.com', 'https://partner.org']
});

Berinteraksi dan memberikan masukan

WebMCP sedang dalam tahap pembahasan aktif dan dapat berubah sewaktu-waktu. Jika Anda mencoba API ini dan memiliki masukan, kami ingin mendengarnya.