Imperative API

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

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

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

await 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

await 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();
await document.modelContext.registerTool(addTodoTool, { signal: controller.signal });

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

Menemukan alat

Gunakan document.modelContext.getTools() untuk mengambil alat yang tersedia. Metode asinkron ini menampilkan daftar alat yang diurutkan menurut abjad yang dapat 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 yang sama asalnya yang didaftarkan oleh dokumen panggilan atau dokumen lain yang sama asalnya di hierarki frame. Untuk mengambil alat lintas origin, Anda harus mencantumkan originnya secara eksplisit dalam opsi fromOrigins. Array ini hanya mendukung asal yang aman.

Alat dari dokumen lintas origin 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 chat 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 server 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 asal yang aman.

// https://partner.org

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

Dukungan React

React memiliki dukungan eksperimental untuk WebMCP menggunakan paket usewebmcp. Jika aplikasi Anda sudah ditulis dengan React, Anda dapat mendaftarkan alat menggunakan hook mandiri yang terkait dengan siklus proses pemasangan dan pelepasan komponen. Hook useWebMCP juga menyediakan inferensi jenis yang didorong skema dan mengekspos status eksekusi lokal.

Dukungan Angular

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.