MCP MS SQL Server

mcp-mssql-server

Un servidor de Model Context Protocol (MCP) que proporciona una interfaz estandarizada para que los modelos de IA interactúen con bases de datos MS SQL Server. Este servidor implementa la especificación MCP para permitir operaciones de base de datos sin interrupciones a través de una API consistente.

Características

• Ejecutar consultas SQL con soporte de parámetros
• Listar todas las tablas de la base de datos
• Describir esquemas de tablas
• Soporte para modos de transporte stdio y HTTP
• Sistema de registro (logging) integral
• Configuración basada en variables de entorno
• Manejo de errores y apagado elegante

Requisitos previos

• Node.js (versión que soporte módulos ES)
• Instancia de MS SQL Server
• Credenciales de acceso para la base de datos

Instalación

1. Clonar el repositorio
2. Instalar las dependencias:

npm install

También puedes instalar el paquete de forma global:

npm install -g mcp-mssql-server

3. Crear un archivo .env en la raíz del proyecto con las siguientes variables requeridas:

DB_SERVER=your_server_address
DB_USER=your_username
DB_PASSWORD=your_password
DB_DATABASE_NAME=your_database_name

Uso

El servidor se puede iniciar en dos modos de transporte diferentes:

Modo stdio (predeterminado)

npm start
# or
npm run start:stdio

Modo HTTP

npm run start:http

Modo de desarrollo

npm run dev

Protocolo JSON-RPC

El servidor implementa el protocolo JSON-RPC 2.0 con los siguientes métodos clave:

1. initialize - Inicializar la conexión del servidor:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "clientInfo": {
      "name": "your-client",
      "version": "1.0.0"
    }
  }
}

2. tools/list - Listar las herramientas disponibles
3. tools/call - Llamar a una herramienta específica

Pruebas

El paquete incluye un cliente de prueba (test.package.js) que demuestra cómo interactuar con el servidor MCP:

node test.package.js

El cliente de prueba implementa una clase MCPTestClient que:

• Inicia un proceso del servidor usando npx mcp-mssql-server
• Inicializa la conexión con la versión de protocolo '2024-11-05'
• Lista las herramientas disponibles
• Ejecuta consultas de ejemplo, incluyendo:
  • Listar todas las tablas
  • Ejecutar una consulta SQL específica para contar documentos
• Maneja las respuestas y errores del servidor a través de flujos stdio
• Incluye manejo adecuado de errores y limpieza de procesos

Ejemplo de consulta de prueba del cliente:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "execute_sql_query",
    "arguments": {
      "query": "SELECT COUNT(*) as document_count FROM document_new"
    }
  }
}

El cliente de prueba proporciona una forma sencilla de verificar la funcionalidad del servidor y puede servir como referencia para implementar tu propio cliente.

Herramientas disponibles

El servidor proporciona las siguientes herramientas MCP:

1. execute_sql_query

Ejecutar consultas SQL contra la base de datos con parametrización opcional.

{
  "query": "SELECT * FROM Users WHERE id = @userId",
  "parameters": [
    {
      "name": "userId",
      "type": "int",
      "value": 1
    }
  ]
}

2. list_tables

Listar todas las tablas disponibles en la base de datos conectada.

3. describe_table

Obtener información detallada del esquema de una tabla específica.

{
  "table_name": "Users"
}

Registro (Logging)

Los registros se almacenan en el directorio logs:

• error.log: Registros de nivel de error
• combined.log: Todos los registros

En modo HTTP, los registros también se muestran en la consola.

Dependencias

Dependencias principales:

• @modelcontextprotocol/sdk: ^1.13.0
• dotenv: ^16.4.5
• express: ^5.1.0
• mssql: ^11.0.1
• winston: ^3.11.0

Dependencias de desarrollo:

• axios: ^1.10.0

Licencia

MIT

Contribuciones

1. Haz un fork del repositorio
2. Crea tu rama de características
3. Realiza tus cambios
4. Haz push a la rama
5. Crea una nueva Pull Request