Ти підключаєш Claude до бази даних і питаєш її людською мовою. Claude сам дивиться, які є таблиці, читає їхню структуру, пише SQL, будує графіки й звертається до ML-моделі.
Робить це не магія, а маленький Python-сервер зі 150 рядків змістовного коду — той, що в цьому репозиторії. Він називається MCP-сервером, і наприкінці ти зможеш написати такий самий для своїх даних.
Попередні знання про MCP не потрібні.
Ти → Claude → MCP-сервер → база даних
П'ять інструментів. Claude сам вирішує, що і в якому порядку викликати.
| Інструмент | Що робить |
|---|---|
list_tables |
які є таблиці, скільки в них рядків, про що вони |
describe_table |
колонки, типи, зв'язки та пояснення особливостей даних |
run_sql |
виконує SELECT-запит: тільки читання, з лімітом і таймаутом |
save_report |
зберігає HTML-звіт, який Claude намалював сам |
predict_churn |
оцінює ризик відтоку учня ML-моделлю |
Інструмента «побудувати графік» тут немає навмисно. Claude малює візуалізації краще, ніж це зробив би тул із трьома параметрами. Наша справа — зберегти готовий результат у файл, щоб його можна було переслати колезі.
Докладно, з перевірками на кожному кроці — docs/SETUP.md. Якщо коротко, потрібні три речі:
- Python 3.10 або новіший — python.org
- Claude Desktop — claude.ai/download
- Git — щоб завантажити цей репозиторій
Docker потрібен лише в одному з двох варіантів роботи з базою — про це нижче.
git clone https://github.com/hpylieva/data-analyst-agent.git
cd data-analyst-agent
python3 -m venv .venv
source .venv/bin/activateНа Windows остання команда інша: .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .envДва варіанти. Обери один — обидва дають однаковий результат.
Ведуча дає рядок до бази, яка вже заповнена й лежить у хмарі. Відкрий файл
.env і встав його в рядок DATABASE_URL:
DATABASE_URL=postgresql://analyst_ro:ПАРОЛЬ@хост.neon.tech/workshop_analytics?sslmode=require
Все. Нічого встановлювати й запускати не треба — Docker не потрібен.
Те саме, але база живе локально й належить тільки тобі.
Потрібен Docker Desktop — постав і запусти застосунок, він має працювати у фоні. Потім:
make setupДві-три хвилини: підніметься Postgres, згенеруються ті самі дані,
натренується модель. .env міняти не треба — він уже налаштований на цю базу.
Тільки для одного: підняти базу даних на твоєму комп'ютері. До самого MCP-сервера він стосунку не має — сервер це звичайна Python-програма, і Docker їй не потрібен.
Постав Docker, якщо хочеш:
- працювати без інтернету й після того, як спільна база перестане існувати;
- ламати дані без наслідків для інших — база твоя,
make resetповертає все; - побачити, як дані взагалі з'являються (
db/seed.pyстворює їх з нуля).
Не став, якщо тобі досить пройти воркшоп і подивитись, як це працює. Варіант А для цього повністю достатній.
Ніяк — вона вже є. Натренована модель лежить у репозиторії файлом
ml/model.pkl і приїжджає до тебе разом із git clone. Тренувати нічого не
треба в жодному з варіантів.
Так зроблено навмисно, і це окрема ідея, яку варто забрати з воркшопу: модель навчають заздалегідь, окремим кроком, і перевіряють якість перед тим, як віддати в роботу. Сервер моделей не навчає — він бере готову. Якби він навчав її на льоту, ти щоразу отримувала б трохи іншу модель, ніхто не встиг би перевірити її якість, а перший користувач чекав би.
Перетренувати можна будь-коли й теж без Docker — достатньо того самого рядка підключення:
make trainСкрипт порахує якість моделі й збереже її, лише якщо якість вища за поріг. Якщо ні — скаже про це й лишить попередню версію недоторканою.
make config-writeКоманда сама допише потрібне в налаштування Claude Desktop — з правильними шляхами саме для твого комп'ютера, зберігши решту налаштувань і зробивши резервну копію.
Хочеш побачити, що саме буде додано, — make config покаже текст і нічого
не змінить.
Claude Desktop не підключається до сервера за адресою: він запускає його сам. Тому в налаштуваннях вказується не посилання, а команда запуску — і шляхи в ній мають бути абсолютними.
Після цього повністю вийди з Claude Desktop і запусти знову:
- macOS —
Cmd+Q, не просто закрити вікно - Windows — вийти через іконку в треї
Конфігурація читається лише при старті застосунку.
Відкрий новий чат у Claude і спитай:
Що є в цій базі?
Claude має перелічити сім таблиць і коротко описати, що це за сервіс. Якщо так — готово, агент працює.
Не вийшло — docs/TROUBLESHOOTING.md, там розібрані причини в порядку від найчастішої.
Питання, на яких добре видно, як агент працює:
Скільки уроків ми провели минулого місяця?
Побудуй графік проведених уроків по місяцях за останній рік
Збережи цей звіт файлом
Хто з учнів у зоні ризику і що в них спільного?
Розгорни виклики інструментів у відповіді Claude — там видно ланцюжок: спершу він подивився список таблиць, потім прочитав структуру потрібної, потім написав SQL. Цей порядок ніхто не програмував, модель обрала його сама.
Claude Desktop
│ MCP: локально через stdio, у хмарі через HTTP
▼
MCP-сервер (Python)
├── server/main.py реєстрація інструментів, вибір транспорту
├── server/db.py підключення, захист SQL, зрозумілі помилки
├── server/tools/ власне інструменти
└── server/features.py ознаки ML-моделі
▼
PostgreSQL
Три речі, на які варто звернути увагу в коді:
Опис інструмента для моделі — це його docstring. Не назва функції й не
назва файлу. Claude читає текст під def і з нього розуміє, що робить
інструмент і коли його викликати. Зміниш docstring — зміниться поведінка.
Знання про дані живуть у самій базі. Пояснення на кшталт «ось цей статус
означає скасований урок, не рахуй його» записані як коментарі до колонок
(COMMENT ON COLUMN), а describe_table віддає їх моделі. Не в промпті, не в
коді — поруч із даними.
Різниця між локальним запуском і сервісом для команди — одна змінна.
Локально Claude Desktop сам запускає сервер як дочірній процес і говорить із
ним через stdin/stdout. У хмарі сервер слухає HTTP-порт. Код інструментів
однаковий, перемикає це MCP_TRANSPORT.
Сервер ходить у базу під користувачем, який має право лише читати. Це не перевірка в коді, а права на рівні Postgres: навіть якщо запит якось пролізе повз усі перевірки, база його відхилить.
Переконатись самому:
python scripts/prove_readonly.pyСкрипт іде в базу напряму, повз увесь код сервера, і намагається видалити таблицю, стерти дані й підчистити журнал. Усе отримує відмову; читання проходить.
Кожен виклик пишеться в таблицю audit_log — і успішний, і невдалий. Агент
має право туди тільки додавати: журнал, який можна підчистити, журналом не є.
Поки сервер живе на твоєму комп'ютері, ним користуєшся тільки ти. Щоб колеги могли просто додати посилання й нічого не встановлювати — docs/DEPLOY.md.
make doctor # перевірити, чи все готове до роботи
make config-write # вписати налаштування в Claude Desktop
make train # натренувати модель заново
make run # запустити сервер вручну, щоб побачити помилки
make test # прогнати тести
make setup # підняти свою базу в Docker і підготувати все з нуля
make reset # знести локальну базу й зібрати зановоУ Windows цієї команди зазвичай немає, і це нормально: кожна з них — просто короткий запис звичайної команди Python.
| Замість | Виконай |
|---|---|
make doctor |
python scripts/doctor.py |
make config |
python scripts/print_config.py |
make config-write |
python scripts/print_config.py --write |
make train |
python ml/train.py |
make seed |
python db/seed.py |
make run |
python -m server.main |
make test |
python -m pytest -q |
make setup окремої заміни не має, бо це кілька команд поспіль:
docker compose up -d, далі python db/seed.py, далі python ml/train.py.
main — повне рішення.
workshop-start — каркас, який ми заповнюємо разом на воркшопі: там навмисно
не написані ті функції, які набираємо в кадрі. Якщо відстанеш —
git checkout main повертає робочий стан. Деталі:
docs/WORKSHOP-START.md.
- docs/SETUP.md — установка з нуля, з перевірками
- docs/TROUBLESHOOTING.md — якщо не працює
- docs/DEPLOY.md — винести сервер у хмару
- docs/NEXT-STEPS.md — як застосувати це до своїх даних
- deploy/AUTH.md — що зробити перед підключенням до справжньої робочої бази