# Dashboard MCP

MCP-коннектор + read-only веб-вьювер для дашбордов, которые полностью
контролирует ИИ-агент. Поддерживает произвольное количество независимых
дашбордов — каждый со своим `slug`, файлом и URL `/d/<slug>`.

Живой сервис: https://dashboard.89-207-254-32.nip.io
- Список дашбордов: `/`
- Конкретный дашборд (read-only, автообновление каждые 5с): `/d/<slug>`
- JSON API (тоже read-only): `/api/dashboards`, `/api/dashboards/<slug>`
- MCP-эндпоинт (нужен OAuth): `/mcp`

## Как это устроено

- `mcp_app.py` — создаёт единственный `MCPServer`, с OAuth (если заданы
  `OAUTH_*` переменные) или без (для локальной разработки).
- `tools.py` — MCP-тулы (`@mcp.tool()`): `list_dashboards`, `create_dashboard`,
  `get_dashboard`, `update_dashboard_meta`, `delete_dashboard`, `add_widget`,
  `update_widget`, `remove_widget`, `reorder_widgets`, `replace_widgets`.
  Это то, чем агент управляет дашбордами. Защищены OAuth-ом на `/mcp`.
- `web.py` — публичные HTML-страницы и JSON API (`@mcp.custom_route`, по
  документации SDK **не требуют авторизации**) — сюда смотрят люди в браузере.
- `models.py` — pydantic-схемы виджетов: `text`, `list`, `stats`, `progress`,
  `chart`.
- `store.py` — файловое хранилище, один JSON на дашборд в `data/dashboards/`.

## Типы виджетов

```jsonc
{"type": "text", "title": "Заметка", "body": "..."}
{"type": "list", "title": "Задачи", "ordered": false, "items": [{"label": "...", "value": "...", "note": "..."}]}
{"type": "stats", "title": "Метрики", "items": [{"label": "MRR", "value": "128k", "unit": "₽", "delta": "+12%", "trend": "up"}]}
{"type": "progress", "title": "Прогресс", "items": [{"label": "Q3", "value": 62, "max": 100, "color": "#395b4b"}]}
{"type": "chart", "title": "Динамика", "chartType": "line", "labels": ["Пн","Вт"], "series": [{"name": "Заказы", "data": [3, 7]}]}
```

Общие поля: `title` (опционально), `size`: `sm|md|lg|full` (ширина в гриде).

## Локальный запуск

```bash
pip install -r requirements.txt
cp .env.example .env   # можно оставить OAUTH_* пустыми — сервер поднимется без auth
MCP_TRANSPORT=streamable-http python server.py
# либо просто `python server.py` для stdio (claude mcp add / MCP Inspector)
```

## Как подключить коннектор в Claude

1. На сервере создан статический OAuth-клиент (Client ID/Secret выданы отдельно).
2. В Claude: Settings → Connectors → Add custom connector.
   - URL: `https://dashboard.89-207-254-32.nip.io/mcp`
   - Client ID / Client Secret — как выданы при разворачивании.
3. После авторизации агенту становятся доступны тулы из `tools.py`.

## Деплой

Продовый сервер тянет этот репозиторий сам: `deploy/deploy.sh` запускается
по cron каждые 2 минуты, сравнивает локальный `HEAD` с `origin/main`, и если
есть новые коммиты — `git reset --hard` + `docker compose up -d --build` +
проверка `/healthz`. Просто `git push` в `main` — изменения на проде
подхватятся сами в течение ~2 минут.

_Last verified deploy: 2026-08-19T15:29:01Z_