SingleStore MCP Server

Un servidor MCP para interactuar con bases de datos SingleStore, que requiere variables de entorno para la conexión.

GitHub
4
Prueba este MCPPatrocinado

Documentación

Servidor MCP de SingleStore

smithery badge

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
  • Obtener información detallada de tablas, incluyendo esquema y datos de muestra
  • Generar diagramas ER de Mermaid del esquema de la base de datos
  • Soporte SSL con obtención automática del paquete de certificados CA
  • Manejo adecuado de errores y seguridad de tipos en TypeScript

Requisitos previos

  • Node.js 16 o superior
  • npm o yarn
  • Acceso a una base de datos SingleStore
  • Paquete de certificados CA de SingleStore (obtenido automáticamente desde el portal)

Instalación

Instalación mediante Smithery

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

npx -y @smithery/cli install @madhukarkumar/singlestore-mcp-server --client claude
  1. Clonar el repositorio:
git clone <repository-url>
cd mcp-server-singlestore
  1. Instalar dependencias:
npm install
  1. Compilar 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 SingleStore. La conexión utiliza SSL con el paquete de certificados CA de SingleStore, que se obtiene automáticamente desde el portal de SingleStore.

Variables de entorno opcionales

Para soporte del 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

  1. En su terminal: Establezca 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

  2. En 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 protocolos

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

  1. Protocolo MCP: El Protocolo de Contexto de Modelo estándar que utiliza comunicación stdio, utilizado por Claude Desktop, Windsurf y Cursor.
  2. Protocolo SSE: Eventos Enviados por el Servidor sobre HTTP para clientes basados en web y aplicaciones 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

  1. list_tables

    • Lista todas las tablas en la base de datos
    • No requiere parámetros
    use_mcp_tool({
  server_name: "singlestore",
  tool_name: "list_tables",
  arguments: {}
})

  2. query_table

    • Ejecuta una consulta SQL personalizada
    • Parámetros:
      • query: Cadena de consulta SQL
    use_mcp_tool({
  server_name: "singlestore",
  tool_name: "query_table",
  arguments: {
    query: "SELECT * FROM your_table LIMIT 5"
  }
})

  3. describe_table

    • Obtiene información detallada sobre una tabla
    • Parámetros:
      • table: Nombre de la tabla
    use_mcp_tool({
  server_name: "singlestore",
  tool_name: "describe_table",
  arguments: {
    table: "your_table"
  }
})

  4. generate_er_diagram

    • Genera un diagrama ER de Mermaid del esquema de la base de datos
    • No requiere parámetros
    use_mcp_tool({
  server_name: "singlestore",
  tool_name: "generate_er_diagram",
  arguments: {}
})

  5. run_read_query

    • Ejecuta una consulta de solo lectura (SELECT) en la base de datos
    • Parámetros:
      • query: Consulta SQL SELECT a ejecutar
    use_mcp_tool({
  server_name: "singlestore",
  tool_name: "run_read_query",
  arguments: {
    query: "SELECT * FROM your_table LIMIT 5"
  }
})

  6. create_table

    • Crea una nueva tabla en la base de datos con columnas y restricciones especificadas
    • Parámetros:
      • table_name: Nombre de la tabla a crear
      • columns: Matriz de definiciones de columnas
      • table_options: Configuración opcional de la tabla
    use_mcp_tool({
  server_name: "singlestore",
  tool_name: "create_table",
  arguments: {
    table_name: "new_table",
    columns: [
      {
        name: "id",
        type: "INT",
        nullable: false,
        auto_increment: true
      },
      {
        name: "name",
        type: "VARCHAR(255)",
        nullable: false
      }
    ],
    table_options: {
      shard_key: ["id"],
      sort_key: ["name"]
    }
  }
})

  7. generate_synthetic_data

    • Genera e inserta datos sintéticos en una tabla existente
    • Parámetros:
      • table: Nombre de la tabla donde insertar 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)
    use_mcp_tool({
  server_name: "singlestore",
  tool_name: "generate_synthetic_data",
  arguments: {
    table: "customers",
    count: 1000,
    column_generators: {
      "customer_id": {
        "type": "sequence",
        "start": 1000
      },
      "status": {
        "type": "values",
        "values": ["active", "inactive", "pending"]
      },
      "signup_date": {
        "type": "formula",
        "formula": "NOW() - INTERVAL FLOOR(RAND() * 365) DAY"
      }
    },
    batch_size: 500
  }
})

  8. optimize_sql

    • Analiza una consulta SQL usando PROFILE y proporciona recomendaciones de optimización
    • Parámetros:
      • query: Consulta SQL a analizar y optimizar
    use_mcp_tool({
  server_name: "singlestore",
  tool_name: "optimize_sql",
  arguments: {
    query: "SELECT * FROM customers JOIN orders ON customers.id = orders.customer_id WHERE region = 'west'"
  }
})
    • 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

  1. Compilar el servidor:
npm run build
  1. Ejecutar el servidor solo con el protocolo MCP:
node build/index.js
  1. Ejecutar el servidor con ambos 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 endpoints HTTP:

  1. Endpoint raíz

    GET /

    Devuelve información del servidor y endpoints disponibles.

  2. Verificación de estado

    GET /health

    Devuelve información de estado sobre el servidor.

  3. Conexión SSE

    GET /sse

    Establece una conexión de Eventos Enviados por el Servidor para actualizaciones en tiempo real.

  4. Listar herramientas

    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": {}
}

  5. Llamar herramienta

    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 SSE

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

  1. message (evento sin nombre): Se envía cuando se establece exitosamente una conexión SSE.
  2. open: Evento adicional de conexión establecida.
  3. message: Se utiliza para todos los mensajes del protocolo MCP, incluidos los eventos de inicio de herramienta, resultado y error.

Todos los eventos siguen el formato JSON-RPC 2.0 utilizado por el protocolo MCP. El sistema utiliza el tipo de evento estándar message para compatibilidad con MCP Inspector y la mayoría de las bibliotecas de clientes 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

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

  1. Inicie tanto el servidor como el inspector MCP en un solo comando:

    npm run inspector

    O inicie solo el servidor con:

    npm run start:inspector

  2. Para instalar y ejecutar MCP Inspector por separado:

    npx @modelcontextprotocol/inspector

    El inspector se abrirá en su navegador predeterminado.

  3. Cuando se abra MCP Inspector:

    a. Ingrese la URL en el campo de conexión:

    http://localhost:8081

    Nota: El puerto real puede variar según su configuración. Verifique los registros de inicio del servidor para conocer el puerto real en uso. 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"

  4. Si encuentra problemas de conexión, pruebe estas alternativas:

    a. Intente conectarse a un endpoint 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

  5. Depuración de problemas de conexión:

    a. Verifique que el servidor esté ejecutándose visitando http://localhost:8081 en su navegador

    b. Revise los registros del servidor para ver intentos de conexión

    c. Intente reiniciar tanto el servidor como el inspector

    d. Asegúrese de que ningún otro servicio esté usando el puerto 8081

    e. 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 su configuración de firewall permita conexiones al puerto 8081

  6. Una vez conectado, el inspector mostrará todas las herramientas disponibles y le permitirá probarlas interactivamente.

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

Integración con clientes MCP

Instalación en Claude Desktop

  1. 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
    • Windows: %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 soporte SSE junto con el protocolo MCP estándar.

  1. Reinicie la aplicación Claude Desktop

  2. En su conversación con Claude, ahora puede usar el servidor MCP de SingleStore con:

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

Instalación en Windsurf

  1. Agregue la configuración del servidor a su archivo de configuración de Windsurf ubicado en:
    • macOS: ~/Library/Application Support/Windsurf/config.json
    • Windows: %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.

  1. Reinicie Windsurf

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

Instalación en Cursor

  1. Agregue la configuración del servidor a la configuración de Cursor:
    • Abra Cursor
    • 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 mediante Eventos Enviados por el Servidor.

  1. Reinicie Cursor

  2. Al usar Claude AI dentro de Cursor, las herramientas MCP de SingleStore estarán disponibles para operaciones de base de datos.

Consideraciones de seguridad

  1. Nunca envíe credenciales al control de versiones
  2. Use variables de entorno o gestión segura de configuración
  3. Considere usar un mecanismo de agrupación de conexiones para uso en producción
  4. Implemente controles de acceso y permisos de usuario apropiados en SingleStore
  5. Mantenga actualizado el paquete de certificados CA de SingleStore

Desarrollo

Estructura del proyecto

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

Compilación

npm run build

Pruebas

npm test

Solución de problemas

  1. Problemas de conexión

    • Verifique las credenciales y la información del host en sus variables de entorno
    • Revise la configuración SSL
    • Asegúrese de que la base de datos sea accesible desde su red
    • Revise su configuración de firewall para permitir conexiones salientes a su base de datos SingleStore

  2. Problemas de compilación

    • Limpie node_modules y reinstale las dependencias
    • Verifique la configuración de TypeScript
    • Revise la compatibilidad de la versión de Node.js (debe ser 16+)

  3. Problemas de integración MCP

    • Verifique que la ruta al archivo build/index.js del servidor sea correcta en su configuración de cliente
    • Revise que todas las variables de entorno estén configuradas correctamente en su configuración de cliente
    • Reinicie su aplicación cliente después de realizar cambios en la configuración
    • Revise los registros del cliente para ver mensajes de error relacionados con el servidor MCP
    • Intente ejecutar el servidor de forma independiente primero para validar que funciona fuera del cliente

Contribuciones

  1. Haga un fork del repositorio
  2. Cree una rama de características
  3. Envíe sus cambios
  4. Haga push a la rama
  5. Cree una Solicitud de Extracción (Pull Request)

Licencia

Licencia MIT: consulte el archivo LICENSE para más detalles