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

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

التثبيت

تقدم هذه الصفحة إرشادات تثبيت StackQL على منصات مختلفة.

macOS​

StackQL متاح على macOS عبر Homebrew وبرنامج التثبيت pkg، ويدعم برنامج تثبيت واحد متعدد البنى بنيتي ARM (M1/Apple Silicon) وAMD معًا.

للتثبيت عبر Homebrew، شغّل الأمر التالي في الوحدة الطرفية:

brew install stackql

الاستخدام مع عملاء MCP​

يعمل خادم StackQL MCP محليًا عبر stdio، لذا تبقى بيانات اعتماد الموفرين على جهازك مهما كان العميل الذي تستخدمه. اختر عميلك أدناه: تعرض كل علامة تبويب طريقة التثبيت من الدليل أو بنقرة واحدة أولًا، ثم التكوين اليدوي كبديل احتياطي. لمعرفة جميع قنوات التوزيع، بما في ذلك npx وPython وDocker وCI، راجع تثبيت خادم MCP.

Claude Desktop​

الطريقة الموصى بها لتثبيت خادم StackQL MCP في Claude Desktop هي التثبيت من Anthropic Connector Directory (Settings -> Connectors -> Add -> Browse Connectors، ثم ابحث عن StackQL) - يحدد Claude Desktop الملف الثنائي الموقع رقميًا الصحيح لمنصتك تلقائيًا. بدلًا من ذلك، يحتوي كل إصدار من StackQL على ملفات MCP Bundle مبنية مسبقًا (.mcpb) للتثبيت من ملف تم تنزيله - ولا يلزم تثبيت StackQL بشكل منفصل في أي من الحالتين. تتوفر ملفات bundle لأنظمة macOS وWindows وLinux.

تستخدم تنزيلات MCPB لنظامي Linux وWindows البنية amd64 (x64) افتراضيًا. استخدم القوائم المنسدلة لتحديد amd64 أو arm64.


معلومات

خادم StackQL MCP مدرج أيضًا في Official MCP Registry باسم io.github.stackql/stackql-mcp.

تلميح

ملف bundle هو إحدى الطرق العديدة لتشغيل خادم StackQL MCP. راجع استخدام StackQL مع Claude Desktop للاطلاع على الشرح التفصيلي الكامل لـ Claude Desktop، أو تثبيت خادم MCP للاطلاع على خيارات npx وDocker وPython وCI والتثبيت اليدوي.

تثبيت خادم MCP​

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

الأسواق والأدلة​

الخادم منشور في Official MCP Registry باسم io.github.stackql/stackql-mcp؛ وتحمل سجلات الحزم أدناه الملفات الناتجة القابلة للتوزيع، وتأخذ الأدلة التابعة الإدراج من هناك.

السجلالنوعطريقة النشرالإدراجملاحظات
Official MCP Registryسجل بيانات التعريف المعياريأداة CLI mcp-publisher + server.jsonmodelcontextprotocol.io/search
modelcontextprotocol.io/direct
يعلن عن جميع الحزم وعددها 8 (mcpb x5 وoci وnpm وpypi)
npmسجل حزمnpm publish@stackql/mcp-serverأداة التشغيل npx
PyPIسجل حزمtwine uploadstackql-mcp-serverأداة التشغيل uvx / pip
Docker Hubسجل حاوياتdocker buildx --pushstackql/stackql-mcpمتعدد البنى amd64 + arm64
GitHub Actions Marketplaceسوق CI (الإجراء setup-stackql-mcp)مستودع عام + إصدار + إدراج في السوقsetup-stackql-mcp-serverناشر تم التحقق منه؛ stackql/setup-stackql-mcp

ملف bundle .mcpb مبني مسبقًا​

متى تستخدم: في Claude Desktop دون إمكانية الوصول إلى Connector Directory، أو عندما تريد قفل إصدار محدد أو التحقق من المجاميع الاختبارية بنفسك قبل التثبيت. طريقة التثبيت الموصى بها لمعظم مستخدمي Claude Desktop هي Anthropic Connector Directory.

يحتوي كل إصدار من StackQL على ملف MCP Bundle مبني مسبقًا لكل منصة:

https://releases.stackql.io/stackql/latest/stackql-mcp-<platform>.mcpb

حيث <platform> هي إحدى القيم darwin-universal أو windows-x64 (AMD64) أو windows-arm64 أو linux-x64 أو linux-arm64. توجد أزرار التنزيل لكل منصة في علامة التبويب Claude Desktop ضمن الاستخدام مع عملاء MCP. لكل ملف bundle مجموع اختباري .sha256 مطابق في صفحة الإصدار. تحقق منه، ثم ثبّته عبر Settings -> Extensions في Claude Desktop:

shasum -a 256 -c stackql-mcp-darwin-universal.mcpb.sha256

راجع استخدام StackQL مع Claude Desktop للاطلاع على الشرح التفصيلي الكامل.

تكوين الملف claude_desktop_config.json يدويًا​

متى تستخدم: عندما يكون لديك الملف الثنائي stackql في متغير PATH بالفعل وتستخدم Claude Desktop أو أي عميل MCP آخر يعمل عبر stdio.

{
"mcpServers": {
"stackql": {
"command": "stackql",
"args": [
"mcp",
"--mcp.server.type=stdio",
"--approot", "/Users/you/.stackql",
"--mcp.config", "{\"server\": {\"audit\": {\"disabled\": true}}}"
]
}
}
}

الوسيطات الثلاث جميعها ضرورية:

  • --mcp.server.type=stdio تحدد وسيلة النقل stdio التي يستخدمها العملاء المضمنون في المحررات.
  • --approot توجه ذاكرة التخزين المؤقت للموفرين إلى دليل قابل للكتابة. قد يشغل عملاء MCP الخادم مع تعيين دليل العمل إلى /، وهو دليل غير قابل للكتابة.
  • --mcp.config '{"server": {"audit": {"disabled": true}}}' تعطل سجل التدقيق، الذي يستخدم بخلاف ذلك دليل العمل (الذي قد يكون غير قابل للكتابة) كدليل افتراضي له.

أضف بيانات اعتماد الموفرين باستخدام كتلة "env" وعدّل عقد الأمان باستخدام "mode" - راجع أوضاع الخادم.

npx (بدون تثبيت)​

متى تستخدم: في أي بيئة Node، عندما لا تريد تثبيت StackQL على مستوى النظام.

{ "mcpServers": { "stackql": { "command": "npx", "args": ["-y", "@stackql/mcp-server"] } } }

تتولى أداة التشغيل @stackql/mcp-server تنزيل الملف الثنائي stackql الموقع رقميًا عند أول تشغيل، والتحقق من قيمة SHA-256 الخاصة به، وتخزينه مؤقتًا لعمليات التشغيل اللاحقة.

uvx / pip (Python)​

متى تستخدم: في بيئة Python - وهي أداة التشغيل نفسها مجهزة كحزمة لـ Python، وتشترك في ذاكرة التخزين المؤقت للملف الثنائي التي تملؤها أداة التشغيل npx.

{ "mcpServers": { "stackql": { "command": "uvx", "args": ["stackql-mcp-server"] } } }

أو ثبّتها في البيئة الحالية باستخدام pip install stackql-mcp-server (Python 3.9+). الحزمة هي stackql-mcp-server على PyPI.

Docker​

متى تستخدم: في وقت تشغيل داخل حاوية أو معزول بطريقة أخرى. الصورة متعددة البنى (amd64 وarm64).

docker run -i --rm stackql/stackql-mcp

كتكوين للعميل:

{ "mcpServers": { "stackql": { "command": "docker", "args": ["run", "-i", "--rm", "stackql/stackql-mcp"] } } }

الصورة هي stackql/stackql-mcp على Docker Hub.

CI وسير العمل القائم على الوكلاء (GitHub Actions)​

متى تستخدم: لتشغيل الخادم داخل مهمة GitHub Actions حتى يتمكن وكيل من الاستعلام عن بيئتك السحابية - واتخاذ إجراءات عليها إذا سمحت بذلك - كجزء من CI.

يثبت الإجراء stackql/setup-stackql-mcp@v1 الملف الثنائي ويكتب تكوين MCP (بالوضع read_only افتراضيًا). مرّر هذا التكوين إلى anthropics/claude-code-action عبر claude_args:

- id: stackql
uses: stackql/setup-stackql-mcp@v1
with:
auth: '{"github":{"type":"null_auth"}}'

- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: |
Using stackql, list the public repositories in the stackql org and
summarise them as a markdown table.
claude_args: |
--mcp-config ${{ steps.stackql.outputs.mcp-config-file }}
--allowedTools 'mcp__stackql__*'

راجع ملف README الخاص بالإجراء للاطلاع على مزيد من الوصفات القائمة على الوكلاء (عمليات تدقيق السحابة وتقديرات التكلفة وما إلى ذلك).

MCP المضمن​

متى تستخدم: عندما تعمل على بناء تطبيق قائم على الوكلاء وتريد تضمين نسخة محلية من خادم MCP في ملفك الثنائي - بدون npx، وبدون تثبيت منفصل، وبدون تبعية وقت تشغيل.

تشغل المكتبات الأصلية الملف الثنائي stackql الموقع رقميًا عبر stdio خلف عميل MCP SDK الرسمي لكل لغة، بحيث يحصل تطبيقك على واجهة SQL نفسها الخاضعة للحوكمة لكل موفر في السجل. تستخدم كل مكتبة الوضع read_only افتراضيًا - ولا يتم الانتقال إلى وضع يسمح بالكتابة إلا بشكل صريح - ويمكنها إما تنزيل الملف الثنائي والتحقق منه عند أول تشغيل، وإما تضمين نسخة محلية منه في البناء للحصول على ملف تنفيذي واحد مستقل. تجد واجهة API الكاملة لكل لغة في مرجع MCP المضمن.

يشغل crate stackql-mcp الملف الثنائي خلف عميل rmcp. تتولى الميزة الافتراضية sidecar تنزيل الملف الثنائي والتحقق منه عند أول تشغيل؛ أما الميزة vendored فتضمنه باستخدام include_bytes! للحصول على ملف ثنائي واحد مستقل. MSRV: Rust 1.88.

# Cargo.toml
stackql-mcp = "0.1"
use stackql_mcp::{Mode, StackqlMcp};

let server = StackqlMcp::builder()
.mode(Mode::ReadOnly)
.start()
.await?;
let tools = server.list_all_tools().await?;

المرجع الكامل: MCP المضمن: Rust.

نموذج الثقة​

تنطبق خصائص الأمان نفسها على جميع القنوات:

  • الملف الثنائي stackql المضمن موقع رقميًا بتقنية Authenticode (Windows) وموثق من Apple (macOS).
  • يأتي كل ملف bundle .mcpb مع مجموع اختباري SHA-256 منشور في صفحة الإصدار.
  • تتحقق أداتا التشغيل npx وuvx من قيمة SHA-256 للملف الثنائي الذي تم تنزيله قبل أول استخدام.
  • يشهد إدخال MCP Registry على قيم التجزئة لكل منصة.

استخدام GitHub Actions​

تتوفر إجراءات StackQL لـ GitHub Actions للاستخدام في سير عمل GitHub Actions لديك. الإجراءات التالية متاحة:

stackql-deploy​

انشر مكدسات البنية التحتية أو اختبرها باستخدام StackQL مباشرة من سير عمل GitHub لديك. يتيح هذا الإجراء سير عمل البنية التحتية كتعليمات برمجية (IaC) باستخدام بناء جملة شبيه بـ SQL، مما يتيح لك تعريف الموارد السحابية ونشرها وإدارتها عبر موفرين متعددين في سير عمل واحد.


مثال على الاستخدام

...
jobs:
stackql-actions-test:
name: StackQL Actions Test
runs-on: ubuntu-latest
env:
GOOGLE_CREDENTIALS: ${{ secrets.GOOGLE_CREDENTIALS }} # add additional cloud provider creds here as needed

steps:
- name: Checkout
uses: actions/checkout@v6

- name: Deploy a Stack
uses: stackql/stackql-deploy-action@v2
with:
command: 'build'
stack_dir: 'examples/k8s-the-hard-way'
stack_env: 'dev'
env_vars: |
GOOGLE_PROJECT=stackql-k8s-the-hard-way-demo
GOOGLE_REGION=australia-southeast1

مكتبات أخرى​

يوفر StackQL عدة وسائل للتكامل للاستخدام في لغات برمجة وبيئات مختلفة. توسع هذه المكتبات إمكانات StackQL، مما يسهل دمج الاستعلام عن الموارد السحابية وإدارتها في تطبيقاتك الحالية وسير العمل لديك.

حزمة Python pystackql​

غلاف Python لاستخدام StackQL في برامج Python الخاصة بك. الحزمة pystackql متاحة على PyPI، ووثائق الحزمة pystackql متاحة عبر Read the Docs. لتثبيت الحزمة pystackql، شغّل الأمر التالي:

pip install pystackql

يوضح المثال التالي استخدام الحزمة pystackql مع المكتبة pandas لتشغيل استعلامات StackQL وإعادة النتائج إلى كائن pandas.DataFrame:

from pystackql import StackQL
import pandas as pd
region = "ap-southeast-2"
stackql = StackQL()

query = """
SELECT instance_type, COUNT(*) as num_instances
FROM aws.ec2.instances
WHERE region = '%s'
GROUP BY instance_type
""" % (region)

res = stackql.execute(query)
df = pd.read_json(res)
print(df)