mcp-sql

Herramienta CLI / servidor MCP para conectarse a SQL Server mediante el Protocolo de Contexto de Modelo.

Propiedad de Isasoft SAS.

Instalar dependencias

bun install

Desarrollo

Ejecutar directamente con Bun (modo de desarrollo):

bun run src/cli.ts --help

Compilación de un ejecutable independiente

Compilar a un único ejecutable nativo sin necesidad de runtime de Bun/Node en la máquina de destino:

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

También hay disponibles scripts de compilación cruzada (no ejecutados/verificados como parte de esta compilación, excepto build:linux que se compiló correctamente de forma cruzada en Windows; build:mac-x64 / build:mac-arm64 no se han verificado en hardware macOS real):

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)

Los binarios de salida se escriben en dist/.

Uso

Una vez compilado (o mediante bun run src/cli.ts en modo de desarrollo), la CLI expone estos subcomandos:

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

Múltiples conexiones

mcp-sql puede almacenar más de una conexión SQL Server con nombre a la vez, pero solo una está activa en un momento dado — esa es la que usa mcp-sql run (y por tanto cualquier cliente de IA conectado). Si nunca pasas un nombre explícito, todo se comporta exactamente igual que antes bajo el nombre "default".

setup

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

Te guía a través de un asistente interactivo para configurar y almacenar los detalles/credenciales de la conexión SQL Server bajo el nombre dado (default si se omite). Al final pregunta si esta conexión debe convertirse en la activa (por defecto "sí" si es la primera conexión que has configurado).

list

mcp-sql list

Enumera los nombres de todas las conexiones configuradas junto con su host y base de datos (nunca la contraseña), marcando cuál está activa. Imprime un mensaje limpio (sin fallos) si aún no hay ninguna configurada.

use

mcp-sql use staging

Marca la conexión dada como activa. Si el nombre no existe, imprime un error claro junto con la lista de nombres de conexión conocidos.

remove

mcp-sql remove staging

Elimina una conexión configurada junto con su credencial almacenada. Se niega a eliminar la conexión actualmente activa — cambia primero a otra con 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

Detecta los clientes de IA instalados (Claude Desktop, Cline, Roo Code) e inyecta una entrada mcp-sql en el archivo de configuración MCP de cada cliente, apuntando a la ruta propia de este ejecutable (command) con args: ["run"]. El contenido de configuración existente y otras entradas de servidor MCP se conservan; se escribe una copia de seguridad .bak del archivo anterior en cada inyección real (no de prueba).

run

mcp-sql run

Inicia mcp-sql en modo servidor MCP. Esto es lo que invocan los clientes de IA — normalmente no ejecutas esto manualmente; discover lo configura por ti.

Ubicación de instalación permanente

discover inyecta la ruta absoluta del ejecutable actualmente en ejecución (process.execPath) en la configuración de cada cliente. Eso significa que el .exe compilado debe permanecer en su lugar una vez que hayas ejecutado discover contra él — si lo mueves o renombras después, las configuraciones de los clientes apuntarán a un archivo que ya no existe allí.

Recomendado: deja el ejecutable compilado en

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

que es donde bun run build:win lo produce, dentro de este directorio de proyecto estable.

No muevas este archivo después de ejecutar discover. Si necesitas moverlo, vuelve a ejecutar discover desde la nueva ubicación del ejecutable después (p. ej. path\to\new\location\mcp-sql-win-x64.exe discover) para actualizar las configuraciones de los clientes en consecuencia.

Instalación / Distribución

Las versiones se compilan automáticamente mediante la canalización de Azure Pipelines definida en azure-pipelines.yml:

1. Haz push de una etiqueta que coincida con v* (p. ej. v1.0.0). La canalización se activa con el push de la etiqueta (o se puede ejecutar manualmente), instala Bun, ejecuta bun test y bunx tsc --noEmit como comprobaciones obligatorias, y luego ejecuta los 4 scripts bun run build:* en un único agente windows-latest (Bun compila de forma cruzada los objetivos mac/linux desde Windows; solo build:win y build:linux se han verificado con ejecución hasta ahora — las compilaciones mac son de mejor esfuerzo/no verificadas en hardware real, ver la nota anterior).

2. Se generan las sumas de verificación SHA256 de los 4 binarios en dist/checksums.sha256.

3. Todo (los 4 binarios, los scripts de instalación y el archivo de sumas de verificación) se publica como un artefacto de canalización de Azure DevOps llamado mcp-sql-release. Descárgalo desde la pestaña "Artifacts" de la ejecución de la canalización. (Un bloque GitHubRelease@1 comentado en la canalización muestra cómo publicar también en una GitHub Release una vez que se configure una conexión de servicio de GitHub.)

Los usuarios finales instalan entonces con un único script desde dentro de la carpeta mcp-sql-release descargada:

# Windows
.\install.ps1

# macOS / Linux
./install.sh

Ambos scripts instalan el binario, ejecutan opcionalmente mcp-sql setup (asistente interactivo de credenciales) y mcp-sql discover (configura Claude Desktop, Cline, Roo Code), e imprimen claramente lo que van a hacer antes de tocar los archivos de configuración de cualquier otra aplicación. Pasa -SkipSetup/-SkipDiscover (PowerShell) o --skip-setup/--skip-discover (bash) para optar por no realizar los pasos automáticos.

La carpeta /docs de este repo está lista para publicarse como la Wiki del proyecto en Azure DevOps (Project Settings -> Wikis -> Publish code as wiki -> este repo -> /docs). Incluye una guía de instalación estilo "one-liner" (adaptada para el feed privado de Azure Artifacts) — ver docs/Installation.md.

Alternativamente (o además), una vez que este repo viva en GitHub, la misma carpeta /docs se puede publicar con GitHub Pages: habilita Settings -> Pages -> Source: "GitHub Actions" (una sola vez), y el workflow .github/workflows/pages.yml construye y despliega docs/ automáticamente (vía Jekyll) en cada push a main que toque docs/**.

Atribución

"Propiedad de Isasoft SAS" se imprime como parte de la salida de mcp-sql --help.