Усильте агента
Установка от издателя. Не эндпоинт PlugMCP.
Host a copy with our keys and logs.
В реестре пока нет пакетного релиза. Следуйте README репозитория.
Удалённый URL или команда на вашем компьютере? Чем различаются два способа установки
Запустить на PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
ЗапускОт издателя
Это не generic SQL chatbot. Trusted runtime построен вокруг deterministic
ClickHouse rule engine: каждое срабатывание имеет rule_id, severity, tier,
confidence, объяснение и rewrite-пример там, где rewrite безопасен. AI
используется как интерфейс через MCP и как исследовательский workflow, но не как
источник production-рекомендаций.
CLI advisor for ClickHouse query optimization. Formally verified rewrite rules + RAG + MCP server.
ClickHouse быстро выполняет аналитические запросы, но performance зависит от
деталей движка: MergeTree, sparse primary key, marks/parts, FINAL, skip
indexes, PREWHERE, materialized views, distributed execution, memory/thread
settings и реального workload.
ClickAdvisor закрывает практическую задачу: не “угадать оптимизацию”, а дать проверяемый ClickHouse-specific сигнал, который можно показать DBA, положить в CI, передать AI-агенту через MCP или использовать для workload review queue.
git clone https://github.com/olyannaa/clickadvisor.git
cd clickadvisor
poetry install
poetry run chadvisor analyze --sql query.sql
Docker:
docker build -t clickadvisor .
docker run --rm -p 8000:8000 clickadvisor
По умолчанию Docker image поднимает lightweight Streamable HTTP MCP endpoint
на /mcp. Образ предназначен для demo/deploy сценария и не ставит тяжёлые
ML/retrieval зависимости.
poetry run chadvisor analyze \
--sql query.sql \
--ch-version 25.3 \
--output-format markdown \
--no-retrieval
Пример рискованного запроса:
SELECT
e.country,
COUNT(DISTINCT e.user_id) AS unique_users,
sumIf(e.revenue, e.status = 'paid') AS paid_revenue
FROM
(
SELECT *
FROM events FINAL
WHERE message LIKE '%timeout%'
AND (country = 'RU' OR country = 'KZ' OR country = 'BY')
) AS e
JOIN users AS u
ON toUInt64(e.user_id) = u.id
GROUP BY e.country
HAVING e.country = 'RU'
ORDER BY paid_revenue DESC;
На этом запросе ClickAdvisor находит 10 срабатываний, включая:
R-001: COUNT(DISTINCT user_id) -> uniqExact(user_id);R-002: approximate distinct через uniq, если это допустимо;D-005 / R-102: leading wildcard search и skip-index/search strategy;D-007: дорогой FINAL на MergeTree;D-011, R-008, R-020: приведение типов вокруг JOIN/filter keys;R-011: non-aggregate HAVING можно перенести в WHERE;R-014: дорогой GROUP BY по строковой колонке.CSV export из system.query_log:
poetry run chadvisor workload \
--query-log examples/query_log_sample.csv \
--output-format markdown \
--top-n 3
Live read-only режим через ClickHouse HTTP API:
poetry run chadvisor workload \
--connect http://localhost:8123 \
--user default \
--password secret \
--since 24h \
--output-format markdown \
--top-n 10
workload группирует похожие запросы по normalized fingerprint, считает
executions, total/avg/p95 latency, read rows/bytes и memory usage, затем
прогоняет representative SQL через rule engine и формирует top-N DBA review
queue.
Пример top risk из sample:
Priority: high
Executions: 2
Total duration: 2180 ms
Read bytes: 350000000
Rule IDs: D-003, D-004, D-005, D-007, R-102
Normalized SQL: select * from events final where message like ?
Подробнее: docs/workload.md.
Локальный stdio MCP для Claude Desktop, Cursor, Zed и других MCP-клиентов:
poetry run chadvisor mcp-server
Публичный MCP endpoint для проверки без локальной установки:
https://clickadvisor-mcp-production.up.railway.app/mcp
В Claude / Anthropic API remote MCP подключается как URL-based server:
Claude / Claude Desktop:
Customize -> Connectors -> Add custom connector
Name: ClickAdvisor
URL: https://clickadvisor-mcp-production.up.railway.app/mcp
Claude Code:
claude mcp add --transport http clickadvisor \
https://clickadvisor-mcp-production.up.railway.app/mcp
Anthropic API:
{
"mcp_servers": [
{
"type": "url",
"name": "clickadvisor",
"url": "https://clickadvisor-mcp-production.up.railway.app/mcp"
}
]
}
Доступные MCP tools:
Если открыть /mcp в браузере, можно увидеть ошибку Not Acceptable: Client must accept text/event-stream. Это нормально: endpoint предназначен для MCP
clients, а не для обычной HTML-страницы.
Подробнее:
poetry run chadvisor analyze \
--sql query.sql \
--schema schema.sql \
--explain explain.json \
--environment environment.json
Environment context включает настройки, hardware, cluster и workload facts для
E-* и части Tier 2 advisory rules:
{
"settings": {
"max_threads": 64,
"max_memory_usage": 90000000000,
"join_use_nulls": true
},
"hardware": {
"cpu_cores": 16,
"ram_bytes": 128000000000,
"disk_type": "hdd"
},
"workload": {
"interactive_queries": true,
"large_join": true,
"bulk_inserts": true
},
"cluster": {
"shards": 4,
"replicas": 2
}
}
EXPLAIN ESTIMATE:
poetry run chadvisor analyze \
--sql query.sql \
--connect http://localhost:8123 \
--ch-user default \
--ch-password secret \
--explain-estimate
ClickAdvisor выполняет только EXPLAIN ESTIMATE, не запускает пользовательский
запрос и не читает result data.
DS-часть нужна не для замены rule engine. Её задача — формализовать качество, сравнить подходы, найти ограничения и подготовить triage/prioritization layer.
Expert dataset:
Ключевой факт по источнику меток:
Baseline ladder:
Holdout error analysis для Random Forest:
Вывод: ML полезен для triage, confidence grouping и review queue ordering, но production-рекомендации остаются rule-first.
Подробнее:
Воспроизводимые проверки:
poetry run ruff check clickadvisor tests scripts
poetry run mypy clickadvisor
poetry run pytest --ignore=tests/integration -q
poetry run python scripts/rules/validate_catalog.py
poetry run python scripts/benchmark/validate_cases.py
poetry run python scripts/eval/run_benchmark.py --cases-dir benchmark/cases/synthetic_expanded --mode strict
ClickAdvisor можно запускать внутри компании, CI/CD или локальной среды инженера без отправки SQL, DDL, EXPLAIN, environment context и query_log во внешние LLM/API.
Что может читать ClickAdvisor:
system.query_log CSV или read-only live metadata;SELECT version() при version detection;EXPLAIN ESTIMATE только при явном флаге.Что он не делает по умолчанию:
ANALYZE;Подробнее: docs/security-local-first.md.
MIT
CLI advisor for ClickHouse query optimization. Formally verified rewrite rules + RAG + MCP server.
Инструменты
Списка инструментов пока нет. У удалённых серверов он появляется после первой проверки состояния.
FAQ
Скопируйте на этой странице конфигурацию stdio для Cursor, Claude Desktop, Claude Code или VS Code. Она использует установку издателя, а не прокси PlugMCP.
В этой записи не указано обязательных переменных окружения.
Clickadvisor работает локально через stdio.
Последняя проверка: 2026-10-28. CLI advisor for ClickHouse query optimization. Formally verified rewrite rules + RAG + MCP server.