# Structly MCP Server

MCP-сервер для **Structly** (VisualDB) — позволяет ИИ-агентам полноценно работать
с проектами, схемами, таблицами, колонками, связями, группами, Git-ветками,
SQL-импортом/экспортом и AI-генерацией схем через протокол [Model Context Protocol](https://modelcontextprotocol.io).

Сервер — отдельный процесс, который общается со Structly по REST API,
используя bearer-токен из раздела **«Интеграции»** продукта.

---

## Возможности

**Проекты** — список, создание, редактирование, удаление.

**Схемы** — список, создание, редактирование, удаление, коммит, анализ,
AI-генерация (`create` / `modify`), применение результата ИИ.

**Таблицы и колонки** — получение диаграммы схемы, создание/редактирование/удаление
таблиц, массовое обновление позиций, управление колонками (типы, PK, default).

**Группы и связи** — группы таблиц для визуальной организации, связи
(внешние ключи) с действиями при удалении/обновлении.

**SQL** — импорт DDL в схему, экспорт схемы в SQL.

**Git** — ветки, fork, коммиты, checkout, reset, merge, миграции, DAG коммитов,
ветка по умолчанию.

**Источники данных** — привязка проекта к Structly Agent, проверка подключения,
задачи синхронизации (sync-jobs).

---

## Требования

**Через `npx` (рекомендуется):**
- Node.js 18+ (npx)
- Запущенный бэкенд Structly
- API-токен Structly из раздела **«Интеграции»**

**Из исходников:**
- Python 3.12+
- [uv](https://docs.astral.sh/uv/) (или любой pip-окружение)
- Запущенный бэкенд Structly
- API-токен Structly из раздела **«Интеграции»**

---

## Установка

### Через `npx` (рекомендуется)

Ничего устанавливать не нужно — сервер собран в standalone-бинарник
(PyInstaller) и запускается из npm:

```bash
npx -y structly-mcp
```

### Из исходников

```bash
cd mcp_visualdb
uv sync
cp .env.example .env
```

Заполните `.env`:

```dotenv
STRUCTLY_API_TOKEN=<токен из «Интеграций»>
```

## Запуск

### Через `npx` (рекомендуется, без Python и uv)

```bash
npx -y structly-mcp --transport stdio
```

Параметры те же, что и у Python-версии (`--transport`, `--host`, `--port`).
Переменные окружения `STRUCTLY_API_URL` (по умолчанию `http://localhost:8000`)
и `STRUCTLY_API_TOKEN` задаются через `env` в конфиге MCP-клиента.

### Из исходников

#### stdio (для локальных агентов: Claude Code, opencode и др.)

```bash
uv run structly-mcp --transport stdio
```

Или через модуль:

```bash
uv run python -m mcp_visualdb
```

#### Streamable HTTP (для удалённых агентов)

```bash
uv run structly-mcp --transport streamable-http --host 0.0.0.0 --port 8765
```

MCP endpoint будет доступен по адресу `http://<host>:<port>/mcp`.

#### SSE (устаревший транспорт)

```bash
uv run structly-mcp --transport sse --host 0.0.0.0 --port 8765
```

---

## Сборка и публикация npm-пакета

- Сборка standalone-бинарника: [`build/README.md`](./build/README.md)
- npm-пакет: папка [`npm/`](./npm)
- Публикация: `cd npm && npm publish`
- Локальная проверка без публикации: `cd npm && npm link` → `npx structly-mcp`

---

## Подключение к агенту

### Через `npx` (рекомендуется)

Пример конфигурации MCP-сервера в клиенте (opencode / Claude Desktop):

```json
{
  "mcpServers": {
    "structly": {
      "command": "npx",
      "args": ["-y", "structly-mcp"],
      "env": {
        "STRUCTLY_API_TOKEN": "<ваш_токен>",
      }
    }
  }
}
```

### Из исходников (uv)

```json
{
  "mcpServers": {
    "structly": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "E:/project/PycharmProjects/mcp_visualdb",
        "structly-mcp"
      ],
      "env": {
        "STRUCTLY_API_TOKEN": "<ваш_токен>",
      }
    }
  }
}
```

> ⚠️ MCP-клиенты передают в subprocess только ограниченный набор переменных
> окружения, поэтому токен нужно передавать через `env` конфигурации клиента
> (в `.env` файле проекта он не подхватится при запуске через `npx`).

---

## Инструменты (47)

| Категория    | Инструменты                                                                                                                                                                                                 |
|--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Проекты      | `list_projects`, `create_project`, `edit_project`, `delete_project`                                                                                                                                         |
| Схемы        | `list_schemas`, `create_schema`, `edit_schema`, `delete_schema`, `commit_schema`, `analyze_schema`                                                                                                          |
| AI-схемы     | `ai_preview_schema`, `ai_get_preview`, `ai_apply_schema`                                                                                                                                                    |
| Диаграмма    | `get_diagram`, `export_schema_sql`                                                                                                                                                                          |
| Таблицы      | `create_table`, `edit_table`, `delete_table`, `batch_edit_tables`                                                                                                                                           |
| Колонки      | `create_column`, `edit_column`, `delete_column`                                                                                                                                                             |
| Группы       | `create_group`, `edit_group`, `delete_group`                                                                                                                                                                |
| Связи        | `create_relationship`, `edit_relationship`, `delete_relationship`                                                                                                                                           |
| SQL          | `import_sql_into_schema`                                                                                                                                                                                    |
| Git          | `list_branches`, `create_branch`, `fork_branch`, `commit_to_branch`, `checkout_branch`, `checkout_commit`, `reset_branch`, `merge_branches`, `get_branch_migration`, `get_commit_dag`, `set_default_branch` |
| Data sources | `get_data_source`, `set_data_source`, `delete_data_source`, `test_connection`, `list_sync_jobs`, `create_sync_job`, `get_sync_job`                                                                          |

## Ресурсы

- `structly://projects` — список проектов
- `structly://projects/{project_uuid}/schemas` — схемы проекта
- `structly://schemas/{schema_uuid}/diagram` — полная структура схемы

## Промпты

- `create_project` — создать проект по описанию
- `design_schema` — спроектировать схему по требованиям
- `modify_schema` — внести изменения в схему по описанию

---

## Тесты

```bash
uv run pytest
uv run ruff check src
```

## Структура проекта

```
src/mcp_visualdb/
├── __main__.py        # python -m mcp_visualdb
├── cli.py             # точка входа, выбор транспорта
├── config.py          # настройки из .env
├── client.py          # HTTP-клиент Structly API
├── server.py          # сборка MCPServer
├── utils.py           # утилиты (JSON-сериализация)
├── resources.py       # ресурсы MCP
├── prompts.py         # промпты MCP
└── tools/             # инструменты MCP
    ├── projects.py
    ├── schemas.py
    ├── tables.py
    ├── git.py
    ├── data_sources.py
    └── sql.py
```