# التثبيت

> ثبّت StackQL على macOS أو Linux أو Windows أو Docker أو واجهة أوامر سحابية، واستخدم خادم StackQL MCP من Claude Desktop وChatGPT وGoose وعملاء MCP آخرين أو عبر npx وuvx وpip وDocker وGitHub Actions.

Source: https://stackql.io/ar/installing-stackql

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

**macOS**

## macOS

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

**Homebrew**

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

```bash
brew install stackql
```

**curl (ملف ثنائي موقع رقميًا وموثق)**

لتثبيت الملف التنفيذي `stackql` الموقع رقميًا والموثق في الدليل الحالي، شغّل الأمر التالي في الوحدة الطرفية:

```bash
curl -fsSL https://get-stackql.io/install | sh
```

**تنزيل الحزمة**

StackQL متاح على شكل برنامج تثبيت `pkg` تفاعلي موقع رقميًا وموثق لنظام macOS.

[تنزيل PKG لنظام macOS](https://releases.stackql.io/stackql/latest/stackql_darwin_multiarch.pkg)

**Linux**

## Linux

StackQL متاح لجميع بنى Linux.

**curl**

لتثبيت الملف التنفيذي `stackql` في الدليل الحالي لبنية Linux لديك (amd64 أو arm64)، شغّل الأمر التالي في الوحدة الطرفية:

```bash
curl -fsSL https://get-stackql.io/install | sh
```

**تنزيل الحزمة**

بدلًا من ذلك، يمكنك تنزيل الملفات الثنائية من هنا:

[تنزيل ZIP لنظام Linux (amd64)](https://releases.stackql.io/stackql/latest/stackql_linux_amd64.zip)
[تنزيل ZIP لنظام Linux (arm64)](https://releases.stackql.io/stackql/latest/stackql_linux_arm64.zip)

**Windows**

## Windows

StackQL متاح على Windows عبر Chocolatey وبرنامج تثبيت نصي لـ PowerShell وبرنامج التثبيت MSI. تتوفر إصدارات بناء أصلية لـ AMD64 (x64) وARM64 على شكل برامج تثبيت MSI وملفات ZIP مضغوطة تحتوي على `stackql.exe`. يعمل إصدار بناء AMD64 أيضًا على ARM64 عبر المحاكاة. جميع الملفات التنفيذية موقعة رقميًا بشهادة توقيع تعليمات برمجية من نوع Authenticode.

**Chocolatey**

للتثبيت عبر Chocolatey، شغّل الأمر التالي في الوحدة الطرفية لـ PowerShell أو `cmd`:

```powershell
choco install stackql
```

**Invoke-RestMethod**

لتثبيت ملف تنفيذي موقع رقميًا بتقنية Authenticode في الدليل الحالي، شغّل ما يلي في وحدة طرفية لـ PowerShell:

```powershell
Invoke-RestMethod https://get-stackql.io/install | Invoke-Expression
# or
irm https://get-stackql.io/install | iex
```

**تنزيل MSI/ZIP**

نزّل برنامج التثبيت أو الملف التنفيذي `stackql` الموقع رقميًا لنظام Windows أدناه. يؤدي النقر على زر التنزيل إلى تحديد AMD64 افتراضيًا؛ استخدم القائمة المنسدلة الخاصة به لاختيار AMD64 أو ARM64 الأصلي.

[تنزيل MSI لنظام Windows](https://releases.stackql.io/stackql/latest/stackql_windows_amd64.msi)
[تنزيل ZIP لنظام Windows](https://releases.stackql.io/stackql/latest/stackql_windows_amd64.zip)

**Docker**

## Docker

ننشر إصدارات بناء StackQL على [Docker Hub](https://hub.docker.com/u/stackql).

__Docker Hub__  

لسحب صورة حاوية StackQL، شغّل الأمر التالي:

```bash
docker pull stackql/stackql
```

من الإصدار `v1.0` فصاعدًا، تعتمد الصورة على Ubuntu 26.04 LTS، وننشر صورة بديلة مثبت عليها Python 3.13 مسبقًا تحمل لاحقة الوسم `-python3.13` (والاسم المستعار `-python3`)، على سبيل المثال:

```bash
docker pull stackql/stackql:latest-python3.13
```

**stackql-deploy**

## `stackql-deploy`

`stackql-deploy` هو إطار عمل IaC عديم الحالة مبني على StackQL. للاطلاع على الوثائق الكاملة، راجع [__وثائق StackQL Deploy__](https://stackql-deploy.io/).

__Linux / macOS__

يتولى الأمر التالي تنزيل أحدث ملف ثنائي `stackql-deploy` واستخراجه في خطوة واحدة. يكتشف برنامج التثبيت نظام التشغيل والبنية لديك (بما في ذلك Apple Silicon وIntel عبر ملف ثنائي universal لنظام macOS) ويحصل على ملف الإصدار الصحيح تلقائيًا.
```bash
curl -fsSL https://get-stackql-deploy.io/install.sh | sh
```

__Windows__

يتولى الأمر التالي تنزيل أحدث ملف ثنائي `stackql-deploy` واستخراجه في الدليل الحالي.
يكتشف برنامج التثبيت منصتك ويحصل على ملف الإصدار الصحيح تلقائيًا.
```powershell
irm https://get-stackql-deploy.io/install.ps1 | iex
```

__cargo__

إذا كانت سلسلة أدوات Rust مثبتة لديك، فإن هذا الأمر يبني الملف الثنائي ويثبته مباشرة من [__crates.io__](https://crates.io/crates/stackql-deploy).
```bash
cargo install stackql-deploy
```

**واجهات الأوامر السحابية**

## واجهات الأوامر السحابية

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

**AWS**

### AWS CloudShell

يوفر AWS CloudShell واجهة أوامر تعمل في المتصفح، تم فيها مسبقًا تثبيت AWS CLI وإعداد المصادقة الخاصة به. يتيح لك تشغيل StackQL في AWS CloudShell الاستعلام عن موارد AWS وإدارتها دون خطوات مصادقة إضافية. للحصول على إرشادات مفصلة، راجع [برنامجنا التعليمي حول AWS CloudShell](/quick-starts/aws/aws-cloud-shell).

أولًا، نزّل حزمة StackQL:

```bash
curl -fsSL https://get-stackql.io/install/aws | sh
```
ثم شغّل البرنامج النصي لـ StackQL في AWS CloudShell:

```bash
./stackql-aws-cloud-shell.sh
```  

يبدأ هذا البرنامج النصي واجهة أوامر StackQL باستخدام بيانات اعتماد AWS CloudShell الخاصة بك، مما يتيح لك البدء فورًا في الاستعلام عن موارد AWS.

**Azure**

### Azure Cloud Shell

يوفر Azure Cloud Shell بيئة واجهة أوامر يمكن الوصول إليها من المتصفح، تمت فيها مسبقًا مصادقة Azure CLI بحساب Azure الخاص بك. يتيح استخدام StackQL في Azure Cloud Shell الاستعلام بسلاسة عن موارد Azure دون إعداد إضافي. للاطلاع على التفاصيل الكاملة، راجع [دليلنا حول Azure Cloud Shell](/blog/tutorials/using-stackql-in-native-cloud-shells-in-aws-azure-and-gcp#using-stackql-in-the-azure-cloud-shell).

أولًا، نزّل حزمة StackQL:

```bash
curl -fsSL https://get-stackql.io/install/azure | sh
```

ثم شغّل البرنامج النصي لـ StackQL في Azure Cloud Shell:

```bash
./stackql-azure-cloud-shell.sh
```

يتولى هذا البرنامج النصي تلقائيًا تكوين جلسة StackQL لاستخدام بيانات اعتماد Azure Cloud Shell الخاصة بك، مما يتيح لك الاستعلام عن موارد Azure فورًا.

**Google**

### Google Cloud Shell

يوفر Google Cloud Shell بيئة للتطوير والعمليات تمت فيها مسبقًا مصادقة Google Cloud CLI. يتيح لك تشغيل StackQL في Google Cloud Shell الاستعلام عن موارد GCP باستخدام المصادقة الحالية لديك. لمعرفة المزيد، راجع [دليلنا حول Google Cloud Shell](/blog/tutorials/using-stackql-in-native-cloud-shells-in-aws-azure-and-gcp#using-stackql-in-the-google-cloud-shell).

أولًا، نزّل حزمة StackQL:

```bash
curl -fsSL https://get-stackql.io/install/google | sh
```

ثم شغّل البرنامج النصي لـ StackQL في Google Cloud Shell:

```bash
./stackql-google-cloud-shell.sh
```

يتولى البرنامج النصي إعداد StackQL لاستخدام بيانات اعتماد Google Cloud Shell الخاصة بك، مما يتيح لك البدء فورًا في الاستعلام عن موارد GCP باستخدام بناء جملة SQL.

**Databricks**

### Databricks Web Terminal

تتضمن مساحات عمل Databricks وحدة طرفية على الويب تعمل بهوية المستخدم الذي سجل الدخول. يتيح لك تشغيل StackQL هناك الاستعلام عن مساحة العمل باستخدام هوية Databricks الخاصة بك، دون إعداد مصادقة منفصل. للاطلاع على أمثلة استعلامات والمصادقة على مستوى الحساب، راجع [دليلنا حول Databricks Web Terminal](/blog/tutorials/stackql-in-databricks-web-terminal).

أولًا، نزّل حزمة StackQL:

```bash
curl -fsSL https://get-stackql.io/install/databricks | sh
```

ثم شغّل البرنامج النصي لواجهة أوامر StackQL في Databricks:

```bash
./stackql-databricks-shell.sh
```

يبدأ ذلك جلسة StackQL باستخدام هوية مساحة عمل Databricks الخاصة بك، بحيث يمكنك الاستعلام فورًا عن الموارد التي يقتصر نطاقها على مساحة العمل مثل `databricks_workspace.iam.vw_user_entitlements`. للاستعلامات على مستوى الحساب (التوفير والفوترة وIAM الخاص بالحساب)، عيّن متغيرات كيان خدمة OAuth2 في Databricks كما هو موضح في الدليل.

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

يعمل خادم StackQL MCP محليًا عبر stdio، لذا تبقى بيانات اعتماد الموفرين على جهازك مهما كان العميل الذي تستخدمه. اختر عميلك أدناه: تعرض كل علامة تبويب طريقة التثبيت من الدليل أو بنقرة واحدة أولًا، ثم التكوين اليدوي كبديل احتياطي. لمعرفة جميع قنوات التوزيع، بما في ذلك `npx` وPython وDocker وCI، راجع [تثبيت خادم MCP](#installing-the-mcp-server).

**Claude Desktop**

### Claude Desktop

  الطريقة الموصى بها لتثبيت خادم StackQL MCP في Claude Desktop هي التثبيت من [Anthropic Connector Directory](https://claude.ai/directory/connectors/ant.dir.gh.stackql.stackql) (**Settings -> Connectors -> Add -> Browse Connectors**، ثم ابحث عن **StackQL**) - يحدد Claude Desktop الملف الثنائي الموقع رقميًا الصحيح لمنصتك تلقائيًا. بدلًا من ذلك، يحتوي كل إصدار من StackQL على ملفات MCP Bundle مبنية مسبقًا (`.mcpb`) للتثبيت من ملف تم تنزيله - ولا يلزم تثبيت StackQL بشكل منفصل في أي من الحالتين. تتوفر ملفات bundle لأنظمة macOS وWindows وLinux.

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

  [تنزيل MCPB لنظام macOS](https://releases.stackql.io/stackql/latest/stackql-mcp-darwin-universal.mcpb)
[تنزيل MCPB لنظام Linux](https://releases.stackql.io/stackql/latest/stackql-mcp-linux-x64.mcpb)
[تنزيل MCPB لنظام Windows](https://releases.stackql.io/stackql/latest/stackql-mcp-windows-x64.mcpb)

:::info

خادم StackQL MCP مدرج أيضًا في [__Official MCP Registry__](https://registry.modelcontextprotocol.io/v0/servers?search=stackql) باسم `io.github.stackql/stackql-mcp`.

:::

:::tip

ملف bundle هو إحدى الطرق العديدة لتشغيل خادم StackQL MCP. راجع [__استخدام StackQL مع Claude Desktop__](/getting-started/claude-desktop) للاطلاع على الشرح التفصيلي الكامل لـ Claude Desktop، أو [__تثبيت خادم MCP__](#installing-the-mcp-server) للاطلاع على خيارات npx وDocker وPython وCI والتثبيت اليدوي.

:::

**ChatGPT**

### ChatGPT وCodex

  يتوفر StackQL كمكون إضافي محلي لتطبيق ChatGPT لسطح المكتب وCodex CLI. يشغل المكون الإضافي خادم StackQL MCP عبر stdio على جهازك، لذا لا تغادر بيانات اعتماد الموفرين جهازك أبدًا. يلزم Node.js 24.22.1 أو إصدار أحدث (22.23.4 أو 26.12.1 في خطوط الإصدار تلك)؛ ولا يحتاج المكون الإضافي إلا إلى الوحدات المدمجة في Node.js، ويتولى تنزيل الملف الثنائي `stackql` الموقع رقميًا عند أول استخدام والتحقق من قيمة SHA-256 الخاصة به.

  **تطبيق ChatGPT لسطح المكتب (دليل المكونات الإضافية):**

  افتح دليل المكونات الإضافية في تطبيق ChatGPT لسطح المكتب، وابحث عن **StackQL** وانقر على **Install**، ثم شغّل إعداد المكون الإضافي؛ ترشدك المهارة `stackql-setup` المرفقة خلال إعداد بيانات الاعتماد وأول استعلام. يحمل الإدراج شارة **Desktop only**: لا يمكن تثبيت المكون الإضافي إلا من تطبيق سطح المكتب، وليس من ChatGPT على الويب أو الأجهزة المحمولة، وتتوفر أدواته في وضع Work، داخل threads تعمل على جهاز الكمبيوتر الخاص بك. إذا لم يظهر الإدراج في دليلك بعد، فثبّته من سوق المستودع بدلًا من ذلك.

  **تطبيق ChatGPT لسطح المكتب (سوق المستودع):**

  افتح **Settings -> Plugins -> Add -> Add from GitHub**، وأدخل `stackql/stackql`، ثم ثبّت **StackQL** من القسم **Personal** في دليل المكونات الإضافية وأعد تشغيل التطبيق.

  **Codex CLI:**

  ```shell
  codex plugin marketplace add stackql/stackql --sparse .agents/plugins --sparse packaging/openai-plugin
  codex plugin add stackql@stackql
  ```

  أعد تشغيل ChatGPT لسطح المكتب أو Codex، ثم جرّب: *استخدم StackQL لتثبيت موفر GitHub إذا لزم الأمر، ثم اسرد أول خمس خدمات في GitHub.* توضع بيانات اعتماد الموفرين في `~/.stackql/.env` باستخدام أسماء متغيرات البيئة القياسية لكل موفر (على سبيل المثال `AWS_ACCESS_KEY_ID` و`AWS_SECRET_ACCESS_KEY`)؛ بعد تعديل الملف، اطلب من الوكيل استدعاء الأداة `reload_credentials`.

  **بدون المكون الإضافي:**

  ضمن **Settings -> Plugins -> MCPs -> Connect to a custom MCP**، اختر **STDIO**، وعيّن `npx` كأمر وأضف الوسيطتين `-y` و`@stackql/mcp-server`. قدّم بيانات اعتماد الموفرين كمتغيرات بيئة في نموذج الإدخال نفسه.

:::note

لا يستطيع ChatGPT على الويب والأجهزة المحمولة تشغيل خادم stdio محلي، لذا يقتصر المكون الإضافي على تطبيق سطح المكتب وCodex. قد يؤدي خطأ برمجي مفتوح في ChatGPT لسطح المكتب ([openai/codex#38162](https://github.com/openai/codex/issues/38162)) إلى إخفاء أدوات MCP المحلية من جلسات **Chat**؛ ولا تتأثر threads في وضع Work وthreads في Codex وCodex CLI.

:::

**Goose**

### Goose

  يشغل Goose ملحقات stdio مباشرة، لذا فإن أداة التشغيل `npx` هي كل ما تحتاج إليه (Node.js 18 أو إصدار أحدث).

  **Goose Desktop:** انقر على الزر أدناه. يفتح Goose، ويعرض الأمر الذي سيشغله ويطلب منك التأكيد، ثم يضيف StackQL كملحق.

  التثبيت في Goose Desktop

  الزر هو رابط عميق `goose://`؛ يمكنك أيضًا لصقه في شريط العناوين في متصفحك، أو فتحه من وحدة طرفية باستخدام `open` (macOS) أو `start` (Windows) أو `xdg-open` (Linux):

  ```
  goose://extension?cmd=npx&arg=-y&arg=%40stackql%2Fmcp-server&id=stackql&name=StackQL&description=Query%20and%20provision%20cloud%20and%20SaaS%20resources%20with%20SQL
  ```

  **Goose CLI:**

  ```shell
  goose session --with-extension "npx -y @stackql/mcp-server"
  ```

  أو شغّل الأمر `goose configure`، واختر **Add Extension -> Command-line Extension**، وأدخل الأمر نفسه. قدّم بيانات اعتماد الموفرين كمتغيرات بيئة للملحق عندما يطلب Goose منك ذلك.

:::note

أوقف Goose دليل الملحقات داخل التطبيق لصالح [Official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=stackql)، حيث StackQL مدرج باسم `io.github.stackql/stackql-mcp`. بمجرد أن يطلق Goose ميزة الاستيراد من السجل، سيصبح بالإمكان العثور على StackQL هناك دون أي إجراء إضافي.

:::

## تثبيت خادم MCP

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

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

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

**السجلات**

| السجل | النوع | طريقة النشر | الإدراج | ملاحظات |
|---|---|---|---|---|
| Official MCP Registry | سجل بيانات التعريف المعياري | أداة CLI `mcp-publisher` + `server.json` | [`modelcontextprotocol.io/search`](https://registry.modelcontextprotocol.io/v0/servers?search=stackql) [`modelcontextprotocol.io/direct`](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.stackql/stackql-mcp) | يعلن عن جميع الحزم وعددها 8 (`mcpb x5` و`oci` و`npm` و`pypi`) |
| npm | سجل حزم | `npm publish` | [`@stackql/mcp-server`](https://www.npmjs.com/package/@stackql/mcp-server) | أداة التشغيل `npx` |
| PyPI | سجل حزم | `twine upload` | [`stackql-mcp-server`](https://pypi.org/project/stackql-mcp-server/) | أداة التشغيل `uvx` / `pip` |
| Docker Hub | سجل حاويات | `docker buildx --push` | [`stackql/stackql-mcp`](https://hub.docker.com/r/stackql/stackql-mcp) | متعدد البنى `amd64` + `arm64` |
| GitHub Actions Marketplace | سوق CI (الإجراء `setup-stackql-mcp`) | مستودع عام + إصدار + إدراج في السوق | [`setup-stackql-mcp-server`](https://github.com/marketplace/actions/setup-stackql-mcp-server) | ناشر تم التحقق منه؛ [`stackql/setup-stackql-mcp`](https://github.com/stackql/setup-stackql-mcp) |

**الأدلة**

الإدراجات في الأدلة ومواقع التجميع، مرتبة تقريبًا حسب أهميتها في الاكتشاف:

| الدليل | النوع | الإدراج |
|---|---|---|
| __Anthropic Connector Directory__ | دليل داخل تطبيق Claude Desktop | [claude.ai/directory](https://claude.ai/directory/connectors/ant.dir.gh.stackql.stackql) |
| __OpenAI Plugin Directory__ | دليل داخل تطبيق ChatGPT لسطح المكتب (سطح المكتب فقط) | ابحث عن **StackQL** في تطبيق ChatGPT لسطح المكتب؛ راجع [ChatGPT وCodex](#using-with-mcp-clients) |
| __Cursor Directory__ | دليل عملاء IDE | [cursor.directory](https://cursor.directory/plugins/stackql-mcp-server) |
| __mcp.so__ | أكبر موقع تجميع | [mcp.so](https://mcp.so/server/stackql/stackql) |
| __PulseMCP__ | الاكتشاف، داعم للسجل | [pulsemcp](https://www.pulsemcp.com/servers/stackql) |
| __Glama.ai MCP__ | سوق قابل للبحث | [glama.ai](https://glama.ai/mcp/servers/stackql/stackql) |
| __mcpmarket.com__ | موقع تجميع | [mcpmarket](https://mcpmarket.com/server/stackql) |
| __mcpservers.org__ | موقع awesome-list | [mcpservers.org](https://mcpservers.org/servers/stackql-mcp-server) |

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

**متى تستخدم:** في Claude Desktop دون إمكانية الوصول إلى Connector Directory، أو عندما تريد قفل إصدار محدد أو التحقق من المجاميع الاختبارية بنفسك قبل التثبيت. طريقة التثبيت الموصى بها لمعظم مستخدمي Claude Desktop هي [Anthropic Connector Directory](https://claude.ai/directory/connectors/ant.dir.gh.stackql.stackql).

يحتوي كل إصدار من 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](#using-with-mcp-clients). لكل ملف bundle مجموع اختباري `.sha256` مطابق في [صفحة الإصدار](https://github.com/stackql/stackql/releases/latest). تحقق منه، ثم ثبّته عبر **Settings -> Extensions** في Claude Desktop:

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

راجع [استخدام StackQL مع Claude Desktop](/getting-started/claude-desktop#install-from-a-downloaded-bundle) للاطلاع على الشرح التفصيلي الكامل.

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

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

```json
{
  "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"` - راجع [أوضاع الخادم](/command-line-usage/mcp#server-modes).

### `npx` (بدون تثبيت)

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

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

تتولى أداة التشغيل [`@stackql/mcp-server`](https://www.npmjs.com/package/@stackql/mcp-server) تنزيل الملف الثنائي `stackql` الموقع رقميًا عند أول تشغيل، والتحقق من قيمة SHA-256 الخاصة به، وتخزينه مؤقتًا لعمليات التشغيل اللاحقة.

### `uvx` / `pip` (Python)

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

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

أو ثبّتها في البيئة الحالية باستخدام `pip install stackql-mcp-server` (Python 3.9+). الحزمة هي [`stackql-mcp-server`](https://pypi.org/project/stackql-mcp-server/) على PyPI.

### Docker

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

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

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

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

الصورة هي [`stackql/stackql-mcp`](https://hub.docker.com/r/stackql/stackql-mcp) على Docker Hub.

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

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

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

```yaml
- 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 الخاص بالإجراء](https://github.com/stackql/setup-stackql-mcp) للاطلاع على مزيد من الوصفات القائمة على الوكلاء (عمليات تدقيق السحابة وتقديرات التكلفة وما إلى ذلك).

### MCP المضمن

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

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

**Rust**

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

```toml
# Cargo.toml
stackql-mcp = "0.1"
```

```rust
use stackql_mcp::{Mode, StackqlMcp};

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

[عرض على GitHub](https://github.com/stackql/stackql-mcp-rs)
[عرض على crates.io](https://crates.io/crates/stackql-mcp)

المرجع الكامل: [MCP المضمن: Rust](/mcp/embedded/rust).

**Go**

تشغل المكتبة `stackql-mcp-go` الملف الثنائي خلف عميل Go MCP SDK الرسمي. ضمّن نسخة محلية من الملف الثنائي باستخدام `go:embed` للحصول على ملف ثنائي واحد مستقل، أو دعها تتولى تنزيله والتحقق منه عند أول تشغيل. تبدأ المكتبة بالوضع `read_only` افتراضيًا.

```bash
go get github.com/stackql/stackql-mcp-go
```

```go
import (
    "context"
    stackqlmcp "github.com/stackql/stackql-mcp-go/embed"
)

client, err := stackqlmcp.StartServer(ctx, stackqlmcp.Options{
    Binary: StackqlMCPBinary(),
})
defer client.Close()
```

[عرض على GitHub](https://github.com/stackql/stackql-mcp-go)
[عرض على pkg.go.dev](https://pkg.go.dev/github.com/stackql/stackql-mcp-go)

المرجع الكامل: [MCP المضمن: Go](/mcp/embedded/go).

**Kotlin / JVM**

تشغل المكتبة `io.stackql:stackql-mcp` الملف الثنائي خلف عميل Kotlin MCP SDK الرسمي، ويربط مكون Gradle إضافي مصاحب عملية التشغيل نفسها بالبناء. تتطلب JDK 17 وKotlin 2.x.

```kotlin
dependencies {
    implementation("io.stackql:stackql-mcp:0.1.0")
}
```

```kotlin
import io.stackql.mcp.Mode
import io.stackql.mcp.StackqlMcp

val server = StackqlMcp.builder().mode(Mode.ReadOnly).start()
server.use {
    val tools = server.client.listTools().tools
}
```

[عرض على GitHub](https://github.com/stackql/stackql-mcp-kotlin)

المرجع الكامل: [MCP المضمن: Kotlin / JVM](/mcp/embedded/kotlin).

**.NET**

تشغل الحزمة `StackQL.Mcp` الملف الثنائي خلف عميل C# MCP SDK الرسمي. تعمل بوضع sidecar افتراضيًا، أو يمكنك تضمين نسخة محلية من ملف bundle كمورد بناء للحصول على ملف تنفيذي مستقل. تتطلب .NET 8 أو أحدث.

```bash
dotnet add package StackQL.Mcp
```

```csharp
using StackQL.Mcp;

await using var server = await StackqlMcp.CreateBuilder()
    .WithMode(StackqlMode.ReadOnly)
    .StartAsync();

var tools = await server.ListToolsAsync();
```

[عرض على GitHub](https://github.com/stackql/stackql-mcp-dotnet)

المرجع الكامل: [MCP المضمن: .NET / C#](/mcp/embedded/dotnet).

**Gleam**

تستهدف المكتبة `stackql_mcp` وقت تشغيل Erlang/BEAM وتعرض الخادم كعملية فرعية في OTP عبر `child_spec()`، بحيث يمكن وضعه داخل شجرة الإشراف (supervision tree) الخاصة بك. تبدأ المكتبة بالوضع `read_only` افتراضيًا.

```bash
gleam add stackql_mcp
```

```gleam
import envoy
import stackql_mcp

let assert Ok(server) =
  stackql_mcp.start(
    config: stackql_mcp.default_config(),
    home: "/home/u", os: "linux", arch: "x86_64",
    getenv: envoy.get,
  )
let assert Ok(tools) = stackql_mcp.list_tools(server)
```

[عرض على GitHub](https://github.com/stackql/stackql-mcp-gleam)

المرجع الكامل: [MCP المضمن: Gleam](/mcp/embedded/gleam).

**Swift**

تشغل الحزمة `stackql-mcp-swift` الملف الثنائي خلف عميل Swift MCP SDK الرسمي. الملف الثنائي `darwin-universal` موقع رقميًا بمعرف Developer ID وموثق من Apple، لذا يمكنك تجميعه داخل تطبيق `.app` موقع رقميًا مع الحفاظ على صلاحية توثيق التطبيق. تتطلب macOS 13+ وSwift 6.1 (Xcode 16.3+).

```swift
// Package.swift
.package(url: "https://github.com/stackql/stackql-mcp-swift.git", from: "0.1.0")
```

```swift
import StackQLMCP

var options = Options()
options.mode = .readOnly

let server = try await StackQLServer.start(options)
let tools = try await server.listToolNames()
await server.stop()
```

[عرض على GitHub](https://github.com/stackql/stackql-mcp-swift)

المرجع الكامل: [MCP المضمن: Swift](/mcp/embedded/swift).

### نموذج الثقة

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

- الملف الثنائي `stackql` المضمن موقع رقميًا بتقنية Authenticode (Windows) وموثق من Apple (macOS).
- يأتي كل ملف bundle `.mcpb` مع مجموع اختباري SHA-256 منشور في صفحة الإصدار.
- تتحقق أداتا التشغيل `npx` و`uvx` من قيمة SHA-256 للملف الثنائي الذي تم تنزيله قبل أول استخدام.
- يشهد إدخال [MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=stackql) على قيم التجزئة لكل منصة.

## استخدام GitHub Actions

تتوفر [إجراءات StackQL لـ GitHub Actions](https://github.com/stackql/stackql-actions-demo) للاستخدام في سير عمل GitHub Actions لديك. الإجراءات التالية متاحة:

**stackql-deploy**

### `stackql-deploy`

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

[عرض على GitHub Marketplace](https://github.com/marketplace/actions/stackql-deploy)
[عرض على GitHub](https://github.com/stackql/stackql-deploy-action)

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

```yaml
...
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
```

**setup-stackql**

### `setup-stackql`

إعداد StackQL في سير عمل GitHub Actions لديك.

[عرض على GitHub Marketplace](https://github.com/marketplace/actions/setup-stackql)
[عرض على GitHub](https://github.com/stackql/setup-stackql)

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

```yaml
- name: setup StackQL
  uses: stackql/setup-stackql@v2
  with:
    use_wrapper: true

- name: Use GitHub Provider
  run: |
    stackql exec -i ./examples/github-example.iql
  env: 
    STACKQL_GITHUB_USERNAME: ${{  secrets.STACKQL_GITHUB_USERNAME }}
    STACKQL_GITHUB_PASSWORD: ${{  secrets.STACKQL_GITHUB_PASSWORD }}
```

**setup-stackql-mcp**

### `setup-stackql-mcp`

ثبّت خادم StackQL MCP في سير عمل GitHub Actions لديك. يثبت الإجراء الملف الثنائي الموقع رقميًا ويكتب تكوين `mcpServers` (بالوضع `read_only` افتراضيًا) تستخدمه خطوة قائمة على الوكلاء مثل `anthropics/claude-code-action` عبر `claude_args`.

[عرض على GitHub Marketplace](https://github.com/marketplace/actions/setup-stackql-mcp-server)
[عرض على GitHub](https://github.com/stackql/setup-stackql-mcp)

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

```yaml
- 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__*'
```

**stackql-exec**

### `stackql-exec`

نفّذ أوامر StackQL في سير عمل GitHub Actions لديك. يمكنك تقديم الاستعلامات مباشرة في التكوين أو من ملف في المستودع.

[عرض على GitHub Marketplace](https://github.com/marketplace/actions/stackql-exec)
[عرض على GitHub](https://github.com/stackql/stackql-exec)

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

```yaml
- name: exec github example
  uses: stackql/stackql-exec@v2
  with:
    query: |
      select total_private_repos
      from github.orgs.orgs
      where org = 'stackql'
  env: 
    STACKQL_GITHUB_USERNAME: ${{  secrets.STACKQL_GITHUB_USERNAME }}
    STACKQL_GITHUB_PASSWORD: ${{  secrets.STACKQL_GITHUB_PASSWORD }}
```

**stackql-assert**

### `stackql-assert`

شغّل اختبارات الوحدة في سير عمل GitHub Actions لديك (لعمليات التحقق الخاصة بالضمان أو الحوكمة أو أمان السحابة).

[عرض على GitHub Marketplace](https://github.com/marketplace/actions/stackql-assert)
[عرض على GitHub](https://github.com/stackql/stackql-assert)

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

```yaml
- name: Use test query string and expected rows
  uses: stackql/stackql-assert@v2
  with:
    test_query: |
        SELECT name
        FROM google.compute.instances 
        WHERE project = 'stackql-demo' AND zone = 'australia-southeast1-a' AND name = 'stackql-demo-001';
    expected_rows: 1
  env: 
    GOOGLE_CREDENTIALS: ${{ secrets.GOOGLE_CREDENTIALS }}
```

## مكتبات أخرى

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

**pystackql**

### حزمة Python `pystackql`

غلاف Python لاستخدام StackQL في برامج Python الخاصة بك. الحزمة `pystackql` متاحة على [__PyPI__](https://pypi.org/project/pystackql/)، ووثائق الحزمة `pystackql` متاحة عبر [__Read the Docs__](https://pystackql.readthedocs.io/en/latest/). لتثبيت الحزمة `pystackql`، شغّل الأمر التالي:

```bash
pip install pystackql
```

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

```python
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)
```
