آموزش WebMCP روی فرم‌های سایت: تبدیل فرم HTML به ابزار AI Agent با دو ویژگی ساده

آموزش WebMCP برای فرم‌ها از چیزی که فکر می‌کنید ساده‌تر است: در این صفحه یاد می‌گیرید فرم‌های HTML سایتتان را به ابزار AI Agent تبدیل کنید و نتیجه را همان‌جا در مرورگر خودتان به‌صورت زنده تست کنید. WebMCP یک استاندارد پیشنهادی وب است که به سایت‌ها اجازه می‌دهد ابزارهای ساخت‌یافته را به AI Agentهای مرورگر معرفی کنند. در این آموزش یاد می‌گیرید با Declarative API و فقط با چند ویژگی HTML، یک فرم معمولی را به ابزاری تبدیل کنید که Agent بدون حدس‌زدن بتواند از آن استفاده کند. اگر هنوز با مفهوم کلی آشنا نیستید، اول مقاله‌ی WebMCP چیست؟ را بخوانید.

آموزش WebMCP: Declarative API چیست؟

WebMCP دو API برای تعریف ابزارهای سایت ارائه می‌کند:

در روش اعلانی، toolname و tooldescription هدف ابزار را مشخص می‌کنند و فیلدهای فرم پارامترهای آن می‌شوند. مرورگر این فرم را به یک ساختار JSON Schema تبدیل می‌کند که Agent می‌فهمد. جزئیات روش جاوااسکریپتی در مستندات Imperative API آمده است.

چرا فرم‌ها را ابزار کنیم؟

بدون WebMCP، Agent باید ظاهر صفحه را بخواند و حدس بزند هر فیلد برای چیست. این کار پرخطاست و هر مرحله‌اش جای تفسیر دارد. با WebMCP، خود سایت هدف عنصر را اعلام می‌کند. طبق مستندات Chrome، چند کاربرد نمونه این‌هاست:

• پشتیبانی مشتری: هدایت Agent به فرم درست و پر کردن فیلدها
• ثبت درخواست‌های ساخت‌یافته: مثلاً ابزاری مثل submit_application که اطلاعات گفت‌وگو را درست به فیلدها نگاشت می‌کند
• رابط‌های انسان‌محور: مثلاً انتخاب پیچیده‌ی تاریخ و ساعت در رزرو
• اشکال‌زدایی: ابزارهایی مثل run_diagnostics در صفحه‌ی تنظیمات توسعه‌دهنده

برای دید کلی‌تر درباره‌ی آماده‌سازی سایت برای Agentها، راهنمای آماده‌سازی سایت برای AI Agent را ببینید.

پیش‌نیازهای آموزش WebMCP و فعال‌سازی

• مرورگر Chrome با پشتیبانی WebMCP
• یک فرم HTML ساده (تماس، جستجو یا درخواست مشاوره)
• آشنایی ابتدایی با HTML

فعال‌سازی برای تست محلی

1. آدرس chrome://flags/#enable-webmcp-testing را در Chrome باز کنید.
2. گزینه را روی Enabled بگذارید.
3. مرورگر را دوباره راه‌اندازی کنید.

برای استفاده روی سایت واقعی باید در Origin Trial مربوط به WebMCP (از Chrome 149) ثبت‌نام کنید.

مرحله ۱ آموزش WebMCP: ویژگی‌های ضروری فرم

به تگ فرم دو ویژگی اضافه کنید:

<form toolname="createSupportRequest"
      tooldescription="Submits a request for customer support.">
  ...
</form>

اگر هرکدام از این دو ویژگی را حذف کنید، ابزار از حالت ثبت‌شده خارج می‌شود. وقتی Agent ابزار را صدا بزند، مرورگر فرم را فوکوس می‌کند و فیلدها را پر می‌کند؛ فرم همچنان برای کاربر دیده می‌شود.

توصیه: نام و توضیح ابزار را روشن و به انگلیسی بنویسید، چون این متن را مدل زبانی می‌خواند، نه بازدیدکننده‌ی سایت.

مرحله ۲: توضیح فیلدها با toolparamdescription

مرورگر به‌طور پیش‌فرض از متن label هر فیلد استفاده می‌کند و اگر برچسبی نباشد از aria-description. برای دقت بیشتر می‌توانید از toolparamdescription استفاده کنید:

<form toolname="supportRequestTool"
      tooldescription="Submit a request for support."
      action="/submit">

  <label for="firstName">First Name</label>
  <input type="text" name="firstName">

  <label for="lastName">Last Name</label>
  <input type="text" name="lastName">

  <select name="select" required
          toolparamdescription="Determines what team this request is routed to.">
    <option value="Customer happiness team">Return my purchase.</option>
    <option value="Distribution team">Check where my package is.</option>
    <option value="Website support team">Get help on the website.</option>
  </select>

  <button type="submit">Submit</button>
</form>

مرورگر این فرم را به یک ابزار با inputSchema تبدیل می‌کند. فیلدهای متنی به نوع string تبدیل می‌شوند، گزینه‌های select به یک enum با عنوان هر گزینه، و فیلد required در فهرست required می‌آید. (نمونه‌ی خروجی کامل در مستندات Declarative API هست.)

مرحله ۳: ارسال دستی یا خودکار

برای ارسال فرم دو انتخاب دارید:

• دستی (پیش‌فرض): کاربر خودش روی دکمه‌ی ارسال کلیک می‌کند.
• خودکار: با ویژگی toolautosubmit فرم به‌محض فراخوانی ابزار ارسال می‌شود.

<form toolautosubmit toolname="search_tool"
      tooldescription="Search the web" action="/search">
  <input type="text" name="query">
</form>

ارسال خودکار برای جستجو منطقی است؛ برای پرداخت، ثبت سفارش یا هر اقدام برگشت‌ناپذیر از آن استفاده نکنید.

مرحله ۴: تشخیص Agent و برگرداندن پاسخ

رویداد submit یک مقدار بولی به نام agentInvoked دارد که اگر فرم را AI Agent فعال کرده باشد true است. با respondWith() هم می‌توانید نتیجه را به مدل برگردانید؛ قبل از آن باید preventDefault() را صدا بزنید:

document.querySelector("form").addEventListener("submit", (e) => {
  if (e.agentInvoked) {
    e.preventDefault();
    // اینجا فرم را اعتبارسنجی و ارسال کنید
    e.respondWith(Promise.resolve("Request received."));
  }
});

برای اطلاع از فعال‌شدن یا لغو ابزار، رویدادهای زیر روی document.modelContext در دسترس‌اند:

document.modelContext.addEventListener("toolactivated", ({ toolName }) => {
  console.log(`tool "${toolName}" was activated`);
});

document.modelContext.addEventListener("toolcancel", ({ toolName }) => {
  console.log(`tool "${toolName}" was cancelled`);
});

طبق مستندات، از Chrome 156 به بعد window.ontoolactivated و window.ontoolcancel پشتیبانی نمی‌شوند؛ از document.modelContext استفاده کنید.

مرحله ۵: نشانه‌ی بصری فوکوس

هنگام فعال‌شدن ابزار توسط Agent، مرورگر دو شبه‌کلاس CSS اعمال می‌کند: :tool-form-active روی فرم و :tool-submit-active روی دکمه‌ی ارسال. اگر می‌خواهید ظاهرشان را سفارشی کنید:

form:tool-form-active {
  outline: light-dark(blue, cyan) dashed 1px;
  outline-offset: -1px;
}

نشانه‌ی فوکوس مهم است، چون کاربر و Agent باید بفهمند کدام بخش صفحه فعال است.

تست زنده آموزش WebMCP: فرم خودتان را همین‌جا ابزار کنید

به‌جای فقط خواندن، امتحان کنید. اول ببینید مرورگرتان WebMCP را پشتیبانی می‌کند، بعد نام و توضیح ابزار را بنویسید تا کد آماده و یک فرم زنده ساخته شود. این فرم نمایشی است و هیچ داده‌ای جایی ارسال نمی‌شود.

تست و اشکال‌زدایی WebMCP

1. Chrome DevTools: می‌توانید ابزارهای ثبت‌شده و نحوه‌ی تفسیر JSON Schema توسط مرورگر را بررسی کنید.
2. افزونه‌ی Model Context Tool Inspector: با زبان طبیعی ابزارها را امتحان کنید. برای مدل‌های ابری کلید API لازم است. افزونه‌ی نمونه‌ی Agent از Chrome Labs هم برای همین کار هست.
3. Lighthouse: بررسی agentic browsing فرم‌هایی را که toolname و tooldescription ندارند نشان می‌دهد. فعلاً فقط جنبه‌ی اطلاع‌رسانی دارد و هشدار نمی‌دهد.

نکات امنیتی

• اقدام‌های حساس: برای پرداخت، حذف یا ثبت قرارداد ارسال خودکار نگذارید و تأیید کاربر را نگه دارید.
• افزونه‌های مرورگر: افزونه‌ها می‌توانند ابزارهای WebMCP را با content script بخوانند و اجرا کنند؛ پس همه‌ی ورودی‌ها را سمت سرور هم اعتبارسنجی کنید.
• داده‌ی حساس: فرم‌هایی که اطلاعات محرمانه می‌گیرند را بدون ضرورت ابزار نکنید.
• iframe: ثبت ابزار به Permissions Policy با نام tools وابسته است. مقدار پیش‌فرض self است و در iframeهای cross-origin غیرفعال می‌ماند، مگر اینکه allow="tools" را روی iframe بگذارید.

راهنمای کامل‌تر را در مستندات امنیت ابزارهای WebMCP و بهترین روش‌ها بخوانید.

اشتباهات رایج

• حذف یکی از toolname یا tooldescription و تعجب از اینکه ابزار ثبت نشده است
• گذاشتن toolautosubmit روی فرم‌هایی که اثر برگشت‌ناپذیر دارند
• استفاده از window.ontoolactivated در نسخه‌های جدید Chrome
• نام‌گذاری مبهم ابزار یا فیلدها و نبودن label یا توضیح
• فراموش‌کردن اعتبارسنجی سمت سرور
• انتظار اینکه همه‌ی بازدیدکنندگان از آن بهره ببرند؛ فقط مرورگرها و Agentهایی که WebMCP را پشتیبانی می‌کنند

وردپرس و فرم‌سازها

اگر فرم را مستقیم با HTML یا در قالب/افزونه‌ی خودتان ساخته‌اید، کافی است دو ویژگی را به تگ form اضافه کنید. بسیاری از فرم‌سازها (مثل Contact Form 7 یا ویجت فرم المنتور) ممکن است اجازه‌ی افزودن ویژگی دلخواه به خود تگ form را ندهند. در این حالت می‌توانید با یک اسکریپت کوچک ویژگی‌ها را بعد از بارگذاری اضافه کنید، ولی باید حتماً با DevTools یا Inspector بررسی کنید که ابزار واقعاً ثبت شده است.

محدودیت‌ها

• WebMCP عمدتاً برای مرورگر محلی و با حضور کاربر طراحی شده، نه مرورگرهای headless.
• برای رابط‌های پیچیده ممکن است لازم باشد state و منطق صفحه را بازنویسی کنید.
• کشف‌پذیری محدود است: Agent یا مرورگر باید خودش به صفحه سر بزند تا ببیند ابزار دارد.
• استاندارد در حال بحث است و ممکن است تغییر کند.

سؤالات متداول آموزش WebMCP

WebMCP چیست و فرمش چه فرقی با فرم معمولی دارد؟

WebMCP استانداردی پیشنهادی است که ابزارهای سایت را به AI Agent معرفی می‌کند. ظاهر و رفتار فرم برای کاربر عادی همان است؛ فقط ویژگی‌های اضافه به Agent می‌گویند فرم چه کاری می‌کند.

برای ابزار کردن فرم باید جاوااسکریپت بنویسم؟

خیر. برای ابزار پایه دو ویژگی HTML کافی است. جاوااسکریپت فقط برای اعتبارسنجی، برگرداندن پاسخ به مدل و رویدادها لازم است.

WebMCP با MCP معمولی چه فرقی دارد؟

WebMCP کاملاً در سمت مرورگر روی صفحه اجرا می‌شود و برخی مفاهیم سمت سرور مثل resources را ندارد. مقایسه‌ی رسمی را در مستندات WebMCP versus MCP ببینید.

آیا WebMCP روی رتبه‌ی سایت در گوگل اثر دارد؟

گوگل چنین تأثیری را اعلام نکرده است. هدف WebMCP بهتر شدن تعامل Agentها با سایت است، نه رتبه‌بندی.

آیا در مرورگرهای غیر از Chrome کار می‌کند؟

مستندات فعلی روی Chrome و مرورگرهای مبتنی بر Chromium متمرکز است. پشتیبانی مرورگرهای دیگر را از منابع رسمی همان مرورگرها بررسی کنید.

اگر فرم من اطلاعات حساس می‌گیرد چه کنم؟

ابزار نکردنش امن‌تر است؛ در غیر این صورت ارسال خودکار نگذارید و ورودی‌ها را سمت سرور هم اعتبارسنجی کنید.

جمع‌بندی آموزش WebMCP

در این آموزش WebMCP دیدیم که با دو ویژگی toolname و tooldescription، فرم ساده‌ی شما به ابزاری تبدیل می‌شود که AI Agentها بدون حدس‌زدن می‌توانند از آن استفاده کنند. از یک فرم کم‌ریسک مثل جستجو یا تماس شروع کنید، با Inspector و DevTools تست کنید و فقط در صورت ماندگارشدن استاندارد آن را به فرم‌های دیگر گسترش دهید.

بعد از این آموزش WebMCP چه بخوانیم؟

• WebMCP چیست؟: تصویر کلی استاندارد و دلیل وجودش
• آماده‌سازی سایت برای AI Agent: چک‌لیست کامل برای سایت‌هایی که Agentها هم از آن‌ها استفاده می‌کنند

منابع و روش تهیه‌ی این آموزش

این آموزش با کمک هوش مصنوعی و بر پایه‌ی مستندات رسمی تهیه شده است. کدها از مستندات آمده‌اند؛ پیش از استفاده روی سایت واقعی، آن‌ها را در Chrome خودتان تست کنید.

• WebMCP | Chrome for Developers (آخرین به‌روزرسانی: ۷ اکتبر ۲۰۲۶)
• Declarative API | Chrome for Developers (آخرین به‌روزرسانی: ۲۵ سپتامبر ۲۰۲۶)
• Imperative API | Chrome for Developers
• Build effective tools | Chrome for Developers
• WebMCP Explainer در GitHub
• InfoQ: WebMCP وارد Origin Trial در Chrome 149 شد