Практические заметки: WebMCP: когда веб-сайты превращаются в инструменты ИИ

Используйте это как переработанную версию идей из статьи «WebMCP: Когда веб-сайты превращаются в инструменты ИИ», ориентированную на операторов: четкие этапы, упорядоченные блоки кода и записи о восстановлении, сохраняющиеся при передаче задачи. Этап Обзора работает наилучшим образом, если рассматривать его как измеримую основу. Соберите один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объема работ. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Дайте названия элементам, определите критерии успеха и не соглашайтесь на молчаливое частичное выполнение задачи.

Как все элементы соединяются между собой

Для этапа «Как соединяются компоненты» необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рядом с функциональными результатами следует записывать время выполнения и стоимость токена или запроса. Отображение стоимости заранее предотвращает неожиданные счета при переходе с демо-среды в общедоступные среды. Аутентификация происходит на шлюзе, а повторная авторизация — на уровне данных. Один только токен-носитель не является границей аренды.

Настройка

На этапе настройки необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Конфигурацию следует хранить отдельно от кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь кодовый граф. Аутентификация происходит на шлюзе, а повторная авторизация — на уровне обработки данных. Один только токен-носитель не является границей между тенантами.

const mc = document.modelContext;   // undefined if WebMCP is off

Как это выглядит при корректной работе

На этапе «Как это выглядит» необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Необходимо одновременно задокументировать успешный сценарий работы и сценарий восстановления. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки. Аутентификация происходит на шлюзе, а повторная авторизация — на уровне данных. Один только токен-носитель не является границей между тенантами. На этапе «Как это выглядит» необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Дайте названия результатам работы, определите критерии успеха и не допускайте безусловного частичного завершения задачи.

Форма уже является инструментом. Нужно лишь это указать.

При работе над этапом, когда форма уже готова, сначала запишите условия контракта: обязательные поля ввода, сигнал о успешном выполнении и действия при частичной неудаче. Такой список помогает сохранять честность при последующих изменениях кода. Записывайте время выполнения и стоимость токенов или запросов рядом с функциональными результатами. Отображение затрат на раннем этапе предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Фиксируйте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Без такой записи отладка циклов занимает часы.

<form id="add-form"
      toolname="add-task"
      tooldescription="Add a new task to the user's task board."
      toolautosubmit>
  <input name="title" required maxlength="80"
         toolparamdescription="Short description of the task to add.">
  <select name="priority"
          toolparamdescription="How urgent the task is.">
    <option value="low">low</option>
    <option value="normal" selected>normal</option>
    <option value="high">high</option>
  </select>
  <button type="submit">Add</button>
</form>

$('#add-form').addEventListener('submit', (e) => {
  e.preventDefault();
  const task = addTask(new FormData(e.target).get('title'), /* ... */);

  if (!e.agentInvoked) {
    e.target.reset();          // human — clear the box
  } else {
    e.respondWith?.(Promise.resolve(
      text(`Added task #${task.id}: "${task.title}".`)
    ));
  }
});

Инструменты, которые появляются и исчезают

При работе с инструментами, которые подключаются и запускаются, сначала запишите условия использования: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист помогает сохранять честность при последующих изменениях кода. Храните конфигурацию отдельно от кода приложения. Файлы с настройками окружения, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Фиксируйте название инструмента, хэш аргументов, время задержки и результат каждого вызова. Без такой записи отладка занимает часы.

await mc.registerTool({
  name: 'list-tasks',
  description: 'List the tasks on the board. Use this before acting so you know the task IDs.',
  inputSchema: {
    type: 'object',
    properties: {
      status: { type: 'string', enum: ['all', 'open', 'done'] },
    },
  },
  annotations: { readOnlyHint: true },
  async execute({ status = 'all' }) {
    const rows = visible(tasks, status);
    return text(rows.map((t) => `#${t.id} [${t.done ? 'x' : ' '}] ${t.title}`).join('\n'));
  },
});

async execute({ id }, { signal }) {
  const t = findTask(tasks, id);

  if (!t) {
    return text(`No task #${id}.`);
  }

  await sleep(3000, signal); // throws if the agent aborts

  return text(
    `Task #${t.id} is about ${
      t.priority === 'high' ? '2 hours' : '30 minutes'
    }.`
  );
}

let clearCtl = null;

async function syncClearTool() {
  const has = tasks.some((t) => t.done);

  if (has && !clearCtl) {
    const ctl = new AbortController();
    clearCtl = ctl;

    await mc.registerTool(
      {
        name: 'clear-completed',
        /* ... */
      },
      {
        signal: ctl.signal
      }
    );
  } else if (!has && clearCtl) {
    const ctl = clearCtl;
    clearCtl = null;

    setTimeout(() => ctl.abort(), 0); // abort() IS unregister
  }
}

mc.addEventListener('toolchange', refreshTools);

Что отличает это решение от сервера MCP для бэкенда

При работе над этапом «Что делает это уникальным» сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список поможет сохранять честность при последующих изменениях кода. Документируйте как успешный, так и восстановительный сценарии работы. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки. Фиксируйте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Без такой записи отладка агента занимает часы. При работе над этапом «Что делает это уникальным» сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список поможет сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия элементам, определите критерии успеха и не допускайте безответственного частичного выполнения задач.

Как подключить настоящего агента

Руководство по подключению сцены работает наилучшим образом, если рассматриваться как измеримая поверхность. Соберите один идеальный пример реализации, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Записывайте временные показатели, а также стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости на раннем этапе предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Используйте инструменты с узкими схемами и четкими метками о побочных эффектах. Хостам необходимо знать, какие вызовы изменяют состояние, прежде чем они автоматически одобрят их.

node agent.mjs list
node agent.mjs call add-task '{"title":"Ship the demo","priority":"high"}'

{
  "mcpServers": {
    "webmcp-board": {
      "command": "node",
      "args": ["C:\\projects\\web-mcp-demo\\mcp-bridge.mjs"],
      "env": { "PAGE_URL": "https://tusharkanjariya.github.io/web-mcp-demo/" }
    }
  }
}

Claude Code
    ↓
MCP
    ↓
mcp-bridge.mjs
    ↓
Chrome DevTools Protocol
    ↓
WebMCP
    ↓
my task board

Отказ

Этап отклонения работает наилучшим образом, когда его рассматривают как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Обеспечьте доступ к инструментам с узкими схемами и чёткими метками побочных эффектов. Хостам необходимо знать, какие вызовы изменяют состояние, прежде чем они автоматически одобрят их.

В чём Chrome не согласуется со спецификацией WebMCP

Сценарий, в котором Chrome дает разные результаты, лучше всего рассматривать как измеримую область. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Документируйте как успешный, так и восстановительный пути выполнения. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не этапом последующей доработки. Используйте инструменты с узкими схемами и четкими метками побочных эффектов. Администраторам необходимо знать, какие вызовы изменяют состояние, прежде чем они автоматически одобрят операцию. Сценарий, в котором Chrome дает разные результаты, лучше всего рассматривать как измеримую область. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия элементам, определите критерии успеха и не допускайте безответственного частичного завершения работы.

Kраткое замечание о выпуске продукта

Краткое замечание по этапу выполнения: определите входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Записывайте время выполнения, а также стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости заранее предотвращает неожиданные счета при переходе с демо-среды в общедоступные среды. Аутентифицируйтесь у шлюза и повторно авторизуйтесь на уровне данных. Один только токен-носитель не является границей аренды.

Вопрос, на который у вас нет четкого ответа

Для той части, которую вы реализуете, определите входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Аутентифицируйтесь у шлюза и повторно авторизуйтесь на уровне передачи данных. Один только токен не является границей между тенантами.

Что вы на самом деле порекомендуете сделать

Для того, что вы действительно собираетесь запустить в производство, определите входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Документируйте как успешный, так и восстановительный сценарии работы. Повторные попытки, проверки со стороны человека и обработка неработоспособных сообщений являются частью продукта, а не последующими улучшениями. Аутентифицируйтесь на шлюзе и повторно авторизуйтесь на уровне данных. Один только токен-носитель не является границей между тенантами. Для того, что вы действительно собираетесь запустить в производство, определите входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Дайте названия элементам, определите критерии успеха и не допускайте безответных частичных завершений.

Получить код

При работе над этапом Получение кода сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список помогает сохранять честность при последующих изменениях кода. Рядом с функциональными результатами записывайте время выполнения и стоимость токенов или запросов. Отслеживание затрат с самого начала предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Для каждого вызова фиксируйте название инструмента, хэш аргументов, время задержки и результат. Без такой записи отладка занимает часы.

Часто задаваемые вопросы

При работе над этапом FAQ сначала запишите условия работы системы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список помогает сохранять честность последующих изменений в коде.

Чек-лист операционной работы

При работе над этапом чек-листа операционной работы сначала запишите условия работы системы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список помогает сохранять честность последующих изменений в коде.

Предпочитайте небольшие, тестируемые модули вместо обширных скриптов. Если какой-то шаг не сработает, причина должна быть связана с конкретной функцией, а не с запутанной цепочкой операций.

Записывайте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Отладка без такой информации тратит часы впустую.

Фиксируйте версии зависимостей и сохраняйте хэш изображения, использованного для демонстрации. Воспроизводимость важнее устного опыта команды.

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

Записывайте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Отладка без такой информации тратит часы впустую.

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

Примечание к пакету a0176a78f428: не включайте ключи поставщиков в репозиторий, установите лимит токенов на одну сессию и храните транскрипции рядом с фиксами для оценки, чтобы последующие замены моделей оставались сопоставимыми.

Для этапа 0 примечания по усилению безопасности определите входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое шага причина должна указывать на конкретную ответственность, а не на запутанную цепочку операций.

Подробность усиления безопасности 0/771: измеряйте время выполнения, класс ошибки и расход токенов для этого примечания, затем решайте, следует ли сохранять изменения на основе фиксированного набора вопросов, а не на основе устных замечаний.

При работе над первым этапом записки по укреплению безопасности сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Рядом с функциональными результатами записывайте время выполнения, стоимость токенов или запросов. Очевидность затрат с самого начала предотвращает неожиданные расходы при переходе с демо-среды в общедоступные среды.

Подробности укрепления безопасности 1/771: измерьте время выполнения, класс ошибки и расход токенов для данной записки, затем решите, следует ли сохранять изменение на основе определенного набора критериев, а не на основе устных замечаний.

Второй этап записки по укреплению безопасности работает наилучшим образом, если рассматривать его как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Документируйте одновременно успешный сценарий работы и сценарий восстановления. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не элементами последующей доработки.

Подробности усиления безопасности 2/771: измерьте время выполнения, класс ошибки и расход токенов для этой записи, затем решите, следует ли сохранить изменения на основе фиксированного набора критериев, а не на основе единичных примеров.

На третьем этапе усиления безопасности определите входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Укажите названия элементов, определите критерии успеха и не допускайте безответственного частичного выполнения задачи.

Подробности усиления безопасности 3/771: измерьте время выполнения, класс ошибки и расход токенов для этой записи, затем решите, следует ли сохранить изменения на основе фиксированного набора критериев, а не на основе единичных примеров.

При работе над четвертым этапом инструкций по усилению безопасности сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список поможет сохранять честность при последующих изменениях кода. Храните конфигурацию отдельно от кода приложения. Файлы с настройками окружения, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код.

Подробности усиления безопасности 4/771: измеряйте время выполнения, класс ошибки и расход токенов для данной инструкции, затем принимайте решение о сохранении изменений на основе определенного набора критериев, а не на основе устных замечаний.

Четвертый этап инструкций по усилению безопасности будет работать наилучшим образом, если рассматривать его как измеримую поверхность. Соберите один эталонный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объема работ. Предпочитайте небольшие, проверяемые на примерах блоки кода вместо обширных скриптов. Когда какой-то шаг не срабатывает, причина должна указывать на конкретную ответственность, а не на запутанную цепочку операций.

Подробности усиления безопасности 5/771: измерьте время выполнения, класс ошибки и расход токенов для этой записи, затем решите, следует ли сохранить изменения на основе фиксированного набора вопросов, а не на основе единичных примеров.

На этапе 6 записи о усилении безопасности определите входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Записывайте время выполнения и стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости заранее предотвращает неожиданные счета при переходе с демо-среды в общедоступные среды.

Подробности усиления безопасности 6/771: измерьте время выполнения, класс ошибки и расход токенов для этой записи, затем решите, следует ли сохранить изменения на основе фиксированного набора вопросов, а не на основе единичных примеров.

При работе над этапом 7 записки по укреплению безопасности сначала запишите условия соглашения: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Документируйте одновременно успешный сценарий работы и сценарий восстановления. Повторные попытки, проверки со стороны человека и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки.

Деталь укрепления безопасности 7/771: измерьте время выполнения, класс ошибки и расход токенов для данной записки, затем решите, следует ли сохранять изменение, опираясь на фиксированный набор критериев, а не на устные оценки.

Этап 8 записки по укреплению безопасности работает наилучшим образом, если рассматривать его как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Рассматривайте этот этап как соглашение между входными данными и проверенными выходными результатами. Дайте названия соответствующим элементам, определите критерии успеха и не допускайте молчаливого частичного завершения работы.

Подробности усиления безопасности 8/771: измерьте время работы на стенде, класс ошибки и расход токенов для этой записи, затем решите, следует ли сохранять изменения на основе фиксированного набора вопросов, а не единичных примеров.