دليل تكامل MCP

إعادة نتيجة تسجيل الدخول المصرّح

ثبّت SDK:

pnpm add mcp-auth-web

بيئات API (engineUrl هو العنوان الأساسي دون مسار):

الاختبار: https://aim-api-test.proton-system.com
الإنتاج: https://aim-api.proton-system.com

عنوان إعادة التفويض الكامل: https://xxx.com/openapi/v1/mcp/authorization/callback

يضيف SDK المسار تلقائيًا.

أعد بيانات الاعتماد بعد نجاح تسجيل الدخول:

import { createMcpAuthClient } from 'mcp-auth-web'

const mcpAuth = createMcpAuthClient({
  engineUrl: 'https://aim-api-test.proton-system.com',
})

mcpAuth.complete({
  Authorization: `Bearer ${token}`,
})

عند فشل الدخول أو إلغاء المستخدم:

mcpAuth.fail({ code, message })
mcpAuth.cancel()

بدءًا من mcp-auth-web@0.3.1، توفر getMcpAuthErrorMessage(error) رسائل افتراضية آمنة باللغة الصينية يديرها SDK. تتولى الواجهة عرضها، ويمكن استخدام رموز الأخطاء للترجمة أو التخصيص. التقط استثناءات complete() وfail() وcancel(). لا تستدعِ fail() دون شرط داخل catch الخاص بـ complete()، ولا تعرض بيانات الاعتماد أو روابط التفويض من الأخطاء الأصلية.

import { getMcpAuthErrorMessage } from 'mcp-auth-web'

try {
  mcpAuth.complete({ Authorization: `Bearer ${token}` })
} catch (error) {
  message.error(getMcpAuthErrorMessage(error))
}

engineUrl هو عنوان Engine الذي توفره المنصة. يستقبل complete مباشرة ترويسات الاعتماد التي يستخدمها MCP. يقرأ SDK الحقل exp من Bearer JWT في Authorization وينشئ expiresAt تلقائيًا، لذلك لا تحتاج إلى تمرير وقت الانتهاء.

يختار SDK تلقائيًا callback عبر HTTPS أو نافذة تفويض App الحالية. يغيّر mcp-auth-web@0.3.0 صيغة إدخال complete؛ عند الترقية، احذف غلاف headers وexpiresAt الذي كان يُمرر يدويًا. عند حذف engineUrl يستمر استخدام نافذة تفويض App الحالية.

إذا أعادت الطريقة false فلا توجد في الصفحة وسيلة متاحة لإعادة التفويض:

if (!mcpAuth.isAvailable()) {
  message.error('البيئة الحالية لا تدعم إعادة نتيجة التفويض')
}

للتحقق، ابدأ التفويض في App وأكمل الدخول. الرجوع إلى App وظهور «مفوّض» يعني نجاح التكامل. في الإنتاج يجب أن تستخدم صفحة الدخول وEngine اتصال HTTPS متاحًا للجهاز وشهادة صالحة. لا تسجل بيانات الاعتماد أو روابط التفويض.

تعليقات المخاطر العامة لـ Tool

Tool للقراءة:

annotations: {
  readOnlyHint: true
}

Tool للكتابة:

annotations: {
  destructiveHint: true
}

أنواع Tool

1. Tool للقائمة

عندما يعيد Tool مجموعة مرشحين ليختار المستخدم منها قيمة تُملأ في معامل Tool آخر، أضف الكائن التالي إلى جذر outputSchema:

outputSchema: {
  type: "object",
  properties: {...}, // اختياري
  "x-prerequisiteCandidate": {
    itemsPath: "data",
    valuePath: "id",
    labelPath: "name"
  }
}

معنى الحقول الثلاثة:

itemsPath: موضع مصفوفة المرشحين في نتيجة Tool.
valuePath: الحقل الذي يصبح القيمة النهائية من كل مرشح.
labelPath: الحقل الذي يظهر للمستخدم من كل مرشح.

على سبيل المثال، يعيد Tool:

{
  "data": [
    { "id": "1", "name": "المتجر A" },
    { "id": "2", "name": "المتجر B" }
  ]
}

عندها:

itemsPath: "data" يعني أن قائمة المرشحين هي مصفوفة data في النتيجة.
valuePath: "id" يعني أن id للعنصر المحدد يُملأ في Tool الهدف.
labelPath: "name" يعني أن بطاقة الاختيار تعرض name للعنصر.

قائمة التحقق