إنتقل إلى المحتوى الرئيسي
صفحة مترجمة

تُرجمت هذه الصفحة من الإنجليزية بمساعدة الذكاء الاصطناعي. إذا اختلفت النسختان، فالمرجع هو النسخة الإنجليزية.

وكلاء الذكاء الاصطناعي

يمنح StackQL وكلاء الذكاء الاصطناعي واجهة SQL نفسها التي يستخدمها الأشخاص للاستعلام عن الخدمات السحابية وخدمات SaaS وتوفيرها وتشغيلها. يكتشف الوكيل ما يعرضه الموفر، ويتحقق من صحة الاستعلام قبل تشغيله، ويقرأ الحالة الحية باستخدام SELECT ويغيرها باستخدام INSERT وUPDATE وDELETE، دون ملف حالة ودون SDK خاص بكل سحابة.

كيفية اتصال الوكلاء​

  • MCP عبر stdio لعملاء المحررات وتطبيقات سطح المكتب مثل Claude Desktop وCursor وContinue. يشغل العميل الأمر stackql mcp --mcp.server.type=stdio بنفسه. راجع خادم MCP.
  • MCP عبر HTTP للوكلاء المستقلين وعمليات الأتمتة التي تتصل بعملية stackql mcp أو stackql srv طويلة التشغيل، مع المصادقة برمز مميز من نوع bearer وTLS اختياري.
  • MCP المضمن للتطبيقات المجمعة: يعمل الخادم داخل العملية نفسها في Go وRust وSwift وKotlin و.NET وGleam. راجع MCP المضمن.
  • بروتوكول الاتصال الخاص بـ PostgreSQL عبر stackql srv لأطر عمل الوكلاء ودفاتر الملاحظات وأدوات BI التي تتعامل مع Postgres بالفعل.

البدء السريع مع Claude Desktop​

ثبّت الخادم من Anthropic Connector Directory (موصى به) أو من MCP Bundle القابل للتنزيل، أو سجّل الخادم يدويًا في الملف claude_desktop_config.json:

{
"mcpServers": {
"stackql": {
"command": "stackql",
"args": ["mcp", "--mcp.server.type=stdio", "--tls.allowInsecure"],
"env": {
"AWS_ACCESS_KEY_ID": "your-aws-access-key-id",
"AWS_SECRET_ACCESS_KEY": "your-aws-secret-access-key"
}
}
}
}

أدرج بيانات الاعتماد الخاصة بالموفرين الذين تخطط لاستخدامهم فقط. تجد الإرشادات الكاملة، بما في ذلك تنزيلات bundle واستخدام ملف بيانات الاعتماد، في استخدام StackQL مع Claude Desktop.

ما يمكن للوكيل فعله​

يعرض خادم MCP مجموعة صغيرة من الأدوات محددة الأنواع. تعيد كل أداة عرضًا منسقًا للنموذج وحمولة منظمة للعملاء البرمجيين.

  • الاكتشاف: تتنقل الأدوات list_providers وlist_services وlist_resources وlist_methods وdescribe_method في التسلسل الهرمي للموفر وتعيد الإدخالات وحقول الإخراج لكل عملية، بحيث تكون معلمات WHERE المطلوبة معروفة قبل كتابة الاستعلام.
  • التحقق من الصحة والقراءة: تحلل الأداة validate_select_query جملة SELECT وتخطط لها دون تشغيلها؛ وتنفذها الأداة run_select_query.
  • التغيير: تشغل الأداة run_mutation_query الجمل INSERT وUPDATE وREPLACE وDELETE؛ وتشغل الأداة run_lifecycle_operation عمليات دورة الحياة EXEC. تخضع الأداتان لوضع الخادم الموضح أدناه.
  • المهام الإدارية: server_info وlist_registry وpull_provider وreload_credentials.

يتوفر المرجع الكامل، مع الإدخالات وسلوك التقييد ومثال على موجه لكل أداة، في أدوات MCP.

ضوابط الحماية​

يحدد وضع الخادم عقد الأمان للجلسة بأكملها:

الوضعSELECT / بيانات التعريفINSERT / UPDATE / REPLACEDELETE / EXEC
read_onlyسماحرفضرفض
safe (افتراضي)سماحيتطلب موافقةيتطلب موافقة
delete_safeسماحسماحيتطلب موافقة
full_accessسماحسماحسماح

تستخدم حالة "يتطلب موافقة" ميزة elicitation في MCP: يعرض العميل الذي يدعمها (Claude Desktop وCursor وContinue) على المستخدم اسم الأداة وفئة الاستعلام وجملة SQL، وينتظر القرار قبل تشغيل أي شيء؛ أما العميل الذي لا يعلن عن دعمها فيُرفض طلبه. يتم تسجيل كل استدعاء أداة في سجل التدقيق، ويتطلب كل مستمع HTTP رمزًا مميزًا من نوع bearer، ويتم تحميل بيانات الاعتماد من البيئة أو من ملف dotenv دون إعادة أي قيم سرية إلى العميل مطلقًا. التفاصيل في أوضاع الخادم ومصادقة عملاء HTTP وسجل التدقيق.

الخطوات التالية​

  • خادم MCP - أوضاع النشر والتكوين وأوضاع الخادم وسجل التدقيق والعلامات.
  • أدوات MCP - المرجع الكامل للأدوات مع الإدخالات والتقييد وأمثلة على الموجهات.
  • MCP المضمن - شغّل الخادم داخل تطبيقك المكتوب بلغة Go أو Rust أو Swift أو Kotlin أو .NET أو Gleam.
  • Query Library - استعلامات SQL جاهزة للتشغيل للإجابة عن الأسئلة الشائعة في العمليات السحابية، مصنفة حسب الموفر.
  • مرجع الذكاء الاصطناعي - مفاهيم وأدلة إرشادية ومقارنات واستكشاف الأخطاء وإصلاحها، مكتوبة للوكلاء وللأشخاص الذين يبنونها.