Structly MCP Server

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

Сервер — отдельный процесс, который общается со 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 (или любой pip-окружение)
• Запущенный бэкенд Structly
• API-токен Structly из раздела «Интеграции»

---

Установка

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

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

npx -y structly-mcp

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

cd mcp_visualdb
uv sync
cp .env.example .env

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

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

Запуск

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

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 и др.)

uv run structly-mcp --transport stdio

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

uv run python -m mcp_visualdb

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

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

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

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

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

---

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

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

---

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

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

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

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

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

{
  "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 — внести изменения в схему по описанию

---

Тесты

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