تُرجمت هذه الصفحة من الإنجليزية بمساعدة الذكاء الاصطناعي. إذا اختلفت النسختان، فالمرجع هو النسخة الإنجليزية.
وكلاء الذكاء الاصطناعي
يمنح 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 / REPLACE | DELETE / 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 جاهزة للتشغيل للإجابة عن الأسئلة الشائعة في العمليات السحابية، مصنفة حسب الموفر.
- مرجع الذكاء الاصطناعي - مفاهيم وأدلة إرشادية ومقارنات واستكشاف الأخطاء وإصلاحها، مكتوبة للوكلاء وللأشخاص الذين يبنونها.