Servidor MCP de SingleStore

Un servidor de Protocolo de Contexto de Modelo (MCP) para interactuar con bases de datos SingleStore. Este servidor proporciona herramientas para consultar tablas, describir esquemas y generar diagramas ER.

Características

Listar todas las tablas en la base de datos
Ejecutar consultas SQL personalizadas
Obtenga información detallada de la tabla, incluido el esquema y los datos de muestra
Generar diagramas ER de sirena del esquema de base de datos
Compatibilidad con SSL con obtención automática de paquetes de CA
Manejo adecuado de errores y seguridad de tipos en TypeScript

Prerrequisitos

Node.js 16 o superior
npm o hilo
Acceso a una base de datos SingleStore
Paquete CA de SingleStore (obtenido automáticamente del portal)

Instalación

Instalación mediante herrería

Para instalar SingleStore MCP Server para Claude Desktop automáticamente a través de Smithery :

npx -y @smithery/cli install @madhukarkumar/singlestore-mcp-server --client claude

Clonar el repositorio:

git clone <repository-url>
cd mcp-server-singlestore

Instalar dependencias:

npm install

Construir el servidor:

npm run build

Variables de entorno

Variables de entorno requeridas

El servidor requiere las siguientes variables de entorno para la conexión a la base de datos:

SINGLESTORE_HOST=your-host.singlestore.com
SINGLESTORE_PORT=3306
SINGLESTORE_USER=your-username
SINGLESTORE_PASSWORD=your-password
SINGLESTORE_DATABASE=your-database

Todas estas variables de entorno son necesarias para que el servidor establezca una conexión con su base de datos de SingleStore. La conexión utiliza SSL con el paquete de CA de SingleStore, que se obtiene automáticamente del portal de SingleStore.

Variables de entorno opcionales

Para compatibilidad con el protocolo SSE (eventos enviados por el servidor):

SSE_ENABLED=true       # Enable the SSE HTTP server (default: false if not set)
SSE_PORT=3333          # HTTP port for the SSE server (default: 3333 if not set)

Configuración de variables de entorno

En su shell : configure las variables en su terminal antes de ejecutar el servidor:
export SINGLESTORE_HOST=your-host.singlestore.com export SINGLESTORE_PORT=3306 export SINGLESTORE_USER=your-username export SINGLESTORE_PASSWORD=your-password export SINGLESTORE_DATABASE=your-database
En los archivos de configuración del cliente : agregue las variables a su archivo de configuración del cliente MCP como se muestra en las secciones de integración a continuación.

Uso

Soporte de protocolo

Este servidor admite dos protocolos para la integración de clientes:

Protocolo MCP : el protocolo de contexto de modelo estándar que utiliza la comunicación stdio, utilizado por Claude Desktop, Windsurf y Cursor.
Protocolo SSE : eventos enviados por el servidor a través de HTTP para clientes y aplicaciones basados en web que necesitan transmisión de datos en tiempo real.

Ambos protocolos exponen las mismas herramientas y funcionalidades, lo que le permite elegir el mejor método de integración para su caso de uso.

Herramientas disponibles

listas_de_tablas
- Enumera todas las tablas de la base de datos
- No se requieren parámetros GXP8
tabla de consulta
- Ejecuta una consulta SQL personalizada
- Parámetros:
  - consulta: cadena de consulta SQL GXP9
describe_tabla
- Obtiene información detallada sobre una tabla
- Parámetros:
  - tabla: Nombre de la tabla GXP10
generar_diagrama_er
- Genera un diagrama ER de sirena del esquema de la base de datos
- No se requieren parámetros GXP11
ejecutar_lectura_consulta
- Ejecuta una consulta de solo lectura (SELECT) en la base de datos
- Parámetros:
  - consulta: consulta SQL SELECT para ejecutar GXP12
crear_tabla
- Crear una nueva tabla en la base de datos con columnas y restricciones específicas
- Parámetros:
  - table_name: Nombre de la tabla a crear
  - columnas: Matriz de definiciones de columnas
  - table_options: Configuración de tabla opcional GXP13
generar_datos_sintéticos
- Generar e insertar datos sintéticos en una tabla existente
- Parámetros:
  - tabla: Nombre de la tabla en la que se insertarán los datos
  - count: Número de filas a generar (predeterminado: 100)
  - column_generators: generadores personalizados para columnas específicas
  - batch_size: Número de filas a insertar en cada lote (predeterminado: 1000) GXP14
optimizar_sql
- Analizar una consulta SQL utilizando PROFILE y proporcionar recomendaciones de optimización
- Parámetros:
  - consulta: Consulta SQL para analizar y optimizar GXP15
- La respuesta incluye:
  - Consulta original
  - Resumen del perfil de rendimiento (tiempo total de ejecución, tiempo de compilación, tiempo de ejecución)
  - Lista de cuellos de botella detectados
  - Recomendaciones de optimización con niveles de impacto (alto/medio/bajo)
  - Sugerencias para índices, uniones, uso de memoria y otras optimizaciones

Ejecución independiente

Construir el servidor:

npm run build

Ejecute el servidor solo con el protocolo MCP:

node build/index.js

Ejecute el servidor con los protocolos MCP y SSE:

SSE_ENABLED=true SSE_PORT=3333 node build/index.js

Uso del protocolo SSE

Cuando SSE está habilitado, el servidor expone los siguientes puntos finales HTTP:

Punto final raíz
GET /
Devuelve información del servidor y los puntos finales disponibles.
Chequeo de salud
GET /health
Devuelve información de estado sobre el servidor.
Conexión SSE
GET /sse
Establece una conexión de eventos enviados por el servidor para actualizaciones en tiempo real.
Herramientas de lista
GET /tools
Devuelve una lista de todas las herramientas disponibles, igual que la funcionalidad list_tools de MCP.También admite solicitudes POST para compatibilidad con MCP Inspector:
POST /tools Content-Type: application/json { "jsonrpc": "2.0", "id": "request-id", "method": "mcp.list_tools", "params": {} }
Herramienta de llamada
POST /call-tool Content-Type: application/json { "name": "tool_name", "arguments": { "param1": "value1", "param2": "value2" }, "client_id": "optional_sse_client_id_for_streaming_response" }
Ejecuta una herramienta con los argumentos proporcionados.
- Si se proporciona client_id , la respuesta se transmite a ese cliente SSE.
- Si se omite client_id , la respuesta se devuelve directamente en la respuesta HTTP.
También admite el formato MCP estándar para compatibilidad con MCP Inspector:
POST /call-tool Content-Type: application/json { "jsonrpc": "2.0", "id": "request-id", "method": "mcp.call_tool", "params": { "name": "tool_name", "arguments": { "param1": "value1", "param2": "value2" }, "_meta": { "client_id": "optional_sse_client_id_for_streaming_response" } } }

Tipos de eventos de SSE

Al utilizar conexiones SSE, el servidor envía los siguientes tipos de eventos:

mensaje (evento sin nombre): se envía cuando se establece correctamente una conexión SSE.
abierto : Evento de conexión adicional establecida.
mensaje : se utiliza para todos los mensajes del protocolo MCP, incluidos eventos de inicio de herramienta, resultado y error.

Todos los eventos siguen el formato JSON-RPC 2.0 del protocolo MCP. El sistema utiliza el tipo de evento message estándar para garantizar la compatibilidad con el Inspector de MCP y la mayoría de las bibliotecas cliente de SSE.

Ejemplo de cliente JavaScript

// Connect to SSE endpoint
const eventSource = new EventSource('http://localhost:3333/sse');
let clientId = null;

// Handle connection establishment via unnamed event
eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'connection_established') {
    clientId = data.clientId;
    console.log(`Connected with client ID: ${clientId}`);
  }
};

// Handle open event
eventSource.addEventListener('open', (event) => {
  console.log('SSE connection opened via open event');
});

// Handle all MCP messages
eventSource.addEventListener('message', (event) => {
  const data = JSON.parse(event.data);
  
  if (data.jsonrpc === '2.0') {
    if (data.result) {
      console.log('Tool result:', data.result);
    } else if (data.error) {
      console.error('Tool error:', data.error);
    } else if (data.method === 'mcp.call_tool.update') {
      console.log('Tool update:', data.params);
    }
  }
});

// Call a tool with streaming response (custom format)
async function callTool(name, args) {
  const response = await fetch('http://localhost:3333/call-tool', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: name,
      arguments: args,
      client_id: clientId
    })
  });
  return response.json();
}

// Call a tool with streaming response (MCP format)
async function callToolMcp(name, args) {
  const response = await fetch('http://localhost:3333/call-tool', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 'request-' + Date.now(),
      method: 'mcp.call_tool',
      params: {
        name: name,
        arguments: args,
        _meta: {
          client_id: clientId
        }
      }
    })
  });
  return response.json();
}

// Example usage
callTool('list_tables', {})
  .then(response => console.log('Request accepted:', response));

Uso con MCP Inspector

El Inspector MCP es una herramienta basada en navegador para probar y depurar servidores MCP. Para usarlo con este servidor:

Inicie el servidor y el inspector MCP con un solo comando:
npm run inspector
O iniciar solo el servidor con:
npm run start:inspector
Para instalar y ejecutar MCP Inspector por separado:
npx @modelcontextprotocol/inspector
El inspector se abrirá en su navegador predeterminado.
Cuando se abre el Inspector MCP:a. Introduzca la URL en el campo de conexión:
http://localhost:8081
Nota: El puerto real puede variar según la configuración. Consulte los registros de inicio del servidor para conocer el puerto utilizado. El servidor mostrará:
MCP SingleStore SSE server listening on port XXXX
b. Asegúrese de que "SSE" esté seleccionado como tipo de transporte.c. Haga clic en "Conectar".
Si tiene problemas de conexión, pruebe estas alternativas:a. Intente conectarse a un punto final específico:
http://localhost:8081/stream
b. Intente usar la dirección IP real de su máquina:
http://192.168.1.x:8081
c. Si se ejecuta en Docker:
http://host.docker.internal:8081
Depuración de problemas de conexión :a. Verifique que el servidor esté en funcionamiento visitando http://localhost:8081 en su navegador.b. Verifique los registros del servidor para ver si hay intentos de conexión.c. Intente reiniciar tanto el servidor como el inspector.d. Asegúrese de que ningún otro servicio esté utilizando el puerto 8081e. Pruebe la conexión SSE con el script proporcionado:
npm run test:sse
O manualmente con curl:
curl -N http://localhost:8081/sse
f. Verifique que la configuración de su firewall permita conexiones al puerto 8081
Una vez conectado, el inspector mostrará todas las herramientas disponibles y le permitirá probarlas de forma interactiva.

⚠️ Nota : Al utilizar el Inspector MCP, debe utilizar la URL completa, incluido el prefijo http:// .

Integración de clientes MCP

Instalación en Claude Desktop

Agregue la configuración del servidor a su archivo de configuración de Claude Desktop ubicado en:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Ventanas: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "singlestore": {
      "command": "node",
      "args": ["path/to/mcp-server-singlestore/build/index.js"],
      "env": {
        "SINGLESTORE_HOST": "your-host.singlestore.com",
        "SINGLESTORE_PORT": "3306",
        "SINGLESTORE_USER": "your-username",
        "SINGLESTORE_PASSWORD": "your-password",
        "SINGLESTORE_DATABASE": "your-database",
        "SSE_ENABLED": "true",
        "SSE_PORT": "3333"
      }
    }
  }
}

Las variables SSE_ENABLED y SSE_PORT son opcionales. Inclúyalas si desea habilitar el servidor HTTP con compatibilidad con SSE junto con el protocolo MCP estándar.

Reiniciar la aplicación de escritorio Claude
En tu conversación con Claude, ahora puedes usar el servidor SingleStore MCP con:

use_mcp_tool({
  server_name: "singlestore",
  tool_name: "list_tables",
  arguments: {}
})

Instalación en Windsurf

Agregue la configuración del servidor a su archivo de configuración de Windsurf ubicado en:
- macOS: ~/Library/Application Support/Windsurf/config.json
- Ventanas: %APPDATA%\Windsurf\config.json

{
  "mcpServers": {
    "singlestore": {
      "command": "node",
      "args": ["path/to/mcp-server-singlestore/build/index.js"],
      "env": {
        "SINGLESTORE_HOST": "your-host.singlestore.com",
        "SINGLESTORE_PORT": "3306",
        "SINGLESTORE_USER": "your-username",
        "SINGLESTORE_PASSWORD": "your-password",
        "SINGLESTORE_DATABASE": "your-database",
        "SSE_ENABLED": "true",
        "SSE_PORT": "3333"
      }
    }
  }
}

Las variables SSE_ENABLED y SSE_PORT son opcionales, pero habilitan funcionalidad adicional a través del servidor HTTP SSE.

Reiniciar Windsurf
En su conversación con Claude en Windsurf, las herramientas MCP de SingleStore estarán disponibles automáticamente cuando Claude necesite acceder a la información de la base de datos.

Instalación en Cursor

Añade la configuración del servidor a la configuración del cursor:
- Cursor abierto
- Vaya a Configuración (icono de engranaje) > Extensiones > Claude AI > Servidores MCP
- Agregue un nuevo servidor MCP con la siguiente configuración:

{
  "singlestore": {
    "command": "node",
    "args": ["path/to/mcp-server-singlestore/build/index.js"],
    "env": {
      "SINGLESTORE_HOST": "your-host.singlestore.com",
      "SINGLESTORE_PORT": "3306",
      "SINGLESTORE_USER": "your-username",
      "SINGLESTORE_PASSWORD": "your-password",
      "SINGLESTORE_DATABASE": "your-database",
      "SSE_ENABLED": "true",
      "SSE_PORT": "3333"
    }
  }
}

Las variables SSE_ENABLED y SSE_PORT permiten que las aplicaciones web se conecten al servidor a través de HTTP y reciban actualizaciones en tiempo real a través de eventos enviados por el servidor.

Reiniciar cursor
Al utilizar Claude AI dentro de Cursor, las herramientas SingleStore MCP estarán disponibles para las operaciones de la base de datos.

Consideraciones de seguridad

Nunca envíe credenciales al control de versiones
Utilice variables de entorno o gestión de configuración segura
Considere utilizar un mecanismo de agrupación de conexiones para uso en producción
Implementar controles de acceso y permisos de usuario adecuados en SingleStore
Mantenga actualizado el paquete SingleStore CA

Desarrollo

Estructura del proyecto

mcp-server-singlestore/
├── src/
│   └── index.ts      # Main server implementation
├── package.json
├── tsconfig.json
├── README.md
└── CHANGELOG.md

Edificio

npm run build

Pruebas

npm test

Solución de problemas

Problemas de conexión
- Verifique las credenciales y la información del host en sus variables de entorno
- Comprobar la configuración de SSL
- Asegúrese de que la base de datos sea accesible desde su red
- Verifique la configuración de su firewall para permitir conexiones salientes a su base de datos SingleStore
Problemas de compilación
- Borrar node_modules y reinstalar las dependencias
- Verificar la configuración de TypeScript
- Comprobar la compatibilidad de la versión de Node.js (debe ser 16+)
Problemas de integración de MCP
- Verifique que la ruta al archivo build/index.js del servidor sea correcta en la configuración de su cliente
- Compruebe que todas las variables de entorno estén configuradas correctamente en la configuración de su cliente
- Reinicie su aplicación cliente después de realizar cambios de configuración
- Verifique los registros del cliente para ver si hay mensajes de error relacionados con el servidor MCP
- Intente ejecutar primero el servidor de forma independiente para validar que funciona fuera del cliente

Contribuyendo

Bifurcar el repositorio
Crear una rama de características
Confirme sus cambios
Empujar hacia la rama
Crear una solicitud de extracción

Licencia

Licencia MIT: consulte el archivo de LICENCIA para obtener más detalles

SingleStore MCP Server

Integrations