مكتبة React خفيفة الوزن لتوصيل خادم بروتوكول سياق النموذج (MCP)

مشروع use-mcp: نظرة مفصلة

نظرة عامة على المشروع

use-mcp هي مكتبة خطافات React خفيفة الوزن، مصممة خصيصًا للاتصال بخادم Model Context Protocol (MCP). يبسط هذا المشروع عملية المصادقة واستدعاء الأدوات لمعيار MCP في أنظمة الذكاء الاصطناعي، مما يوفر للمطورين حل تكامل أمامي سهل الاستخدام.

ميزات المشروع

🔄 إدارة الاتصال التلقائي

• يدعم إعادة الاتصال التلقائي وآليات إعادة المحاولة
• معالجة ذكية لحالات الاتصال والاستثناءات

🔐 سير عمل مصادقة OAuth

• معالجة كاملة لسير عمل مصادقة OAuth
• يدعم طرق المصادقة المنبثقة والرجوع
• معالجة تلقائية لتخزين رموز المصادقة

📦 واجهة React Hook موجزة

• يوفر واجهة برمجة تطبيقات React Hook بديهية
• أتمتة إدارة الحالة
• سهولة التكامل في تطبيقات React الحالية

🧰 دعم TypeScript

• تعريفات أنواع TypeScript كاملة
• تلميحات ذكية وفحص الأنواع في المحرر
• تحسين كفاءة التطوير وجودة الكود

📝 تسجيل شامل

• وظيفة تسجيل تصحيح الأخطاء التفصيلية
• تسهيل استكشاف المشكلات وتصحيح الأخطاء

🌐 دعم بروتوكولات نقل متعددة

• يدعم نقل HTTP
• يدعم نقل SSE (Server-Sent Events)

طريقة التثبيت

npm install use-mcp
# أو
pnpm add use-mcp
# أو
yarn add use-mcp

طريقة الاستخدام الأساسية

استخدام Hook الرئيسي

import { useMcp } from 'use-mcp/react'

function MyAIComponent() {
  const {
    state,        // حالة الاتصال: 'discovering' | 'authenticating' | 'connecting' | 'loading' | 'ready' | 'failed'
    tools,        // الأدوات المتاحة التي يوفرها خادم MCP
    error,        // معلومات الخطأ عند فشل الاتصال
    callTool,     // دالة لاستدعاء أدوات خادم MCP
    retry,        // إعادة محاولة الاتصال يدويًا
    authenticate, // تشغيل المصادقة يدويًا
    clearStorage, // مسح الرموز وبيانات الاعتماد المخزنة
  } = useMcp({
    url: 'https://your-mcp-server.com',
    clientName: 'My App',
    autoReconnect: true,
  })

  // معالجة حالات الاتصال المختلفة
  if (state === 'failed') {
    return (
      <div>
        <p>فشل الاتصال: {error}</p>
        <button onClick={retry}>إعادة المحاولة</button>
        <button onClick={authenticate}>مصادقة يدوية</button>
      </div>
    )
  }

  if (state !== 'ready') {
    return <div>جارٍ الاتصال بخدمة الذكاء الاصطناعي...</div>
  }

  // استخدام الأدوات المتاحة
  const handleSearch = async () => {
    try {
      const result = await callTool('search', { query: 'example search' })
      console.log('نتائج البحث:', result)
    } catch (err) {
      console.error('فشل استدعاء الأداة:', err)
    }
  }

  return (
    <div>
      <h2>عدد الأدوات المتاحة: {tools.length}</h2>
      <ul>
        {tools.map(tool => (
          <li key={tool.name}>{tool.name}</li>
        ))}
      </ul>
      <button onClick={handleSearch}>بحث</button>
    </div>
  )
}

إعداد معاودة الاتصال لمصادقة OAuth

لمعالجة سير عمل مصادقة OAuth، يجب عليك إعداد نقطة نهاية معاودة الاتصال في التطبيق.

تكوين React Router

// App.tsx مع React Router
import { BrowserRouter as Router, Routes, Route } from 'react-router-dom'
import { useEffect } from 'react'
import { onMcpAuthorization } from 'use-mcp'

function OAuthCallback() {
  useEffect(() => {
    onMcpAuthorization()
  }, [])

  return (
    <div>
      <h1>جارٍ المصادقة...</h1>
      <p>يجب أن تغلق هذه النافذة تلقائيًا.</p>
    </div>
  )
}

function App() {
  return (
    <Router>
      <Routes>
        <Route path="/oauth/callback" element={<OAuthCallback />} />
        <Route path="/" element={<YourMainComponent />} />
      </Routes>
    </Router>
  )
}

تكوين Next.js

// pages/oauth/callback.tsx
import { useEffect } from 'react'
import { onMcpAuthorization } from 'use-mcp'

export default function OAuthCallbackPage() {
  useEffect(() => {
    onMcpAuthorization()
  }, [])

  return (
    <div>
      <h1>جارٍ المصادقة...</h1>
      <p>يجب أن تغلق هذه النافذة تلقائيًا.</p>
    </div>
  )
}

مرجع API

useMcp Hook

function useMcp(options: UseMcpOptions): UseMcpResult

خيارات التكوين (UseMcpOptions)

الخيار	النوع	الوصف
url	string	مطلوب. عنوان URL لخادم MCP
clientName	string	اسم العميل عند تسجيل OAuth
clientUri	string	URI العميل عند تسجيل OAuth
callbackUrl	string	عنوان URL لمعاودة الاتصال المخصص لإعادة توجيه OAuth (افتراضيًا /oauth/callback للنطاق الحالي)
storageKeyPrefix	string	بادئة مفتاح التخزين لبيانات OAuth في localStorage (افتراضيًا "mcp:auth")
clientConfig	object	تكوين مخصص لهوية عميل MCP
debug	boolean	ما إذا كان سيتم تمكين تسجيل تصحيح الأخطاء التفصيلي
autoRetry	boolean | number	إعادة المحاولة التلقائية عند فشل الاتصال الأولي، يمكن تعيين عدد المللي ثانية للتأخير
autoReconnect	boolean | number	إعادة الاتصال التلقائي عند فقدان الاتصال الذي تم إنشاؤه، يمكن تعيين عدد المللي ثانية للتأخير (افتراضي: 3000)

القيمة المرجعة (UseMcpResult)

الخاصية	النوع	الوصف
state	string	حالة الاتصال الحالية: 'discovering', 'authenticating', 'connecting', 'loading', 'ready', 'failed'
tools	Tool[]	الأدوات المتاحة التي يوفرها خادم MCP
error	string | undefined	معلومات الخطأ عند فشل الاتصال
authUrl	string | undefined	عنوان URL للمصادقة اليدوية عند حظر النافذة المنبثقة
log	LogEntry[]	مصفوفة رسائل السجل
callTool	(name: string, args?: Record<string, unknown>) => Promise<any>	دالة لاستدعاء أدوات خادم MCP
retry	() => void	محاولة إعادة الاتصال يدويًا
disconnect	() => void	قطع الاتصال بخادم MCP
authenticate	() => void	تشغيل المصادقة يدويًا
clearStorage	() => void	مسح جميع بيانات المصادقة المخزنة

أمثلة على التطبيقات العملية

عرض توضيحي عبر الإنترنت

• MCP Inspector - أداة فحص MCP
• Cloudflare Workers AI Playground - ملعب Cloudflare Workers AI

ملخص

يوفر use-mcp حلاً قويًا وموجزًا لمطوري React لدمج خوادم Model Context Protocol. من خلال واجهة Hook البديهية، ومعالجة سير عمل المصادقة الكاملة، ووظائف إدارة الاتصال القوية، يمكن للمطورين بسهولة تنفيذ تكامل أدوات الذكاء الاصطناعي في تطبيقات React، مما يقلل بشكل كبير من حاجز استخدام معيار MCP.