كيفية تحويل واجهة برمجة التطبيقات API إلى خادم MCP

هل تمنيت يومًا أن يتمكن واجهة برمجة التطبيقات (API) الخاصة بك من الدردشة مع وكلاء الذكاء الاصطناعي مثل Claude أو Cursor، وتحويل نقاط النهاية الخاصة بك إلى أدوات ذكية وتفاعلية؟ حسنًا، استعد، لأننا سنتعمق في كيفية تحويل واجهة برمجة التطبيقات (API) الخاصة بك إلى خادم MCP باستخدام Stainless ومواصفات OpenAPI. سيأخذك هذا الدليل التفاعلي عبر العملية، من الإعداد إلى النشر، مع اختبار لإثبات فعاليته. سنستخدم بروتوكول سياق النموذج (MCP) لجعل واجهة برمجة التطبيقات الخاصة بك صديقة للذكاء الاصطناعي، كل ذلك بطريقة ممتعة وسهلة. لنبدأ!

💡

هل تريد أداة رائعة لاختبار واجهة برمجة التطبيقات (API) تولد توثيقًا جميلًا لواجهة برمجة التطبيقات؟

هل تريد منصة متكاملة وشاملة لفريق المطورين الخاص بك للعمل معًا بأقصى إنتاجية؟

يلبي Apidog جميع متطلباتك، ويحل محل Postman بسعر أكثر بأسعار معقولة!

زر

ما هو خادم MCP، ولماذا يجب أن تهتم به؟

بروتوكول سياق النموذج (MCP) يشبه المصافحة العالمية لأنظمة الذكاء الاصطناعي. إنه معيار يعتمد على JSON-RPC يتيح لعملاء الذكاء الاصطناعي (مثل Claude Desktop أو Cursor أو VS Code Copilot) التفاعل مع واجهة برمجة التطبيقات الخاصة بك باستخدام اللغة الطبيعية أو المطالبات القابلة للبرمجة. يعمل خادم MCP كجسر، يترجم نقاط نهاية واجهة برمجة التطبيقات الخاصة بك إلى أدوات يمكن لوكلاء الذكاء الاصطناعي فهمها واستخدامها.

لماذا تحول واجهة برمجة التطبيقات (API) الخاصة بك إلى خادم MCP؟ إنه يغير قواعد اللعبة:

تفاعل مدعوم بالذكاء الاصطناعي: اسمح لوكلاء الذكاء الاصطناعي باستدعاء واجهة برمجة التطبيقات الخاصة بك بمطالبات بسيطة مثل "جلب بيانات المستخدم" أو "إنشاء طلب جديد".
أتمتة سهلة: يقوم Stainless بأتمتة العملية، ويولد خادم MCP من مواصفات OpenAPI الخاصة بك بأقل قدر من الترميز.
قابلية التوسع: قم بتعريض واجهة برمجة التطبيقات الخاصة بك لعدة عملاء ذكاء اصطناعي، من أدوات التطوير المحلية إلى تطبيقات جاهزة للإنتاج.
صديقة للمطورين: لا حاجة لإعادة كتابة واجهة برمجة التطبيقات الخاصة بك—ما عليك سوى إضافة طبقة MCP ودع الذكاء الاصطناعي يقوم بالعمل الشاق.

سواء كنت تقوم ببناء منصة دفع، أو واجهة برمجة تطبيقات للمحتوى، أو خدمة مخصصة، فإن تحويل واجهة برمجة التطبيقات الخاصة بك إلى خادم MCP يجعلها أكثر ذكاءً وسهولة في الوصول إليها.

كيف يتناسب Stainless مع ذلك؟

Stainless هو أفضل صديق للمطورين لإنشاء حزم SDK والآن خوادم MCP من مواصفات OpenAPI. تأخذ ميزة إنشاء خادم MCP التجريبية تعريف OpenAPI الخاص بك وتنتج حزمة فرعية من TypeScript جاهزة للعمل كـ خادم MCP. هذا يعني أن نقاط نهاية واجهة برمجة التطبيقات الخاصة بك تصبح أدوات يمكن للذكاء الاصطناعي الوصول إليها دون عناء. دعنا نرى كيف نجعل ذلك يحدث!

تحويل واجهة برمجة التطبيقات (API) الخاصة بك إلى خادم MCP باستخدام Stainless

المتطلبات الأساسية

قبل أن نتعمق، تأكد من أن لديك:

مواصفات OpenAPI: ملف OpenAPI (Swagger) صالح لواجهة برمجة التطبيقات الخاصة بك (على سبيل المثال، openapi.yaml أو openapi.json).
حساب Stainless: سجل في stainless.com لإنشاء مشروع.
حساب Apidog: لاختبار مواصفات OpenAPI الخاصة بك (قم بزيارة https://apidog.com/).
Node.js 20+: للاختبار المحلي وتشغيل خادم MCP (nodejs.org/en/download).
npm: يأتي مع Node.js لإدارة الحزم.
عميل متوافق مع MCP: Claude Desktop، Cursor، أو VS Code Copilot للاختبار.
مفتاح API: إذا كانت واجهة برمجة التطبيقات الخاصة بك تتطلب مصادقة، فجهز مفتاح API.

الخطوة 1: اختبار مواصفات OpenAPI الخاصة بك باستخدام Apidog

قبل أو حتى بعد تحويل مواصفات OpenAPI الخاصة بك إلى خادم MCP، سيكون من الرائع اختبارها. وهنا يأتي دور Apidog! تتيح لك منصة Apidog البديهية استيراد واختبار مواصفات OpenAPI الخاصة بك لضمان أن نقاط نهاية واجهة برمجة التطبيقات الخاصة بك جاهزة لتكامل MCP. إليك كيفية القيام بذلك:

قم بزيارة Apidog وسجل أو سجل الدخول:

انقر على تسجيل الدخول (أعلى اليمين) إذا كان لديك حساب، أو تسجيل لإنشاء واحد باتباع التعليمات.

زر

2. إنشاء مشروع جديد واستيراد مواصفات OpenAPI الخاصة بك:

بمجرد تسجيل الدخول، انقر على إنشاء مشروع في لوحة التحكم.
في صفحة إنشاء المشروع، انقر على استيراد.
أدخل عنوان URL لملف OpenAPI الخاص بك (على سبيل المثال، https://my-api.com/openapi.yaml) أو انقر على أو تحميل ملف لتحديد ملف openapi.yaml أو openapi.json المحلي الخاص بك.

سيقوم Apidog بتحليل الملف وإنشاء واجهة برمجة تطبيقات جديدة في حسابك (قد يستغرق هذا بضع دقائق للمواصفات المعقدة).

3. تكوين إعدادات واجهة برمجة التطبيقات:

بعد الاستيراد الناجح، ستتم توجيهك إلى صفحة الإعدادات. قم بتخصيص اسم واجهة برمجة التطبيقات الخاصة بك ووصفها ومتطلبات المصادقة (مثل مفتاح API أو OAuth).

4. إضافة نقاط نهاية واختبار:

استخدم واجهة Apidog لإضافة أو تحرير نقاط النهاية والتوثيق.
اختبر نقاط النهاية الخاصة بك مباشرة في Apidog للتحقق من أنها تعمل كما هو متوقع قبل إنشاء خادم MCP الخاص بك.

يضمن الاختبار باستخدام Apidog أن مواصفات OpenAPI الخاصة بك متينة، مما يجعل عملية إنشاء خادم MCP باستخدام Stainless أكثر سلاسة وخادم MCP الخاص بك أكثر موثوقية.

الخطوة 2: إعداد مشروع Stainless باستخدام TypeScript

إنشاء مشروع Stainless:

سجل الدخول إلى stainless.com وأنشئ مشروعًا جديدًا.
قم بتحميل مواصفات OpenAPI الخاصة بك (YAML أو JSON) لتحديد نقاط نهاية واجهة برمجة التطبيقات الخاصة بك.
اختر TypeScript كلغة مستهدفة (يتطلب إنشاء خادم MCP TypeScript، على الرغم من دعم أهداف node القديمة).

تمكين إنشاء خادم MCP:

في قسم إضافة حزم SDK بمشروعك، حدد خادم MCP لتمكين الإنشاء.
يؤدي هذا إلى إنشاء حزمة فرعية ضمن packages/mcp-server في مشروعك.

الخطوة 3: تكوين إنشاء خادم MCP

في إعدادات مشروع Stainless الخاص بك، قم بتكوين خيارات خادم MCP. أنشئ أو حرر ملف تكوين (على سبيل المثال، stainless.yaml) باستخدام:

targets:
  typescript:
    package_name: my-org-name
    production_repo: null
    publish:
      npm: false
    options:
      mcp_server:
        package_name: my-org-name-mcp
        enable_all_resources: true

package_name: اسم حزمة خادم MCP الخاص بك (يُعيّن افتراضيًا على اسم SDK الخاص بك مع -mcp).
enable_all_resources: true: يعرض جميع نقاط نهاية واجهة برمجة التطبيقات كأدوات MCP افتراضيًا.

يخبر هذا Stainless بإنشاء حزمة فرعية لـ خادم MCP تنفذ نقاط نهاية واجهة برمجة التطبيقات الخاصة بك كأدوات يمكن للذكاء الاصطناعي الوصول إليها.

الخطوة 4: تخصيص عرض نقطة النهاية وأوصاف الأداة

افتراضيًا، تصبح جميع نقاط النهاية في مواصفات OpenAPI الخاصة بك أدوات MCP. للتخصيص:

تحديد نقاط نهاية محددة:

قم بتعيين enable_all_resources: false وتمكين موارد أو طرق محددة:

resources:
  users:
    mcp: true
    methods:
      create:
        mcp: true
  orders:
    methods:
      create:
        mcp: true
        endpoint: post /v1/orders

2. ضبط دقيق لبيانات تعريف الأداة:

قم بتخصيص أسماء الأدوات وأوصافها لتفاعل أفضل مع الذكاء الاصطناعي:

resources:
  users:
    methods:
      create:
        mcp:
          tool_name: create_user
          description: Creates a new user profile with name and email.

يضمن هذا أن خادم MCP الخاص بك يعرض فقط نقاط النهاية التي تريدها، مع أوصاف واضحة وصديقة للذكاء الاصطناعي.

الخطوة 5: التعامل مع واجهات برمجة التطبيقات الكبيرة باستخدام تصفية الأدوات والأدوات الديناميكية

بالنسبة لواجهات برمجة التطبيقات التي تحتوي على العديد من نقاط النهاية (>50)، فإن عرض كل منها كأداة منفصلة يمكن أن يطغى على نافذة سياق الذكاء الاصطناعي. استخدم هذه الاستراتيجيات:

تصفية الأدوات:

قم بتصفية الأدوات في وقت التشغيل حسب المورد، أو نوع العملية (على سبيل المثال، قراءة/كتابة)، أو العلامات المخصصة:

npx -y my-org-mcp --resource=users

2. وضع الأدوات الديناميكية:

قم بتمكين الأدوات الديناميكية لعرض ثلاث أدوات تعريفية: list_api_endpoints، get_api_endpoint_schema، و invoke_api_endpoint. هذا يبسط التفاعل لواجهات برمجة التطبيقات الكبيرة:

npx -y my-org-mcp --tools=dynamic

تتيح الأدوات الديناميكية للذكاء الاصطناعي اكتشاف واستدعاء نقاط النهاية ديناميكيًا، مما يقلل من حمل السياق الزائد.

الخطوة 6: بناء ونشر خادم MCP الخاص بك

بناء خادم MCP:

يقوم Stainless بإنشاء خادم MCP في packages/mcp-server عند بناء حزمة SDK الخاصة بك.
قم بتشغيل أمر البناء في مشروع Stainless الخاص بك (تحقق من ملف README.md الخاص بمشروعك للحصول على تفاصيل).

النشر إلى npm:

قم بتكوين مستودع إنتاج في إعدادات Stainless الخاصة بك.
انشر خادم MCP كحزمة npm منفصلة (على سبيل المثال، my-org-name-mcp):

npm publish

الخطوة 7: التثبيت والتكوين لعملاء MCP

بعد النشر، قم بتثبيت حزمة خادم MCP الخاصة بك محليًا أو عن بعد للاستخدام مع عملاء الذكاء الاصطناعي. لـ Claude Desktop:

تثبيت الحزمة:

إذا كنت تختبر محليًا، فانتقل إلى packages/mcp-server واتبع التعليمات في README.md.
للاستخدام عن بعد، قم بالتثبيت عبر npm:

npm install my-org-name-mcp

2. تكوين Claude Desktop:

افتح claude_desktop_config.json (macOS: ~/Library/Application Support/Claude، Windows: %APPDATA%\Claude).

أضف:

{
  "mcpServers": {
    "my_org_api": {
      "command": "npx",
      "args": ["-y", "my-org-mcp"],
      "env": {
        "MY_API_KEY": "123e4567-e89b-12d3-a456-426614174000"
      }
    }
  }
}

استبدل my-org-mcp باسم الحزمة الخاصة بك و MY_API_KEY بمفتاح API الخاص بك.
احفظ وأعد تشغيل Claude Desktop.

3. عملاء آخرون:

لـ Cursor أو VS Code Copilot، أضف نفس التكوين إلى إعداداتهم الخاصة (على سبيل المثال، settings.json لـ VS Code أو لوحة الأدوات والتكاملات في Cursor).

الخطوة 8: اختبار خادم MCP الخاص بك

دعنا نختبر خادم MCP الخاص بك! في Claude Desktop (أو أي عميل MCP آخر)، جرب هذا الأمر:

alex@example.com

إذا كانت واجهة برمجة التطبيقات الخاصة بك تحتوي على نقطة نهاية POST /users (كما هو محدد في مواصفات OpenAPI الخاصة بك)، فسيقوم خادم MCP بترجمة هذا الأمر إلى استدعاء API، وإنشاء مستخدم وإرجاع استجابة مثل:

User created: { "name": "Alex", "email": "alex@example.com", "id": "123" }

يؤكد هذا أن خادم MCP الخاص بك يعمل وجاهز للتفاعلات المدعومة بالذكاء الاصطناعي.

نصائح استكشاف الأخطاء وإصلاحها

أخطاء البناء؟ تأكد من أن مواصفات OpenAPI الخاصة بك صالحة وأن TypeScript ممكّن في مشروع Stainless الخاص بك.
العميل لا يتصل؟ تحقق من اسم الحزمة ومفتاح API في تكوين MCP الخاص بك، وأعد تشغيل العميل.
الأمر لا يعمل؟ تحقق من تكوينات نقطة النهاية الخاصة بك وتأكد من أن الإجراء المطلوب يتطابق مع أداة مكشوفة.
حمولة السياق الزائدة؟ قم بتمكين وضع الأدوات الديناميكية أو تصفية الموارد لواجهات برمجة التطبيقات الكبيرة.

أفضل الممارسات لخوادم MCP

اجعل الأدوات مركزة: اعرض فقط نقاط النهاية التي يحتاجها الذكاء الاصطناعي الخاص بك لتجنب تضخم السياق.
أوصاف واضحة: اكتب أوصاف أدوات صديقة لـ LLM لتحسين دقة المطالبة.
استخدم الأدوات الديناميكية لواجهات برمجة التطبيقات الكبيرة: بسّط واجهات برمجة التطبيقات الكبيرة باستخدام أدوات تعريفية لتوفير مساحة السياق.
مصادقة آمنة: استخدم متغيرات البيئة أو OAuth لمفاتيح API في الإنتاج.
اختبر محليًا أولاً: استخدم التعليمات في README.md للاختبار قبل النشر إلى npm.

الخلاصة

وهذا كل شيء! لقد تعلمت للتو كيفية تحويل واجهة برمجة التطبيقات (API) الخاصة بك إلى خادم MCP باستخدام Stainless، وتحويل مواصفات OpenAPI الخاصة بك إلى قوة جاهزة للذكاء الاصطناعي. من تكوين نقاط النهاية إلى الاختبار باستخدام مطالبة إنشاء مستخدم، يجعل هذا الدليل من السهل ربط واجهة برمجة التطبيقات الخاصة بك بوكلاء الذكاء الاصطناعي مثل Claude أو Cursor. سواء كنت تعمل على تحسين مشروع صغير أو توسيع نطاق واجهة برمجة تطبيقات للإنتاج، فإن خادم MCP هو تذكرتك لتكاملات أكثر ذكاءً وتفاعلية.

هل أنت مستعد لتجربتها؟ احصل على مواصفات OpenAPI الخاصة بك، وشغل Stainless، ودع واجهة برمجة التطبيقات الخاصة بك تتألق في عالم الذكاء الاصطناعي.

💡

زر