Imperative API

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

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

Penjelasan Web Ekstensi Status Chrome Intent
GitHub Uji coba origin Uji coba origin View Maksud 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

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, 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: 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 pemanggil.

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 yang sama asalnya yang didaftarkan oleh dokumen yang memanggil atau dokumen lain yang sama asalnya dalam hierarki frame. Untuk mengambil alat lintas asal, Anda harus mencantumkan asalnya secara eksplisit dalam opsi fromOrigins. Array ini hanya mendukung asal yang aman.

Alat dari dokumen lintas asal hanya disertakan jika:

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

Lihat demo Agen Halaman WebMCP untuk mengetahui contoh cara mengambil alat dari iframe dan menjalankannya dalam antarmuka percakapan berbasis web.

Jalankan 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, saat 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 pembatasan origin eksplisit.

Kebijakan izin

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

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

Eksposur asal

Secara default, alat tidak tersedia untuk dokumen lintas origin. 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']
});

Dukungan sudut

Angular memiliki dukungan eksperimental untuk WebMCP. Jika aplikasi Anda sudah ditulis dengan Angular, Anda dapat mendaftarkan alat yang terkait dengan siklus proses injeksi dependensi aplikasi dan mengubah Formulir Sinyal menjadi alat WebMCP.

Berinteraksi dan memberikan masukan

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