تُرجمت هذه الصفحة من الإنجليزية بمساعدة الذكاء الاصطناعي. إذا اختلفت النسختان، فالمرجع هو النسخة الإنجليزية.
استخدام StackQL مع Claude Desktop
يتكامل StackQL مع Claude Desktop عبر Model Context Protocol (MCP)، مما يتيح لك الاستعلام عن الموارد السحابية وتوفيرها لدى عدة مزودي خدمات سحابية باستخدام اللغة الطبيعية. يتيح لك هذا المزيج القوي التفاعل مع البنية التحتية السحابية الخاصة بك من خلال المحادثة، مع الاستفادة من واجهة StackQL القائمة على SQL في الخلفية.
تتوفر ثلاثة خيارات للتثبيت، مرتبة هنا حسب الترتيب الموصى به: التثبيت من Anthropic Connector Directory، أو التثبيت من ملف bundle تم تنزيله، أو تسجيل ملف StackQL الثنائي المثبت محليًا يدويًا.
التثبيت من Connector Directory (موصى به)
أسهل خيار لاستخدام خادم StackQL MCP مع Claude Desktop هو تثبيته من Anthropic Connector Directory. في Claude Desktop: Settings -> Connectors -> Add -> Browse Connectors، وابحث عن StackQL، ثم انقر على Install. لا يوجد ما تحتاج إلى تنزيله، ولا يلزم تثبيت StackQL بشكل منفصل.

يمكنك أيضًا عرض الإدراج مباشرة على claude.ai/directory.
يؤدي ذلك إلى تثبيت خادم StackQL MCP داخل العملية لمنصتك: يحتوي الإدراج على ملف bundle مجمع متعدد المنصات يضم ملفات ثنائية موقعة رقميًا لـ macOS universal وWindows x64 وLinux x64 وarm64، ويختار Claude Desktop الملف المناسب لجهازك تلقائيًا. بالنسبة إلى Windows ARM64 الأصلي، ثبّت ملف bundle المنفصل windows-arm64 من التنزيلات أدناه. الملفات الثنائية لـ Windows موقعة رقميًا باستخدام Authenticode، والملف الثنائي لـ macOS موثق من Apple - وهي الملفات الثنائية نفسها الموجودة في إصدار StackQL المستقل.

يرث الموصل المثبت من Connector Directory بيئة Claude Desktop، لذا عيّن متغيرات البيئة الخاصة بموفريك على مستوى نظام التشغيل قبل تشغيل Claude Desktop - راجع بيانات الاعتماد الخاصة بكل موفر. يلتقط Claude Desktop بيئته عند بدء التشغيل: بعد تغيير المتغيرات، يجب عليك إنهاء Claude Desktop بالكامل (بما في ذلك أيقونة علبة النظام على Windows) ثم إعادة تشغيله. إن طلب تشغيل reload_credentials من الوكيل يعرض حالة بيانات الاعتماد لكل موفر، وهو أسرع وسيلة للتأكد مما يمكن للخادم رؤيته وما لا يمكنه رؤيته.
يعلن Claude Desktop عن قدرة elicitation في MCP، لذا سيطلب منك وضع الخادم الافتراضي (safe) الموافقة على كل عملية تعديل للبيانات - راجع أوضاع الخادم.
التثبيت من ملف bundle تم تنزيله
استخدم خيار التثبيت هذا لقفل إصدار محدد، أو للتثبيت دون الوصول إلى Connector Directory، أو للتحقق من المجاميع الاختبارية بنفسك قبل التثبيت.
ملف MCP Bundle (.mcpb) المبني مسبقًا هو حزمة قابلة للتثبيت بنقرة واحدة، تحتوي على الملف الثنائي stackql الموقع رقميًا وتكوين الخادم. لا يلزم تثبيت StackQL بشكل منفصل.
نزّل ملف bundle الخاص بمنصتك من أحدث إصدار:
| المنصة | ملف bundle |
|---|---|
| macOS (universal) | stackql-mcp-darwin-universal.mcpb |
| Windows AMD64 (x64) | stackql-mcp-windows-x64.mcpb |
| Windows ARM64 (أصلي) | stackql-mcp-windows-arm64.mcpb |
| Linux x64 | stackql-mcp-linux-x64.mcpb |
| Linux arm64 | stackql-mcp-linux-arm64.mcpb |
ثم في Claude Desktop: Settings -> Extensions -> Install Extension، واختر الملف الذي تم تنزيله. الملف الثنائي المضمن موقع رقميًا باستخدام Authenticode (Windows) وموثق من Apple (macOS)؛ ولكل ملف bundle مجموع اختباري .sha256 بجانبه في صفحة الإصدار. للتحقق قبل التثبيت:
# macOS / Linux
shasum -a 256 -c stackql-mcp-darwin-universal.mcpb.sha256
الخادم مدرج أيضًا في سجل MCP الرسمي باسم io.github.stackql/stackql-mcp، وهو يقفل هذه المجاميع الاختبارية.
التكوين اليدوي
إذا سبق لك تثبيت StackQL، فيمكنك تسجيل خادم StackQL MCP مباشرة في ملف تكوين Claude Desktop.
المتطلبات الأساسية
قبل إعداد StackQL مع Claude Desktop، تأكد من توفر ما يلي لديك:
- StackQL مثبت - نزّل StackQL وثبّته من stackql.io أو استخدم مدير حزم
- Claude Desktop - نزّله من موقع Anthropic على الويب
- بيانات اعتماد مزودي الخدمات السحابية - مفاتيح API أو بيانات الاعتماد الخاصة بمزودي الخدمات السحابية الذين تريد العمل معهم
تحقق من وجود StackQL في متغير PATH الخاص بنظامك من خلال تشغيل ما يلي:
stackql --version
إعداد خادم MCP
لكي يتمكن Claude Desktop من الاتصال بـ StackQL، تحتاج إلى تكوين خادم MCP في ملف تكوين Claude Desktop الخاص بك.
Windows
حرّر ملف التكوين الموجود في:
%APPDATA%\Claude\claude_desktop_config.json
macOS
حرّر ملف التكوين الموجود في:
~/Library/Application Support/Claude/claude_desktop_config.json
Linux
حرّر ملف التكوين الموجود في:
~/.config/Claude/claude_desktop_config.json
مثال على التكوين
أضف التكوين التالي إلى الملف claude_desktop_config.json الخاص بك:
{
"mcpServers": {
"stackql": {
"command": "stackql",
"args": [
"mcp",
"--mcp.server.type=stdio",
"--tls.allowInsecure"
],
"env": {
"GOOGLE_CREDENTIALS": "/path/to/google-credentials.json",
"AWS_ACCESS_KEY_ID": "your-aws-access-key-id",
"AWS_SECRET_ACCESS_KEY": "your-aws-secret-access-key",
"AZURE_CLIENT_ID": "your-azure-client-id",
"AZURE_CLIENT_SECRET": "your-azure-client-secret",
"AZURE_TENANT_ID": "your-azure-tenant-id",
"DATABRICKS_CLIENT_ID": "your-databricks-client-id",
"DATABRICKS_CLIENT_SECRET": "your-databricks-client-secret",
"OPENAI_API_KEY": "your-openai-api-key"
}
}
}
}
تحتاج فقط إلى تضمين متغيرات البيئة الخاصة بمزودي الخدمات السحابية الذين تخطط لاستخدامهم. أزل من التكوين أي بيانات اعتماد لموفرين لا تستخدمهم.
لا تودع أبدًا الملف claude_desktop_config.json الذي يحتوي على بيانات اعتماد فعلية في نظام التحكم في الإصدارات. استخدم ممارسات آمنة لإدارة بيانات الاعتماد.
يعلن Claude Desktop عن قدرة elicitation في MCP، لذا سيطلب منك وضع الخادم الافتراضي (safe) الموافقة على كل عملية تعديل للبيانات. بدّل إلى mode: read_only للحصول على وصول يقتصر على الجرد، أو إلى mode: full_access لتخطي طلبات الموافقة - راجع أوضاع الخادم.
استخدام ملف بيانات اعتماد (--env.file)
البديل عن الكتلة env - وهو البديل الموصى به على Windows - هو الاحتفاظ ببيانات الاعتماد في ملف بنمط dotenv وتمريره باستخدام العلامة --env.file:
{
"mcpServers": {
"stackql": {
"command": "stackql",
"args": [
"mcp",
"--mcp.server.type=stdio",
"--tls.allowInsecure",
"--env.file=C:\\Users\\me\\stackql-credentials.env"
]
}
}
}
مع ملف بيانات اعتماد بسيط:
# stackql-credentials.env
GOOGLE_CREDENTIALS=/path/to/google-credentials.json
AWS_ACCESS_KEY_ID=your-aws-access-key-id
AWS_SECRET_ACCESS_KEY=your-aws-secret-access-key
لماذا هذا الخيار أفضل من الكتلة env:
- تتطلب التغييرات على الكتلة
envإعادة تشغيل Claude Desktop بالكامل (بما في ذلك إنهاؤه من أيقونة علبة النظام) قبل أن تراها عملية MCP الفرعية، وعلى Windows يكتب الأمرsetxفي سجل Windows - ولا يصل أبدًا إلى عملية Desktop قيد التشغيل. - يمكن إنشاء ملف
--env.fileأو تدويره في أي وقت - بل لا يلزم وجوده عند بدء تشغيل الخادم - ويؤدي طلب تشغيلreload_credentialsمن الوكيل إلى التقاط التغييرات دون أي إعادة تشغيل.
العلامة --env.file والأداة reload_credentials متاحتان في إصدارات StackQL بعد v0.10.542.
بيانات الاعتماد الخاصة بكل موفر
يتطلب مزودو الخدمات السحابية المختلفون أساليب مصادقة مختلفة، راجع وثائق الموفرين (https://stackql.io/providers) لمعرفة متغيرات البيئة المطلوبة للموفر أو الموفرين الذين تريدهم.
إعادة تشغيل Claude Desktop
بعد تحديث ملف التكوين، أعد تشغيل Claude Desktop ليقرأ تكوين خادم MCP الجديد. سيبدأ تشغيل خادم StackQL MCP تلقائيًا عندما تبدأ محادثة جديدة.
ما يمكنك فعله
بعد التكوين، يمكنك استخدام اللغة الطبيعية في Claude Desktop من أجل:
الاستعلام عن الموارد السحابية
اطلب من Claude استرداد معلومات حول البنية التحتية السحابية الخاصة بك:
- "اعرض لي جميع مثيلات الحوسبة الخاصة بي في GCP في المنطقة us-central1"
- "اسرد جميع حاويات S3 في حساب AWS الخاص بي"
- "ما الأجهزة الظاهرية في Azure التي تعمل في اشتراكي؟"
- "اعرض لي جميع وحدات pod في Kubernetes في مساحة الاسم الافتراضية"
توفير الموارد
أنشئ الموارد السحابية وانشرها باستخدام أوامر حوارية:
- "أنشئ حاوية S3 باسم 'my-data-bucket' في us-west-2"
- "انشر حاوية Cloud Storage في GCP مع تمكين تعيين الإصدارات"
- "شغّل مثيل EC2 صغير الحجم في us-east-1"
- "أنشئ مجموعة موارد في Azure في westus2"
التحليل والتدقيق
نفّذ عمليات تدقيق أمني وفحوصات امتثال:
- "اعرض لي جميع حاويات S3 التي يمكن الوصول إليها بشكل عام"
- "اسرد مستخدمي IAM الذين لم يسجلوا الدخول منذ 90 يومًا"
- "ابحث عن جميع مثيلات GCP التي لا تحمل تصنيفات مناسبة"
- "حدّد الأجهزة الظاهرية في Azure التي لم يتم تمكين النسخ الاحتياطي لها"
العمليات عبر السحابات
استعلم عن الموارد وقارن بينها عبر عدة مزودي خدمات سحابية:
- "اعرض لي جميع مثيلات الحوسبة عبر AWS وGCP وAzure"
- "قارن تكاليف التخزين بين AWS S3 وGCP Cloud Storage"
- "اسرد جميع قواعد البيانات لدى جميع مزودي الخدمات السحابية"
البنية التحتية كتعليمات برمجية
أنشئ استعلامات نشر البنية التحتية ونفّذها:
- "أنشئ مكدس موارد يتضمن VPC وشبكة فرعية ومثيل EC2"
- "انشر نظام مجموعة GKE مكتمل الإعداد مع تجمعات العقد"
- "أعدّ عملية نشر متعددة المناطق في AWS"
تعديل الموارد
حدّث الموارد السحابية الموجودة:
- "أضف الوسوم إلى جميع مثيلات EC2 غير الموسومة"
- "مكّن التشفير لحاوية S3 'my-bucket'"
- "حدّث نوع الجهاز لمثيل GCP 'web-server-1'"
- "غيّر قائمة ACL على حاوية Cloud Storage الخاصة بي لتصبح خاصة"
حذف الموارد
أزل الموارد السحابية عندما لا تعود هناك حاجة إليها:
- "احذف حاوية S3 'temp-bucket'"
- "أزل جميع مثيلات EC2 المتوقفة"
- "نظّف أقراص GCP غير المستخدمة"
مثال على محادثة
إليك مثالًا على كيفية تفاعلك مع Claude Desktop باستخدام StackQL:
أنت: "هل يمكنك أن تعرض لي جميع مثيلات الحوسبة الخاصة بي في GCP؟"
Claude: ينفذ استعلام StackQL ويعيد النتائج في جدول منسق يعرض أسماء المثيلات ومناطق التوفر وأنواع الأجهزة والحالة
أنت: "أنشئ حاوية Cloud Storage جديدة باسم 'analytics-data-2025' في المنطقة us-central1 مع وصول موحد على مستوى الحاوية"
Claude: ينفذ جملة INSERT في StackQL لإنشاء الحاوية ويؤكد إنشاءها
أنت: "الآن اسرد جميع حاويات Cloud Storage الخاصة بي"
Claude: ينفذ استعلام SELECT ويعرض جميع الحاويات بما في ذلك الحاوية التي تم إنشاؤها حديثًا
تلميحات وأفضل الممارسات
-
حدّد طلبك بدقة: كلما زادت دقة طلبك، كانت النتائج التي تحصل عليها أفضل. ضمّن أسماء الموارد والمناطق والسمات المحددة متى أمكن ذلك.
-
استخدم اللغة الطبيعية: لا تحتاج إلى معرفة بناء جملة SQL - يترجم Claude طلباتك المكتوبة باللغة الطبيعية إلى استعلامات StackQL.
-
راجع قبل التنفيذ: في العمليات الهدامة (DELETE، UPDATE)، يعرض لك Claude عادة ما سيتم تنفيذه قبل المتابعة.
-
العمليات متعددة الخطوات: يمكنك ربط العمليات ببعضها في محادثة واحدة. يحتفظ Claude بالسياق طوال الجلسة.
-
معالجة الأخطاء: إذا فشل استعلام، يمكن لـ Claude المساعدة في استكشاف الأخطاء وإصلاحها واقتراح تصحيحات استنادًا إلى رسالة الخطأ.
-
استكشف القدرات: اسأل Claude "ماذا يمكنني أن أفعل باستخدام StackQL؟" للحصول على اقتراحات خاصة بالموفرين الذين قمت بتكوينهم.
استكشاف الأخطاء وإصلاحها
عدم بدء تشغيل خادم MCP
إذا تعذر على Claude Desktop الاتصال بخادم StackQL MCP:
- تحقق من وجود StackQL في PATH الخاص بك
- تحقق من أن الملف
claude_desktop_config.jsonالخاص بك ملف JSON صالح - تأكد من أن مسار الملف في التكوين صحيح لنظام التشغيل الخاص بك
- راجع سجلات Claude Desktop بحثًا عن رسائل الخطأ
أخطاء المصادقة
إذا تلقيت أخطاء مصادقة:
- تحقق من صحة بيانات اعتماد مزود الخدمات السحابية الخاصة بك
- تأكد من وجود ملفات بيانات الاعتماد في المسارات المحددة
- تحقق من أن متغيرات البيئة منسقة بشكل صحيح في التكوين - إن طلب تشغيل
reload_credentialsمن الوكيل يعرض حالة بيانات الاعتماد لكل موفر، وهو أسرع وسيلة لمعرفة المتغير المفقود - تأكد من أن بيانات الاعتماد الخاصة بك تملك الأذونات اللازمة
أخطاء الأذونات
إذا فشلت العمليات بسبب عدم كفاية الأذونات:
- تحقق من أن حساب الخدمة أو مستخدم IAM الخاص بك يملك الأذونات المطلوبة
- تحقق من سياسات IAM الخاصة بكل مزود خدمات سحابية
- تأكد من تمكين خدمات API في مشاريعك السحابية
معرفة المزيد
اعتبارات الأمان
- خزّن بيانات الاعتماد بشكل آمن ولا تودعها أبدًا في نظام التحكم في الإصدارات
- اتبع مبادئ الوصول بالحد الأدنى من الامتيازات لحسابات الخدمة
- دوّر بيانات الاعتماد ومفاتيح API بانتظام
- راقب سجلات خادم MCP بحثًا عن أي نشاط غير معتاد
- فكّر في استخدام أدوات إدارة بيانات الاعتماد التي يوفرها مزودو الخدمات السحابية (على سبيل المثال، Secret Manager وParameter Store)