# DaraCloud Metabase MCP

Демонстрационный MCP-сервер для аналитики синтетической IaaS-базы DaraCloud через API Metabase.

Проект создан для докладов и обучения. Все названия, сущности и данные вымышлены и не содержат информации реальной инфраструктуры.

## Архитектура

```text
Hermes / другой MCP-клиент
          |
          | Streamable HTTP + Bearer token
          v
DaraCloud Metabase MCP
          |
          | Metabase API + X-API-Key
          v
       Metabase
          |
          v
PostgreSQL / daracloud_demo
```

MCP-сервер не подключается к PostgreSQL напрямую и не хранит учетные данные базы данных.

## Инструменты MCP

- `list_tables` — список таблиц демонстрационной схемы.
- `describe_table` — колонки и типы данных выбранной таблицы.
- `run_sql` — один read-only запрос `SELECT` или `WITH ... SELECT`, результат ограничивается по числу строк.

Изменяющие SQL-команды запрещены дополнительной проверкой на уровне сервера. Для полноценной защиты подключенная к Metabase учетная запись базы данных также должна оставаться read-only.

## Быстрый запуск

Требования: Linux, Python 3.11+ и настроенный Metabase API key.

```bash
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env
```

Заполните `.env`, не добавляя его в Git, затем запустите:

```bash
set -a
. ./.env
set +a
.venv/bin/python src/server.py
```

По умолчанию сервер слушает `127.0.0.1:8000`, а MCP endpoint доступен по пути `/mcp`.

## Переменные окружения

| Переменная | Назначение |
|---|---|
| `METABASE_URL` | Базовый URL Metabase без завершающего `/` |
| `METABASE_API_KEY` | API key Metabase для выполнения запросов |
| `METABASE_DATABASE_ID` | Числовой ID базы в Metabase |
| `METABASE_SCHEMA` | Разрешенная схема, по умолчанию `daracloud_demo` |
| `MCP_AUTH_TOKEN` | Отдельный bearer token для входящих MCP-запросов |
| `MCP_PUBLIC_URL` | Публичный HTTPS URL MCP-сервера |
| `MCP_HOST` | Локальный адрес прослушивания |
| `MCP_PORT` | Локальный порт прослушивания |
| `QUERY_TIMEOUT_SECONDS` | Таймаут запроса к Metabase |
| `MAX_ALLOWED_ROWS` | Максимально допустимый лимит результата |

## Развертывание

В каталоге `deploy` находятся примеры unit-файла systemd и конфигурации Caddy. Перед использованием замените домены и при необходимости пути.

Для Hermes пример подключения находится в [`examples/hermes-config.yaml`](examples/hermes-config.yaml).

## Демонстрационные данные

Схема и дамп синтетической базы: [kosovadaria/daracloud-demo](https://github.com/kosovadaria/daracloud-demo).

## Безопасность

- Не коммитьте `.env`, API keys и bearer tokens.
- Используйте разные секреты для Metabase API и входящей MCP-аутентификации.
- Публикуйте сервер только через HTTPS reverse proxy.
- Оставляйте пользователя базы данных в Metabase с правами только на чтение.
- Это учебный проект, а не универсальный SQL firewall для недоверенных пользователей.

## Лицензия

MIT.