askDB MCP

MCP-сервер, который превращает вопросы о данных на естественном языке в контекст схемы, необходимый LLM для написания SQL. Он не подключается к вашей базе данных и сам не генерирует SQL — он извлекает нужные определения таблиц из вашего индекса Pinecone и передаёт их любой модели, которая задаёт вопрос (Claude Code, Claude Desktop, ChatGPT, Cursor).

user question
   │
   ▼
Claude Code / ChatGPT ──calls──► askDB MCP ──semantic search──► Pinecone (ask-db)
   │                                  │
   │      relevant DDL + guardrails ◄─┘
   ▼
generated SQL

Инструменты

Каждый ответ содержит инструкции, предписывающие модели использовать только возвращённые таблицы и столбцы, чтобы она не выдумывала имена.

Настройка

npm install
npm run setup             # creates .env from the template
#                          → then put your PINECONE_API_KEY in .env
npm run doctor            # verify connection, field mapping and retrieval quality

Делитесь этим с кем-то ещё? Отправьте им SETUP.md — в нём описан как локальный запуск, так и подключение к размещённому экземпляру.

npm run doctor — важный шаг. Он выводит конфигурацию индекса, поля метаданных, которые реально используют ваши записи, и пример поиска — так вы можете убедиться, что сервер читает правильные поля, прежде чем подключать его к клиенту.

npm run doctor       # connectivity + retrieval sanity check
npm run smoke        # drive the stdio server with a real MCP client
npm run smoke:http   # same over Streamable HTTP, with bearer auth

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

Claude Code

CLI, десктопное приложение и IDE-расширения используют одну конфигурацию, поэтому этот шаг регистрирует сервер сразу для всех трёх:

# from the repo root — records an absolute path, so it works in any folder
claude mcp add askdb --scope user -- node "$PWD\src\server.js"

Проверьте с помощью claude mcp list (askdb: ... ✓ Connected), затем перезапустите десктопное приложение или окно IDE — MCP-серверы загружаются при запуске.

Пользовательская область выбрана намеренно: смысл в том, чтобы задавать вопросы о базе данных, работая в ваших других репозиториях. Проектный .mcp.json будет работать только при запуске Claude Code в корне этого репозитория, а определение askdb в обеих областях заставит Claude Code предупредить о дубликате.

Claude Desktop / Cursor

Добавьте в claude_desktop_config.json (или в MCP-настройки Cursor):

{
  "mcpServers": {
    "askdb": {
      "command": "node",
      "args": ["D:\\working-directory\\AI\\askDB-mcp\\src\\server.js"]
    }
  }
}

Учётные данные берутся из .env рядом с сервером, поэтому в конфигурации клиента не появляются ключи.

ChatGPT

Коннекторы ChatGPT не могут запускать локальный процесс — они работают только через удалённый MCP по HTTP. Запустите HTTP-транспорт и откройте к нему доступ:

# set MCP_AUTH_TOKEN first: this endpoint serves your whole schema
MCP_AUTH_TOKEN=some-long-random-string npm run start:http

Затем укажите коннектору https://<your-host>/mcp с заголовком Authorization: Bearer <token>. Для быстрой проверки используйте туннель (cloudflared tunnel --url http://localhost:3000); для долгосрочного использования разместите его как следует — DEPLOY.md описывает Netlify целиком. GET /health не требует аутентификации для проверок балансировщика нагрузки; /mcp требует bearer-токен всегда, когда задан MCP_AUTH_TOKEN.

HTTP-транспорт не сохраняет состояние — один экземпляр сервера на запрос, — поэтому он масштабируется за балансировщиком нагрузки без липких сессий.

Размещение

Разворачивается в виде двух функций Netlify — netlify.toml содержит настройки сборки, так что импорт репозитория и установка PINECONE_API_KEY + MCP_AUTH_TOKEN — это вся работа. Пошагово: DEPLOY.md.

Это работает без переписывания транспорта, потому что WebStandardStreamableHTTPServerTransport из MCP SDK принимает Request и возвращает Response — сигнатура Netlify Functions v2, — поэтому netlify/functions/mcp.mjs импортирует src/mcp.js без изменений. Тот же файл подходит для Cloudflare Workers, Deno или Bun; src/http.js покрывает контейнеры и виртуальные машины.

GET /health не требует токена и сообщает, попали ли требуемые переменные окружения (только наличие, никогда значения) — бессерверная замена чтения лога запуска. /mcp закрыт по умолчанию: без установленного MCP_AUTH_TOKEN он возвращает 503, а не отдаёт вашу схему в интернет.

Когда сервер развёрнут, коллегам не нужно ничего устанавливать — достаточно URL и токена (SETUP.md, Route A).

Конфигурация

Всё опционально, кроме API-ключа. Смотрите .env.example.

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

Два момента, которые стоит знать

Модель эмбеддингов должна совпадать. Если EMBED_MODEL — не та модель, которой была загружена схема, все оценки падают почти до нуля, а результаты превращаются в шум — векторы фактически случайны относительно друг друга. npm run doctor покажет это как несвязанные таблицы с оценками около 0.01 вместо 0.8. Этот индекс был построен с помощью multilingual-e5-large.

Задайте DEFAULT_DATABASE, если ваш индекс содержит несколько окружений. Когда одна и та же схема существует как *_live и *_test, поиск без ограничений возвращает обе копии каждой таблицы, расходуя половину слотов top_k на дубликатах и позволяя модели смешивать окружения в одном запросе.

Структура файлов