SingleStore MCP Server

Um servidor MCP para interagir com bancos de dados SingleStore, exigindo variáveis de ambiente para conexão.

GitHub
4
Experimente este MCPPatrocinado

Documentação

SingleStore MCP Server

smithery badge

Um servidor Model Context Protocol (MCP) para interagir com bancos de dados SingleStore. Este servidor fornece ferramentas para consultar tabelas, descrever esquemas e gerar diagramas ER.

Recursos

  • Listar todas as tabelas no banco de dados
  • Executar consultas SQL personalizadas
  • Obter informações detalhadas sobre tabelas, incluindo esquema e dados de exemplo
  • Gerar diagramas ER Mermaid do esquema do banco de dados
  • Suporte a SSL com busca automática do pacote de certificados CA
  • Tratamento adequado de erros e segurança de tipos TypeScript

Pré-requisitos

  • Node.js 16 ou superior
  • npm ou yarn
  • Acesso a um banco de dados SingleStore
  • Pacote de certificados CA do SingleStore (buscado automaticamente no portal)

Instalação

Instalação via Smithery

Para instalar o SingleStore MCP Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @madhukarkumar/singlestore-mcp-server --client claude
  1. Clone o repositório:
git clone <repository-url>
cd mcp-server-singlestore
  1. Instale as dependências:
npm install
  1. Compile o servidor:
npm run build

Variáveis de Ambiente

Variáveis de Ambiente Obrigatórias

O servidor requer as seguintes variáveis de ambiente para a conexão com o banco de dados:

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

Todas essas variáveis de ambiente são obrigatórias para que o servidor estabeleça uma conexão com seu banco de dados SingleStore. A conexão usa SSL com o pacote de certificados CA do SingleStore, que é buscado automaticamente no portal do SingleStore.

Variáveis de Ambiente Opcionais

Para suporte ao protocolo SSE (Server-Sent Events):

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)

Definindo Variáveis de Ambiente

  1. No seu Shell: Defina as variáveis no seu terminal antes de executar o 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. Em Arquivos de Configuração do Cliente: Adicione as variáveis ao arquivo de configuração do seu cliente MCP, conforme mostrado nas seções de integração abaixo.

Uso

Suporte a Protocolos

Este servidor suporta dois protocolos para integração com clientes:

  1. Protocolo MCP: O Model Context Protocol padrão usando comunicação stdio, usado por Claude Desktop, Windsurf e Cursor.
  2. Protocolo SSE: Server-Sent Events sobre HTTP para clientes baseados na web e aplicações que precisam de streaming de dados em tempo real.

Ambos os protocolos expõem as mesmas ferramentas e funcionalidades, permitindo que você escolha o melhor método de integração para o seu caso de uso.

Ferramentas Disponíveis

  1. list_tables

    • Lista todas as tabelas no banco de dados
    • Nenhum parâmetro necessário
    use_mcp_tool({
  server_name: "singlestore",
  tool_name: "list_tables",
  arguments: {}
})

  2. query_table

    • Executa uma consulta SQL personalizada
    • Parâmetros:
      • query: string da consulta SQL
    use_mcp_tool({
  server_name: "singlestore",
  tool_name: "query_table",
  arguments: {
    query: "SELECT * FROM your_table LIMIT 5"
  }
})

  3. describe_table

    • Obtém informações detalhadas sobre uma tabela
    • Parâmetros:
      • table: nome da tabela
    use_mcp_tool({
  server_name: "singlestore",
  tool_name: "describe_table",
  arguments: {
    table: "your_table"
  }
})

  4. generate_er_diagram

    • Gera um diagrama ER Mermaid do esquema do banco de dados
    • Nenhum parâmetro necessário
    use_mcp_tool({
  server_name: "singlestore",
  tool_name: "generate_er_diagram",
  arguments: {}
})

  5. run_read_query

    • Executa uma consulta somente leitura (SELECT) no banco de dados
    • Parâmetros:
      • query: consulta SQL SELECT a ser executada
    use_mcp_tool({
  server_name: "singlestore",
  tool_name: "run_read_query",
  arguments: {
    query: "SELECT * FROM your_table LIMIT 5"
  }
})

  6. create_table

    • Cria uma nova tabela no banco de dados com colunas e restrições especificadas
    • Parâmetros:
      • table_name: nome da tabela a ser criada
      • columns: array de definições de colunas
      • table_options: configuração opcional da tabela
    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

    • Gera e insere dados sintéticos em uma tabela existente
    • Parâmetros:
      • table: nome da tabela onde os dados serão inseridos
      • count: número de linhas a gerar (padrão: 100)
      • column_generators: geradores personalizados para colunas específicas
      • batch_size: número de linhas a inserir em cada lote (padrão: 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

    • Analisa uma consulta SQL usando PROFILE e fornece recomendações de otimização
    • Parâmetros:
      • query: consulta SQL a ser analisada e otimizada
    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'"
  }
})
    • A resposta inclui:
      • Consulta original
      • Resumo do perfil de desempenho (tempo total de execução, tempo de compilação, tempo de execução)
      • Lista de gargalos detectados
      • Recomendações de otimização com níveis de impacto (alto/médio/baixo)
      • Sugestões para índices, junções, uso de memória e outras otimizações

Execução Autônoma

  1. Compile o servidor:
npm run build
  1. Execute o servidor apenas com o protocolo MCP:
node build/index.js
  1. Execute o servidor com os protocolos MCP e SSE:
SSE_ENABLED=true SSE_PORT=3333 node build/index.js

Usando o Protocolo SSE

Quando o SSE está habilitado, o servidor expõe os seguintes endpoints HTTP:

  1. Endpoint Raiz

    GET /

    Retorna informações do servidor e endpoints disponíveis.

  2. Verificação de Saúde

    GET /health

    Retorna informações de status sobre o servidor.

  3. Conexão SSE

    GET /sse

    Estabelece uma conexão Server-Sent Events para atualizações em tempo real.

  4. Listar Ferramentas

    GET /tools

    Retorna uma lista de todas as ferramentas disponíveis, igual à funcionalidade list_tools do MCP.

    Também suporta requisições POST para compatibilidade com o MCP Inspector:

    POST /tools
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": "request-id",
  "method": "mcp.list_tools",
  "params": {}
}

  5. Chamar Ferramenta

    POST /call-tool
Content-Type: application/json

{
  "name": "tool_name",
  "arguments": {
    "param1": "value1",
    "param2": "value2"
  },
  "client_id": "optional_sse_client_id_for_streaming_response"
}

    Executa uma ferramenta com os argumentos fornecidos.

    • Se client_id for fornecido, a resposta é transmitida para esse cliente SSE.
    • Se client_id for omitido, a resposta é retornada diretamente na resposta HTTP.

    Também suporta o formato MCP padrão para compatibilidade com o 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

Ao usar conexões SSE, o servidor envia os seguintes tipos de eventos:

  1. message (evento sem nome): Enviado quando uma conexão SSE é estabelecida com sucesso.
  2. open: Evento adicional de conexão estabelecida.
  3. message: Usado para todas as mensagens do protocolo MCP, incluindo eventos de início de ferramenta, resultado e erro.

Todos os eventos seguem o formato JSON-RPC 2.0 usado pelo protocolo MCP. O sistema usa o tipo de evento padrão message para compatibilidade com o MCP Inspector e a maioria das bibliotecas de cliente SSE.

Exemplo 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));

Usando com o MCP Inspector

O MCP Inspector é uma ferramenta baseada em navegador para testar e depurar servidores MCP. Para usá-lo com este servidor:

  1. Inicie o servidor e o MCP Inspector em um único comando:

    npm run inspector

    Ou inicie apenas o servidor com:

    npm run start:inspector

  2. Para instalar e executar o MCP Inspector separadamente:

    npx @modelcontextprotocol/inspector

    O inspector abrirá no seu navegador padrão.

  3. Quando o MCP Inspector abrir:

    a. Insira a URL no campo de conexão:

    http://localhost:8081

    Nota: A porta real pode variar dependendo da sua configuração. Verifique os logs de inicialização do servidor para saber a porta real em uso. O servidor exibirá:

    MCP SingleStore SSE server listening on port XXXX

    b. Certifique-se de que "SSE" esteja selecionado como tipo de transporte

    c. Clique em "Connect"

  4. Se você encontrar problemas de conexão, tente estas alternativas:

    a. Tente conectar a um endpoint específico:

    http://localhost:8081/stream

    b. Tente usar o endereço IP real da sua máquina:

    http://192.168.1.x:8081

    c. Se estiver executando em Docker:

    http://host.docker.internal:8081

  5. Depurando problemas de conexão:

    a. Verifique se o servidor está em execução visitando http://localhost:8081 no seu navegador

    b. Verifique os logs do servidor para tentativas de conexão

    c. Tente reiniciar o servidor e o inspector

    d. Certifique-se de que nenhum outro serviço esteja usando a porta 8081

    e. Teste a conexão SSE com o script fornecido:

    npm run test:sse

    Ou manualmente com curl:

    curl -N http://localhost:8081/sse

    f. Verifique se as configurações do firewall permitem conexões na porta 8081

  6. Após conectar, o inspector mostrará todas as ferramentas disponíveis e permitirá que você as teste interativamente.

⚠️ Nota: Ao usar o MCP Inspector, você deve usar a URL completa, incluindo o prefixo http://.

Integração com Clientes MCP

Instalação no Claude Desktop

  1. Adicione a configuração do servidor ao arquivo de configuração do Claude Desktop localizado em:
    • 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"
      }
    }
  }
}

As variáveis SSE_ENABLED e SSE_PORT são opcionais. Inclua-as se quiser habilitar o servidor HTTP com suporte a SSE junto com o protocolo MCP padrão.

  1. Reinicie o aplicativo Claude Desktop

  2. Na sua conversa com o Claude, você agora pode usar o servidor MCP do SingleStore com:

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

Instalação no Windsurf

  1. Adicione a configuração do servidor ao arquivo de configuração do Windsurf localizado em:
    • 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"
      }
    }
  }
}

As variáveis SSE_ENABLED e SSE_PORT são opcionais, mas habilitam funcionalidades adicionais através do servidor HTTP SSE.

  1. Reinicie o Windsurf

  2. Na sua conversa com o Claude no Windsurf, as ferramentas MCP do SingleStore estarão disponíveis automaticamente quando o Claude precisar acessar informações do banco de dados.

Instalação no Cursor

  1. Adicione a configuração do servidor nas configurações do Cursor:
    • Abra o Cursor
    • Vá para Configurações (ícone de engrenagem) > Extensões > Claude AI > MCP Servers
    • Adicione um novo servidor MCP com a seguinte configuração:
{
  "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"
    }
  }
}

As variáveis SSE_ENABLED e SSE_PORT permitem que aplicações web se conectem ao servidor via HTTP e recebam atualizações em tempo real através de Server-Sent Events.

  1. Reinicie o Cursor

  2. Ao usar o Claude AI dentro do Cursor, as ferramentas MCP do SingleStore estarão disponíveis para operações de banco de dados.

Considerações de Segurança

  1. Nunca envie credenciais para o controle de versão
  2. Use variáveis de ambiente ou gerenciamento seguro de configuração
  3. Considere usar um mecanismo de pool de conexões para uso em produção
  4. Implemente controles de acesso e permissões de usuário adequados no SingleStore
  5. Mantenha o pacote de certificados CA do SingleStore atualizado

Desenvolvimento

Estrutura do Projeto

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

Compilação

npm run build

Testes

npm test

Solução de Problemas

  1. Problemas de Conexão

    • Verifique as credenciais e informações do host nas suas variáveis de ambiente
    • Verifique a configuração SSL
    • Certifique-se de que o banco de dados esteja acessível a partir da sua rede
    • Verifique as configurações do firewall para permitir conexões de saída ao seu banco de dados SingleStore

  2. Problemas de Compilação

    • Limpe node_modules e reinstale as dependências
    • Verifique a configuração do TypeScript
    • Verifique a compatibilidade da versão do Node.js (deve ser 16+)

  3. Problemas de Integração MCP

    • Verifique se o caminho para o arquivo build/index.js do servidor está correto na configuração do seu cliente
    • Verifique se todas as variáveis de ambiente estão configuradas corretamente na configuração do seu cliente
    • Reinicie o aplicativo do cliente após fazer alterações na configuração
    • Verifique os logs do cliente para mensagens de erro relacionadas ao servidor MCP
    • Tente executar o servidor de forma autônoma primeiro para validar que ele funciona fora do cliente

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Faça commit das suas alterações
  4. Envie para o branch
  5. Crie um Pull Request

Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes