WebMCP في Next.js وReact: سجّل أدوات وكلاء الذكاء الاصطناعي بالطريقة الصحيحة

إذا كان منتجك يعمل على Next.js أو React، فإن WebMCP يناسبه بسهولة: الأداة دالة صغيرة، ومسارات API لديك تقوم بالعمل الحقيقي أصلًا. يعرض هذا الدليل نمطًا نظيفًا. جديد على الموضوع؟ ابدأ بمقال ما هو WebMCP.

سجّل الأدوات في مكوّن عميل

لا يوجد document.modelContext إلا في المتصفح، لذا مكان التسجيل هو useEffect. لا تعرض شيئًا، ومرّر AbortSignal لتختفي الأدوات عندما يغادر الزائر الصفحة:

'use client';
import { useEffect } from 'react';

export default function SearchTool() {
  useEffect(() => {
    const mc = document.modelContext || navigator.modelContext;
    if (!mc?.registerTool) return undefined; // browsers without WebMCP skip this
    const controller = new AbortController();
    mc.registerTool({
      name: 'search_products',
      description: 'Search the catalog. Returns up to 5 products with price and link.',
      inputSchema: {
        type: 'object',
        properties: { query: { type: 'string' } },
        required: ['query'],
      },
      annotations: { readOnlyHint: true },
      execute: async ({ query }, { signal }) => {
        const res = await fetch('/api/search?q=' + encodeURIComponent(query), { signal });
        return JSON.stringify(await res.json());
      },
    }, { signal: controller.signal });
    return () => controller.abort();
  }, []);
  return null;
}

أضف <SearchTool /> إلى التخطيط أو الصفحة التي تناسبها الأداة. يشغّل React Strict Mode التأثيرات مرتين أثناء التطوير، ودالة التنظيف أعلاه تعالج ذلك.

أبقِ المنطق في مسار API

الأداة مجرد غلاف رقيق. أما التحقق والحدود والصلاحيات فمكانها الخادم، حيث لا يستطيع الزائر تغييرها:

// app/api/search/route.js
import { NextResponse } from 'next/server';

export async function GET(request) {
  const q = (request.nextUrl.searchParams.get('q') || '').slice(0, 80);
  if (!q) return NextResponse.json({ error: 'missing_query' }, { status: 400 });
  const items = await searchCatalog(q, { limit: 5 }); // your own function
  return NextResponse.json(items.map(({ name, price, url }) => ({ name, price, url })));
}

النماذج كأدوات

للنموذج البسيط، أضف toolname وtooldescription إلى العنصر <form>. يمرّر React هذه السمات غير المعروفة المكتوبة بأحرف صغيرة إلى الصفحة كما هي. ويعبّئ المتصفح النموذج، ويبقى الزائر افتراضيًا هو من يضغط الزر.

قواعد الأمان

• ابدأ بالقراءة فقط. البحث والتفاصيل أولًا، وميّزها بـ readOnlyHint.
• اسأل قبل التنفيذ. ميّز إجراءات السلة والحجز والنماذج بـ consequentialHint ليؤكّدها الزائر.
• تحقّق على الخادم. المتصفح ليس حدًّا أمنيًّا، لذا تحقّق من كل مدخل وكل صلاحية في الواجهة الخلفية.
• أعِد أقل قدر ممكن. أرسل فقط ما يحق للعميل رؤيته، ولا ترسل أبدًا بيانات الإدارة أو سجلات عملاء آخرين.

اختبر الأدوات

1. استخدم إصدارًا حديثًا من Chrome مع تفعيل WebMCP، عبر التجربة الأولية (origin trial) أو إعداد الاختبار.
2. استدعِ كل أداة بمدخلات صحيحة وأخرى خاطئة.
3. تأكّد من أن الزوار العاديين لا يلاحظون أي تغيير.
4. شغّل فاحص WebMCP المجاني على الصفحة نفسها التي توجد فيها أدواتك.

تريد أن ننفّذه لك؟

نضيف WebMCP إلى منتجات Next.js وReact، من التقييم المجاني للجاهزية حتى الأدوات المختبرة. اطّلع على خدمات دمج WebMCP وتطوير Next.js.