‏useWebMCP؛ ابزارهای ایجنت به‌سبک ری‌اکت

تو مخزن GoogleChromeLabs پکیجی به اسم use-webmcp-tool منتشر شده که خود تیم کروم نگهش می‌داره و قراره با تغییرات اسپک به‌روز بمونه. ایدهٔ WebMCP اینه که به‌جای اینکه ایجنت هوش مصنوعی مجبور باشه DOM یا درخت دسترسی‌پذیری رو اسکرپ کنه یا از اسکرین‌شات بخونه، خودِ نویسندهٔ سایت مشخص کنه چه قابلیت‌هایی در دسترسه و ایجنت همون‌ها رو صدا بزنه.

شکل خام این API روی document.modelContext سواره: با registerTool یه تول با نام، توضیح و inputSchema ثبت می‌کنی و برای لغو ثبتش یه AbortSignal پاس می‌دی. هوک همین کار دستی رو به مدلی اعلانی تبدیل می‌کنه که چرخهٔ عمرش رو خود ری‌اکت مدیریت می‌کنه — همون چیزی که توسعه‌دهنده‌های ری‌اکت باهاش راحتن:

const { supported, registered } = useWebMCP({
  name: "add-todo",
  description: "Add a new item to the user's active todo list",
  inputSchema: { type: "object", properties: { text: { type: "string" } }, required: ["text"] },
  async execute({ text }) {
    addTodo(text);
    return `Added todo item: "${text}" successfully.`;
  },
});

تول موقع مانت‌شدن کامپوننت ثبت می‌شه و موقع آنمانت خودکار لغو می‌شه؛ هدفش اینه که مجموعهٔ ابزارهایی که ایجنت می‌بینه دقیقاً با چیزی که رو صفحه‌ست هماهنگ بمونه. خروجی هوک سه‌تا مقداره: supported که می‌گه document.modelContext تو این محیط هست یا نه، registered برای وضعیت فعلی ثبت، و error برای خطاهایی مثل NotAllowedError که از permissions policy میاد.

خروجی execute هم نرمال‌سازی می‌شه: رشته به یه بلوک متنی تبدیل می‌شه، نبودِ مقدار یعنی موفقیت بدون payload، و هر چیزی که پرتاب بشه — حتی وقتی از جنس Error نیست — با پرچم isError برمی‌گرده تا شکست هیچ‌وقت برای ایجنت شبیه موفقیت به‌نظر نرسه. آپشن‌های enabled، formatOutput و onError هم برای کنترل بیشتر گذاشته شدن.

پکیج به‌شکل ESM منتشر شده، تایپ‌های TypeScript رو همراه داره، وابستگی runtime نداره و ری‌اکت ۱۸ به بالا رو به‌عنوان peer dependency می‌خواد. ۲۱ تست با vitest و jsdom نوشته شده که چرخهٔ ثبت (مانت/آنمانت، StrictMode، تزریق دیرهنگام و خطای ثبت) و کل ماتریس نرمال‌سازی خروجی و خطا رو پوشش می‌ده. چون اسپک هنوز آزمایشیه، هوک قابلیت رو feature-detect می‌کنه و هر جا نباشه به no-op تبدیل می‌شه.

نکات کلیدی:

• use-webmcp-tool یه هوک ری‌اکته که تیم کروم نگهداریش می‌کنه
• WebMCP به سایت اجازه می‌ده تابع‌هاش رو به‌عنوان تول به ایجنت معرفی کنه، به‌جای اسکرپ DOM
• ثبت و لغو ثبت تول به مانت و آنمانت کامپوننت گره خورده
• خروجی هوک: supported، registered و error
• خطاها همیشه با isError برمی‌گردن تا شکست شبیه موفقیت نباشه
• ESM با تایپ TypeScript، بدون وابستگی runtime، نیازمند ری‌اکت ۱۸+
• اسپک آزمایشیه و هوک هرجا API نباشه به no-op تبدیل می‌شه