명령형 API

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

게시일: 2026년 5월 18일, 최종 업데이트: 2026년 6월 18일

설명하듯이 웹 확장 프로그램 Chrome 상태 의도
GitHub 오리진 트라이얼 오리진 트라이얼 View 실험 의도

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

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

모델 컨텍스트 제공

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

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

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

주문 상태 가져오기

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

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

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

도구 탐색

document.modelContext.getTools()를 사용하여 사용 가능한 도구를 가져옵니다. 이 비동기 메서드는 호출 문서가 액세스할 수 있는 도구의 알파벳순 목록을 반환합니다.

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

기본적으로 getTools()는 호출 문서 또는 프레임 트리의 다른 동일 출처 문서에 의해 등록된 동일 출처 도구만 반환합니다. 크로스 오리진 도구를 가져오려면 fromOrigins 옵션에 오리진을 명시적으로 나열해야 합니다. 이 배열은 보안 출처만 지원합니다.

크로스 오리진 문서의 도구는 다음 조건이 충족되는 경우에만 포함됩니다.

  1. 호스팅 출처는 fromOrigins 옵션에 나열됩니다.
  2. 도구가 명시적으로 출처에 노출되었습니다.
// 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']
});

iframe에서 도구를 가져와 웹 기반 채팅 인터페이스 내에서 실행하는 방법의 예는 WebMCP 페이지 에이전트 데모를 참고하세요.

도구 실행

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

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

// 'Added to-do: Buy milk'

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

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

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

이벤트

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

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

교차 출처 iframe

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

권한 정책

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

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

출처 노출

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

// https://partner.org

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

Angular 지원

Angular에는 WebMCP에 대한 실험적 지원이 있습니다. 애플리케이션이 이미 Angular로 작성된 경우 애플리케이션의 종속 항목 삽입 수명 주기에 연결된 도구를 등록하고 Signal Forms를 WebMCP 도구로 전환할 수 있습니다.

참여 및 의견 공유

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