接入你的智能体
从发布者处安装。不是 PlugMCP 端点。
远程 URL 还是本机命令？ 两种安装方式的区别
来自发布者
Это не 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.
工具
暂无工具列表。远程服务器在首次健康检查后会获得工具列表。
常见问题
在本页复制适用于 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 配置。它使用发布者的安装方式，而不是 PlugMCP 代理。
此记录未列出必需的环境变量。
Clickadvisor 通过 stdio 在本地运行。
上次检查时间：2026-10-28。 CLI advisor for ClickHouse query optimization. Formally verified rewrite rules + RAG + MCP server.