Перейти до основного вмісту
Перекладена сторінка

Цю сторінку перекладено з англійської мови за допомогою ШІ. Якщо тексти відрізняються, еталоном є англійська версія.

Встановлення

Тут наведено інструкції зі встановлення StackQL на різних платформах.

macOS​

StackQL доступний на macOS через Homebrew та інсталятор pkg; один багатоархітектурний інсталятор підтримує обидві архітектури: ARM (M1/Apple Silicon) і Intel (x86_64).

Для встановлення через Homebrew виконайте таку команду у вашому терміналі:

brew install stackql

Використання з клієнтами MCP​

Сервер MCP StackQL працює локально через stdio, тож облікові дані провайдерів залишаються на вашому комп'ютері, хоч би який клієнт ви використовували. Виберіть свій клієнт нижче: кожна вкладка спершу описує шлях через каталог або встановлення одним клацанням, а ручну конфігурацію наводить як резервний варіант. Усі канали розповсюдження, зокрема npx, Python, Docker і CI, див. у розділі Встановлення сервера MCP.

Claude Desktop​

Рекомендований спосіб встановити сервер MCP StackQL у Claude Desktop - з каталогу Anthropic Connector Directory (Settings -> Connectors -> Add -> Browse Connectors, знайдіть StackQL) - Claude Desktop автоматично вибирає правильний підписаний двійковий файл для вашої платформи. Також до кожного випуску StackQL додано попередньо зібрані пакети MCP Bundle (.mcpb) для встановлення із завантаженого файлу - в обох випадках окремо встановлювати StackQL не потрібно. Пакети доступні для macOS, Windows і Linux.

Завантаження MCPB для Linux і Windows за замовчуванням використовують amd64 (x64). Скористайтеся розкривними списками, щоб вибрати amd64 або arm64.


інформація

Сервер MCP StackQL також зареєстровано в Official MCP Registry як io.github.stackql/stackql-mcp.

порада

Пакет - один із кількох способів запустити сервер MCP StackQL. Повне покрокове керівництво для Claude Desktop див. на сторінці Використання StackQL із Claude Desktop, а варіанти з npx, Docker, Python, CI і ручним налаштуванням - у розділі Встановлення сервера MCP.

Встановлення сервера MCP​

Сервер MCP StackQL дає змогу агентам ШІ виконувати запити до хмарних ресурсів і створювати їх за допомогою 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

Попередньо зібраний пакет .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. Для кожного пакета на сторінці випуску є відповідна контрольна сума .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+). На PyPI це пакет stackql-mcp-server.

Docker​

Коли використовувати: контейнеризоване або іншим чином ізольоване середовище виконання. Образ багатоархітектурний (amd64 і arm64).

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

Як конфігурація клієнта:

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

У Docker Hub це образ stackql/stackql-mcp.

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).
  • Кожен пакет .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
region = "ap-southeast-2"
stackql = StackQL(output='pandas')

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

df = stackql.execute(query)
print(df)