خادم بروتوكول سياق النموذج (MCP) للتفاعل مع Kong Konnect API، مما يسمح للمساعدين الذين يعملون بالذكاء الاصطناعي بالاستعلام عن وتحليل تكوين بوابة Kong وحركة المرور وبيانات التحليلات.

نظرة عامة على مشروع Kong MCP-Konnect

Kong MCP-Konnect هو مشروع خادم يعتمد على بروتوكول سياق النموذج (Model Context Protocol, MCP)، ويسمح لمساعدي الذكاء الاصطناعي بالاستعلام عن بيانات تكوين Kong Gateway وحركة المرور والتحليلات وتحليلها. يمكّن هذا المشروع مساعدي الذكاء الاصطناعي مثل Claude من التفاعل مع بوابة API الخاصة بـ Kong Konnect باستخدام اللغة الطبيعية.

الميزات الأساسية

• تحليل استعلامات طلبات API: يدعم تحليل طلبات API مع عوامل تصفية مخصصة
• إدارة تكوين البوابة: سرد وفحص خدمات البوابة، والمسارات، والمستهلكين، والمكونات الإضافية
• إدارة لوحة التحكم: إدارة لوحات التحكم ومجموعات لوحات التحكم
• تكامل مساعد الذكاء الاصطناعي: التكامل مع Claude ومساعدي الذكاء الاصطناعي الآخرين المتوافقين مع MCP

هيكل المشروع

src/
├── index.ts            # نقطة الدخول الرئيسية
├── api.ts             # عميل Kong API
├── tools.ts           # تعريفات الأدوات
├── parameters.ts      # مخطط Zod لمعلمات الأدوات
├── prompts.ts         # وثائق تفصيلية للأدوات
├── operations/
│   ├── analytics.ts   # عمليات تحليل طلبات API
│   ├── configuration.ts # الخدمات، والمسارات، والمستهلكين، والمكونات الإضافية
│   └── controlPlanes.ts # إدارة لوحة التحكم
└── types.ts           # تعريفات الأنواع العامة

متطلبات النظام

• Node.js 20 أو إصدار أحدث
• حساب Kong Konnect مع إمكانية الوصول إلى API
• عميل يدعم وظائف MCP (مثل Claude Desktop، Cursor، إلخ.)

التثبيت والتكوين

1. الاستنساخ والتثبيت

# استنساخ المستودع
git clone https://github.com/Kong/mcp-konnect.git
cd mcp-konnect

# تثبيت التبعيات
npm install

# بناء المشروع
npm run build

2. تكوين البيئة

قم بتعيين متغيرات البيئة التالية لتكوين خادم MCP:

# مطلوب: مفتاح API الخاص بـ Kong Konnect
export KONNECT_ACCESS_TOKEN=kpat_api_key_here

# اختياري: منطقة API المراد استخدامها (افتراضيًا US)
# القيم المحتملة: US, EU, AU, ME, IN
export KONNECT_REGION=us

الأدوات المتاحة

أدوات التحليل

1. تحليل طلبات API (analyze-api-requests)

الاستعلام عن طلبات Kong API Gateway وتحليلها، مع دعم عوامل التصفية المخصصة.

معلمات الإدخال:

• timeRange: النطاق الزمني لاسترجاع البيانات (15M, 1H, 6H, 12H, 24H, 7D)
• statusCodes: التصفية حسب رموز حالة HTTP محددة
• excludeStatusCodes: استبعاد رموز حالة HTTP محددة
• httpMethods: التصفية حسب طريقة HTTP
• consumerIds: التصفية حسب معرف المستهلك
• serviceIds: التصفية حسب معرف الخدمة
• routeIds: التصفية حسب معرف المسار
• maxResults: الحد الأقصى لعدد النتائج التي يتم إرجاعها

2. تحليل طلبات المستهلك (analyze-consumer-requests)

تحليل طلبات API الصادرة من مستهلك معين.

معلمات الإدخال:

• consumerId: معرف المستهلك المراد تحليله
• timeRange: النطاق الزمني لاسترجاع البيانات
• successOnly: عرض الطلبات الناجحة (2xx) فقط
• failureOnly: عرض الطلبات الفاشلة (غير 2xx) فقط
• maxResults: الحد الأقصى لعدد النتائج التي يتم إرجاعها

أدوات التكوين

1. سرد الخدمات (list-services)

سرد جميع الخدمات المرتبطة بلوحة التحكم.

معلمات الإدخال:

• controlPlaneId: معرف لوحة التحكم
• size: عدد الخدمات التي يتم إرجاعها
• offset: رمز إزاحة ترقيم الصفحات

2. سرد المسارات (list-routes)

سرد جميع المسارات المرتبطة بلوحة التحكم.

3. سرد المستهلكين (list-consumers)

سرد جميع المستهلكين المرتبطين بلوحة التحكم.

4. سرد المكونات الإضافية (list-plugins)

سرد جميع المكونات الإضافية المرتبطة بلوحة التحكم.

أدوات إدارة لوحة التحكم

1. سرد لوحات التحكم (list-control-planes)

سرد جميع لوحات التحكم في المؤسسة.

معلمات الإدخال:

• pageSize: عدد لوحات التحكم في كل صفحة
• pageNumber: رقم الصفحة المراد استرجاعها
• filterName: تصفية لوحات التحكم حسب الاسم
• filterClusterType: تصفية لوحات التحكم حسب نوع المجموعة
• filterCloudGateway: تصفية لوحات التحكم حسب وظيفة بوابة السحابة
• labels: تصفية لوحات التحكم حسب الملصقات
• sort: حقل واتجاه الفرز

2. الحصول على لوحة التحكم (get-control-plane)

الحصول على تفاصيل لوحة تحكم معينة.

3. سرد أعضاء مجموعة لوحة التحكم (list-control-plane-group-members)

سرد جميع أعضاء لوحة التحكم في مجموعة معينة.

4. التحقق من عضوية مجموعة لوحة التحكم (check-control-plane-group-membership)

التحقق مما إذا كانت لوحة التحكم عضوًا في أي مجموعة.

الاستخدام مع تكامل Claude

1. تثبيت Claude for Desktop

قم بتنزيل وتثبيت Claude for Desktop من موقع Claude الرسمي.

2. تكوين Claude Desktop

قم بإنشاء أو تحرير ملف تكوين Claude Desktop:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

3. إضافة التكوين

{
  "mcpServers": {
    "kong-konnect": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-konnect/build/index.js"
      ],
      "env": {
        "KONNECT_ACCESS_TOKEN": "kpat_api_key_here",
        "KONNECT_REGION": "us"
      }
    }
  }
}

4. إعادة تشغيل Claude for Desktop

بعد إعادة التشغيل، ستكون أدوات Kong Konnect متاحة للاستخدام مع Claude.

أمثلة على سير العمل

1. سرد جميع لوحات التحكم

يرجى سرد جميع لوحات التحكم في مؤسسة Kong Konnect الخاصة بي.

2. سرد الخدمات الخاصة بلوحة تحكم معينة

سرد جميع الخدمات الخاصة بلوحة التحكم [CONTROL_PLANE_NAME/ID].

3. الاستعلام عن طلبات API لخدمة معينة

أظهر لي جميع طلبات API الخاصة بالخدمة [SERVICE_NAME/ID] التي تحتوي على رموز حالة 5xx في الساعة الماضية.

4. سرد المستهلكين الخاصين بلوحة التحكم

سرد جميع المستهلكين الخاصين بلوحة التحكم [CONTROL_PLANE_NAME/ID].

5. تحليل طلبات مستهلك معين

أظهر لي جميع الطلبات الصادرة من المستهلك [CONSUMER_NAME/ID] في الـ 24 ساعة الماضية.

6. التحقق من الأخطاء أو الأنماط الشائعة

ما هي الأخطاء الأكثر شيوعًا التي يواجهها هذا المستهلك؟

دليل المطور

لإضافة أداة جديدة، اتبع الخطوات التالية:

1. حدد المعلمات في parameters.ts
2. أضف الوثائق في prompts.ts
3. قم بإنشاء منطق العملية في الملف المناسب في operations/
4. سجل الأداة في tools.ts
5. تعامل مع تنفيذ الأداة في index.ts

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

أخطاء الاتصال

• تحقق من أن مفتاح API الخاص بك صالح ولديه الأذونات اللازمة
• تحقق من أن منطقة API محددة بشكل صحيح
• تأكد من أن شبكتك يمكنها الاتصال بـ Kong Konnect API

أخطاء المصادقة

• أعد إنشاء مفتاح API الخاص بك في بوابة Kong Konnect
• تحقق من أن متغيرات البيئة قد تم تعيينها بشكل صحيح

لم يتم العثور على البيانات

• تحقق من أن المعرفات المستخدمة في الطلب صحيحة
• تحقق من أن المورد موجود في لوحة التحكم المحددة
• تأكد من أن النطاق الزمني لاستعلام التحليل صالح

ملخص

Kong MCP-Konnect هي أداة قوية تسد الفجوة بين مساعدي الذكاء الاصطناعي وإدارة Kong API Gateway. من خلال توفير واجهة لغة طبيعية للاستعلام عن بيانات تكوين بوابة API وحركة المرور والتحليلات وتحليلها، فإنها تجعل إدارة API أكثر سهولة وكفاءة. يوفر المشروع مجموعة غنية من الميزات، من استعلامات التكوين الأساسية إلى تحليل حركة المرور المتقدم، وهو أداة مهمة لإدارة البنية التحتية الحديثة لـ API.