For AI agents: the complete documentation index is available at /rspress-russian/llms.txt, the full documentation bundle is available at /rspress-russian/llms-full.txt, and this page is available as Markdown at /rspress-russian/ui/hooks/use-web-mcp.md.
close

useWebMcp

useWebMcp регистрирует инструмент через экспериментальный WebMCP API браузера и удаляет его при размонтировании компонента. Импортируйте его из @rspress/core/runtime:

import { usePage, useWebMcp } from '@rspress/core/runtime';

export function PageTitleTool() {
  const { page } = usePage();

  useWebMcp({
    name: 'my_site_page_title',
    description: 'Get the current page title',
    annotations: { readOnlyHint: true },
    execute: () => ({ title: page.title }),
  });

  return null;
}

Размещайте компонент там, где эта возможность уместна. Инструменты уровня сайта держите в постоянном компоненте; инструменты для конкретной страницы монтируйте вместе с этой страницей. Имена инструментов должны быть уникальными в пределах документа, включая встроенные инструменты.

Собственные инструменты работают независимо от опции конфигурации webMcp. Требования к браузерам описаны в руководстве по WebMCP.

Опции

ОпцияОписание
nameОбязательное уникальное имя инструмента.
descriptionОбязательное описание для агентов.
titleНеобязательный отображаемый заголовок.
inputSchemaJSON Schema, описывающая входные данные.
execute(input, options)Обязательная функция, возвращающая сериализуемое в JSON значение или промис. options.signal, если передан, несёт отмену от вызывающей стороны.
enabledРегистрировать ли инструмент. По умолчанию true; значение false отменяет регистрацию инструмента.
annotationsНеобязательные логические подсказки: readOnlyHint, untrustedContentHint, consequentialHint и debugging.
exposedToНеобязательный массив дополнительных безопасных источников, которым разрешено обнаруживать инструмент.

Используйте WebMcpOptions<TInput, TResult> или аннотации параметров для типов, а также проверяйте входные данные и обрабатывайте отмену в execute.

useWebMcp({
  name: 'my_site_lookup',
  description: 'Look up a documentation entry',
  inputSchema: {
    type: 'object',
    properties: { query: { type: 'string' } },
    required: ['query'],
    additionalProperties: false,
  },
  async execute(input: { query: string }, { signal }) {
    if (typeof input?.query !== 'string' || !input.query.trim()) {
      throw new TypeError('query must be a non-empty string');
    }
    const response = await fetch(
      `/api/lookup?q=${encodeURIComponent(input.query)}`,
      { signal },
    );
    if (!response.ok) throw new Error(`Lookup failed: ${response.status}`);
    return response.json();
  },
});

Возвращаемое значение и жизненный цикл

Возвращает WebMcpState:

  • supported: поддерживает ли браузер WebMCP.
  • registered: успешно ли прошла регистрация.
  • error: ошибка регистрации или null при успехе.

Вызовы инструмента используют последние зафиксированные props и состояние. Обновление обработчика не перерегистрирует инструмент. Отключение или размонтирование компонента отменяет его регистрацию.