mcp-sql

CLI-инструмент / MCP-сервер для подключения к SQL Server через Model Context Protocol.

Собственность Isasoft SAS.

Установка зависимостей

bun install

Разработка

Запуск напрямую с помощью Bun (режим разработки):

bun run src/cli.ts --help

Сборка автономного исполняемого файла

Скомпилируйте в один нативный исполняемый файл без необходимости Bun/Node runtime на целевой машине:

bun run build:win        # dist/mcp-sql-win-x64.exe (Windows x64)

Скрипты кросс-компиляции также доступны (не запускались/не проверялись в рамках этой сборки, кроме build:linux, который был успешно кросс-скомпилирован на Windows; build:mac-x64 / build:mac-arm64 не проверялись на реальном оборудовании macOS):

bun run build:mac-x64    # dist/mcp-sql-macos-x64 (macOS Intel, cross-compiled, unverified)
bun run build:mac-arm64  # dist/mcp-sql-macos-arm64 (macOS Apple Silicon, cross-compiled, unverified)
bun run build:linux      # dist/mcp-sql-linux-x64 (Linux x64, cross-compiled)

Выходные бинарные файлы записываются в dist/.

Использование

После сборки (или через bun run src/cli.ts в режиме разработки) CLI предоставляет следующие подкоманды:

mcp-sql setup [name]  Interactively configure a SQL Server connection
                       (defaults to the name "default")
mcp-sql list           List configured connections and mark the active one
mcp-sql use <name>     Switch which configured connection is active
mcp-sql remove <name>  Remove a configured connection (and its credential)
mcp-sql run            Run mcp-sql in server mode (starts the MCP server)
mcp-sql discover        Detect installed AI clients (Claude Desktop, Cline, Roo
                        Code) and configure them to use mcp-sql

Несколько подключений

mcp-sql может хранить несколько именованных подключений к SQL Server одновременно, но только одно является активным в любой момент времени — именно его использует mcp-sql run (и, следовательно, любой подключённый AI-клиент). Если вы никогда не передаёте явное имя, всё работает точно так же, как раньше, под именем "default".

setup

mcp-sql setup          # configure (or reconfigure) the "default" connection
mcp-sql setup staging  # configure a connection named "staging"

Проводит вас через интерактивный мастер для настройки и сохранения данных/учётных данных подключения к SQL Server под указанным именем (default, если не указано). В конце спрашивает, должно ли это подключение стать активным (по умолчанию "да", если это первое настроенное вами подключение).

list

mcp-sql list

Выводит список имён всех настроенных подключений вместе с их хостом и базой данных (никогда не паролем), отмечая, какое из них активно. Выводит понятное сообщение (без сбоев), если ещё ничего не настроено.

use

mcp-sql use staging

Помечает указанное подключение как активное. Если имя не существует, выводит понятную ошибку вместе со списком известных имён подключений.

remove

mcp-sql remove staging

Удаляет настроенное подключение вместе с сохранёнными учётными данными. Отказывается удалять текущее активное подключение — сначала переключитесь на другое с помощью mcp-sql use <other-name>.

discover

mcp-sql discover           # detect clients and write/merge their MCP config
mcp-sql discover --dry-run # preview what would be written, without touching any files

Обнаруживает установленные AI-клиенты (Claude Desktop, Cline, Roo Code) и добавляет запись mcp-sql в файл конфигурации MCP каждого клиента, указывая на собственный путь этого исполняемого файла (command) с args: ["run"]. Существующее содержимое конфигурации и другие записи MCP-серверов сохраняются; резервная копия .bak предыдущего файла создаётся при каждой реальной (не пробной) инъекции.

run

mcp-sql run

Запускает mcp-sql в режиме MCP-сервера. Именно это вызывают AI-клиенты — обычно вам не нужно запускать это вручную; discover настраивает это за вас.

Постоянное место установки

discover вставляет абсолютный путь текущего исполняемого файла (process.execPath) в конфигурацию каждого клиента. Это означает, что скомпилированный .exe должен оставаться на месте после того, как вы запустили discover для него — если вы переместите или переименуете его позже, конфигурации клиентов будут указывать на файл, которого там больше нет.

Рекомендуется: оставьте скомпилированный исполняемый файл в

C:\Users\Wil\appisoft\mcp\dist\mcp-sql-win-x64.exe

именно там bun run build:win создаёт его, внутри этого стабильного каталога проекта.

Не перемещайте этот файл после запуска discover. Если вам всё же нужно переместить его, повторно запустите discover из нового расположения исполняемого файла (например, path\to\new\location\mcp-sql-win-x64.exe discover), чтобы обновить конфигурации клиентов.

Установка / Распространение

Релизы автоматически собираются конвейером Azure Pipelines, определённым в azure-pipelines.yml:

1. Отправьте тег, соответствующий v* (например, v1.0.0). Конвейер запускается по отправке тега (или может быть запущен вручную), устанавливает Bun, выполняет bun test и bunx tsc --noEmit как обязательные проверки, затем запускает все 4 скрипта bun run build:* на одном агенте windows-latest (Bun кросс-компилирует цели mac/linux из Windows; только build:win и build:linux были проверены запуском — сборки для mac являются best-effort/непроверенными на реальном оборудовании, см. примечание выше).

2. Контрольные суммы SHA256 для всех 4 бинарных файлов генерируются в dist/checksums.sha256.

3. Всё (4 бинарных файла, скрипты установки и файл контрольных сумм) публикуется как артефакт конвейера Azure DevOps с именем mcp-sql-release. Скачайте его с вкладки "Artifacts" запуска конвейера. (Закомментированный блок GitHubRelease@1 в конвейере показывает, как также публиковать в GitHub Release после настройки подключения к службе GitHub.)

Затем конечные пользователи устанавливают с помощью одного скрипта из загруженной папки mcp-sql-release:

# Windows
.\install.ps1

# macOS / Linux
./install.sh

Оба скрипта устанавливают бинарный файл, при необходимости запускают mcp-sql setup (интерактивный мастер учётных данных) и mcp-sql discover (настраивает Claude Desktop, Cline, Roo Code), и чётко сообщают, что собираются сделать, прежде чем касаться файлов конфигурации других приложений. Передайте -SkipSetup/-SkipDiscover (PowerShell) или --skip-setup/--skip-discover (bash), чтобы отказаться от автоматических шагов.

Папка /docs этого репозитория готова к публикации в качестве Wiki проекта в Azure DevOps (Project Settings -> Wikis -> Publish code as wiki -> этот репозиторий -> /docs). Включает руководство по установке в стиле "one-liner" (адаптированное для приватного фида Azure Artifacts) — см. docs/Installation.md.

В качестве альтернативы (или дополнительно), когда этот репозиторий будет жить на GitHub, ту же папку /docs можно опубликовать с помощью GitHub Pages: включите Settings -> Pages -> Source: "GitHub Actions" (один раз), и workflow .github/workflows/pages.yml автоматически собирает и разворачивает docs/ (через Jekyll) при каждом push в main, затрагивающем docs/**.

Атрибуция

"Propiedad de Isasoft SAS" выводится как часть вывода mcp-sql --help.