명령형 API

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

게시일: 2026년 5월 18일

설명하듯이 웹 확장 프로그램 Chrome 상태 의도
GitHub 개발자 체험판 개발자 체험판 개발자 체험판 개발자 체험판 View 실험 의도

WebMCP 명령형 API를 사용하여 표준 JavaScript로 여러 유형의 도구를 정의할 수 있습니다. 도구는 양식 입력, 사이트 탐색, 상태 관리와 같은 다양한 함수를 실행할 수 있습니다.

이 API를 사용하기 전에 사용 사례 예시를 읽어보세요.

모델 컨텍스트 제공

modelContext 인터페이스를 사용하여 도구를 등록합니다. 도구를 등록하려면 이름, 설명, 관련 속성이 있는 입력 스키마가 필요합니다.

registertool을 사용하여 모델 컨텍스트에 단일 도구를 추가합니다.

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

주문 상태 가져오기

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

선택적 매개변수로 전달된 경우 AbortSignal을 사용하여 도구를 삭제할 수 있습니다.

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

도구 검색

사용 가능한 도구를 보려면 navigator.modelContext.getTools()를 사용하세요. 이 비동기 메서드는 호출 문서가 출처를 기반으로 액세스할 수 있는 권한이 있는 도구 목록을 반환합니다.

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

도구 실행

getTools()에서 검색된 도구를 수동으로 실행하려면 입력 인수를 유효한 JSON 문자열로 사용하여 navigator.modelContext.executeTool()을 호출합니다. 이 비동기 메서드는 도구 실행 결과를 반환하거나 탐색이 트리거될 때 null을 반환합니다.

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

// 'Added to-do: Buy milk'

선택적 매개변수로 전달된 경우 AbortSignal을 사용하여 대기 중인 도구 실행을 취소할 수 있습니다.

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

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

이벤트

프레임은 navigator.modelContext에서 toolchange 이벤트를 수신 대기하여 사용 가능한 도구 목록이 변경될 때 알림을 받을 수 있습니다.

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

교차 출처 iframe

WebMCP는 권한 정책과 명시적 출처 게이팅을 모두 사용하는 교차 출처 iframe을 지원합니다.

권한 정책

교차 출처 iframe에서는 도구 등록이 기본적으로 사용 중지되어 있습니다. 페이지는 tools 권한 정책을 사용하여 액세스 권한을 위임해야 합니다.

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

출처 노출

도구는 기본적으로 교차 출처 문서에서 사용할 수 없습니다. registerTool 내에서 exposedTo 배열을 사용하여 도구를 보고 실행할 수 있는 특정 출처를 나열할 수 있습니다. 이 배열은 HTTPS 프로토콜이 있는 출처만 지원합니다.

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

참여 및 의견 공유

WebMCP는 활발히 논의 중이며 향후 변경될 수 있습니다. 이 API를 사용해 보고 의견이 있으면 알려주세요.