pg-aiguide — MCP-сервер, который учит AI писать правильный PostgreSQL

## В чём проблема

AI-инструменты обучены на огромном количестве кода, включая Postgres. Но обучающие данные — это срез прошлого, а PostgreSQL активно развивается. Без дополнительного контекста агент:

• использует устаревшие паттерны (SERIAL вместо GENERATED ALWAYS AS IDENTITY)
• пропускает ограничения и индексы, которые очевидны любому опытному DBA
• не знает о NULLS NOT DISTINCT, частичных индексах, современных типах данных
• игнорирует лучшие практики именования и документирования схемы

Это не ошибки — это пробел в знаниях, который pg-aiguide закрывает.

## Как это работает

pg-aiguide предоставляет агенту два типа инструментов:

search_docs — семантический + keyword (BM25) поиск по официальной документации PostgreSQL с привязкой к версии. Агент может спросить «как работает LATERAL join в PG17» и получить точный ответ из официального мануала, а не из случайного StackOverflow.

Поиск работает по трём источникам:

• postgres — официальная документация PostgreSQL (с указанием версии)
• tiger — документация TimescaleDB и экосистемы TigerData
• postgis — документация расширения PostGIS

view_skill — набор курируемых опinionated-практик, которые агент применяет автоматически. Это не просто советы — это конкретные паттерны по проектированию схем, индексированию, типам данных, ограничениям, именованию и настройке производительности.

Вся инфраструктура уже поднята Timescale: публичный MCP-сервер доступен на https://mcp.tigerdata.com/docs, устанавливать и поддерживать ничего не нужно.

## ## Реальный пример: разница на практике

Команда Timescale провела честное сравнение: попросили Claude Code создать схему для e-commerce сайта дважды — без pg-aiguide и с ним. Результаты:

Это не подготовленный демо-пример — это стандартная разница при работе с реальными задачами.

## Установка

### Claude Code (плагин)

Самый полный режим — плагин использует и MCP-сервер, и встроенный механизм скиллов Claude Code:

claude plugin marketplace add timescale/pg-aiguide
claude plugin install pg@aiguide

### Cursor

Один клик через кнопку в README, или вручную добавить в .cursor/mcp.json:

{
  "mcpServers": {
    "pg-aiguide": {
      "url": "https://mcp.tigerdata.com/docs"
    }
  }
}

### Codex (OpenAI)

codex mcp add --url "https://mcp.tigerdata.com/docs" pg-aiguide

### VS Code

code --add-mcp '{"name":"pg-aiguide","type":"http","url":"https://mcp.tigerdata.com/docs"}'

### Gemini CLI

gemini mcp add -s user pg-aiguide "https://mcp.tigerdata.com/docs" -t http

### Windsurf

Добавить в ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "pg-aiguide": {
      "serverUrl": "https://mcp.tigerdata.com/docs"
    }
  }
}

### Универсальный JSON-конфиг (для любого MCP-клиента)

{
  "mcpServers": {
    "pg-aiguide": {
      "url": "https://mcp.tigerdata.com/docs"
    }
  }
}

## Первые запросы после установки

После подключения агент автоматически начнёт использовать документацию и скиллы. Несколько примеров задач, которые теперь дадут заметно лучший результат:

Простая схема:

Создай таблицу для хранения пользователей с уникальным email и именем пользователя.

Сложная схема с временными рядами:

Я разрабатываю систему мониторинга IoT-устройств на заводе. Устройства собирают
данные температуры, влажности и давления раз в секунду. Каждое устройство имеет
уникальный ID и название. Нужен эффективный поиск по последним данным конкретного
устройства и агрегация исторических данных за длительные периоды.

Оптимизация существующей схемы:

Проверь эту схему на соответствие лучшим практикам PostgreSQL 17 и предложи улучшения.

Агент получит из pg-aiguide актуальные паттерны и применит их сразу в ответе.

## Что внутри: структура проекта

Репозиторий устроен прозрачно — можно посмотреть, что именно агент получает как контекст:

skills/          # YAML-файлы со скиллами — опinionated практики по Postgres
rules/           # Правила для конкретных AI IDE (.cursor-plugin, .claude-plugin)
src/             # Код MCP-сервера (Python + TypeScript)
ingest/          # Пайплайн загрузки документации в векторную базу
migrations/      # SQL-миграции для собственного деплоя
docker/          # Docker-конфигурация для локального запуска

Файл skills.yaml — это «сердце» проекта. Именно оттуда агент берёт практики, которые применяет автоматически. Формат читаемый, и в него можно вносить вклад.

## Экосистемная документация

Помимо официального мануала PostgreSQL, pg-aiguide включает документацию расширений:

Уже доступно:

• TimescaleDB — гипертаблицы, политики сжатия, continuous aggregates, time_bucket
• PostGIS — пространственные типы данных, индексы, геометрические функции

Скоро:

• pgvector — векторные операции, индексы HNSW и IVFFlat

Расширения — это именно то место, где AI чаще всего генерирует неправильный код, потому что их документация слабее представлена в обучающих данных.

## Локальный запуск (для разработки и кастомизации)

Если хотите добавить собственные скиллы или подключить другую документацию:

git clone https://github.com/timescale/pg-aiguide
cd pg-aiguide

# Запуск через Docker Compose (PostgreSQL + MCP-сервер)
docker compose up -d

# Или установить зависимости напрямую (Bun)
bun install
bun run dev

Для добавления новых скиллов достаточно добавить YAML-файл в папку skills/ — формат задокументирован в DEVELOPMENT.md. Это самый ценный способ сконтрибьютить в проект.

## Почему это важно для вайбкодера

MCP-серверы с доменной документацией — это один из наиболее практичных паттернов для повышения качества AI-генерированного кода прямо сейчас. pg-aiguide показывает, как это работает на конкретном примере:

• не нужно каждый раз вставлять в промпт «используй PG17, добавь индексы, следуй лучшим практикам»
• агент сам находит нужный раздел документации под конкретный вопрос
• опционированные скиллы убирают неоднозначность там, где у Postgres есть несколько рабочих способов сделать одно и то же

Тот же подход можно применить к любой библиотеке или фреймворку — pg-aiguide это хорошо работающий шаблон, а не только инструмент для PostgreSQL.

## Заключение

pg-aiguide — бесплатный, публично доступный MCP-сервер от Timescale. Устанавливается одной командой или строчкой JSON, не требует своей инфраструктуры, работает с большинством популярных AI IDE.

Если вы используете PostgreSQL в проекте и работаете с Cursor, VS Code, Codex или Claude Code — подключение занимает меньше минуты и сразу повышает качество генерируемых схем и запросов.

Репозиторий: github.com/timescale/pg-aiguide MCP-эндпоинт: https://mcp.tigerdata.com/docs Лицензия: Apache 2.0