‏webmcp-react: ابزارهای اپ ری‌اکتی رو به ایجنت‌ها بده

webmcp-react یه کتابخونهٔ اوپن‌سورس با لایسنس MIT هست که hookهای React رو برای WebMCP فراهم می‌کنه. WebMCP یه استاندارد پیشنهادی از گروه Web Machine Learning تو W3C هست که یه API به اسم document.modelContext به مرورگر اضافه می‌کنه. یعنی هر صفحه می‌تونه ابزارهای تایپ‌دار و قابل صدا زدن رو به ایجنت‌های هوش مصنوعی نشون بده. Chrome این API رو تو حالت Early Preview داره.

کار اصلی با دو تا چیزه: اپ رو داخل می‌ذاری و با useMcpTool ابزار ثبت می‌کنی. ورودی ابزار رو با Zod تعریف می‌کنی و تو handler تایپ کامل می‌گیری. اگه Zod نمی‌خوای، می‌شه مستقیم JSON Schema داد:

function SearchTool() {
  useMcpTool({
    name: "search",
    description: "Search the catalog",
    input: z.object({ query: z.string() }),
    handler: async ({ query }) => ({
      content: [{ type: "text", text: `Results for: ${query}` }],
    }),
  });
  return null;
}

بعد از این، ابزار search روی document.modelContext ثبت شده و هر ایجنت سازگار با WebMCP می‌تونه صداش کنه. چون ابزارها با mount کامپوننت ثبت می‌شن و با unmount حذف، می‌شه مثلاً ابزارهای ادمین رو فقط برای کاربر ادمین رندر کرد.

useMcpTool یه state واکنش‌گرا هم برمی‌گردونه (مثل isExecuting، lastResult و error) که باهاش می‌شه UI ساخت. هر اجرا یه AbortSignal هم می‌گیره؛ از Chrome 153 به بعد اگه ایجنت کار رو لغو کنه، این سیگنال abort می‌شه. تو مرورگرهای قدیمی‌تر یه سیگنال بی‌اثر جاش می‌ذاره که کد نشکنه. title و annotationهایی مثل readOnlyHint و untrustedContentHint هم پشتیبانی می‌شن.

اگه مرورگر WebMCP رو نداشته باشه، کتابخونه یه polyfill سبک (یعنی پیاده‌سازی جایگزین همون API) نصب می‌کنه. با Next.js و Remix هم بدون تنظیم اضافه کار می‌کنه و تو StrictMode ابزار تکراری ثبت نمی‌شه. ایجنت‌هایی مثل Codex مستقیم ابزارها رو پیدا می‌کنن، ولی Claude Code و Cursor باید از افزونهٔ WebMCP Bridge تو Chrome وصل بشن. یه دموی Wordle هم هست که ایجنت می‌تونه باهاش بازی کنه.

نکات کلیدی:

• نیازمندی‌ها: React 18 به بالا و Zod 3.25 یا Zod 4
• ابزارها با useMcpTool روی document.modelContext ثبت می‌شن
• لغو اجرا با AbortSignal از Chrome 153 به بعد واقعاً کار می‌کنه
• Claude Code و Cursor از طریق افزونهٔ WebMCP Bridge وصل می‌شن، Codex مستقیم
• outputSchema و structuredContent افزونه‌های خود کتابخونه‌ان و جزو استاندارد WebMCP نیستن