SingleStore MCP Server

Servidor MCP SingleStore

[Model Context Protocol]((https://modelcontextprotocol.io/introduction) (MCP) é um protocolo padronizado projetado para gerenciar o contexto entre modelos de linguagem de grande escala (LLMs) e sistemas externos. Este repositório fornece um instalador e um Servidor MCP para o SingleStore, permitindo uma integração perfeita.

Com o MCP, você pode usar o Claude Desktop, Claude Code, Cursor ou qualquer cliente MCP compatível para interagir com o SingleStore usando linguagem natural, facilitando a execução de operações complexas sem esforço.

💡 Dica Profissional: Não sabe o que o servidor MCP pode fazer? Basta chamar o prompt /help no seu chat!

Requisitos

• Python >= v3.10.0
• uvx instalado no seu ambiente Python
• VS Code, Cursor, Windsurf, Claude Desktop, Claude Code, Goose ou qualquer outro cliente MCP

Primeiros passos

Primeiros passos

Primeiro, instale o servidor MCP SingleStore com o seu cliente.

A configuração padrão funciona na maioria das ferramentas:

{
  "mcpServers": {
    "singlestore-mcp-server": {
      "command": "uvx",
      "args": [
        "singlestore-mcp-server",
        "start"
      ]
    }
  }
}

Sem necessidade de chaves de API, tokens ou variáveis de ambiente! O servidor gerencia automaticamente a autenticação via OAuth no navegador quando iniciado.

uvx singlestore-mcp-server init --client=claude-desktop

uvx singlestore-mcp-server init --client=claude-code

claude mcp add singlestore-mcp-server uvx singlestore-mcp-server start

uvx singlestore-mcp-server init --client=cursor

uvx singlestore-mcp-server init --client=vscode

code --add-mcp '{"name":"singlestore-mcp-server","command":"uvx","args":["singlestore-mcp-server","start"]}'

uvx singlestore-mcp-server init --client=windsurf

uvx singlestore-mcp-server init --client=gemini

uvx singlestore-mcp-server init --client=lm-studio

Usando Docker

NOTA: Uma chave de API é necessária ao usar Docker porque o fluxo OAuth não é suportado para servidores executando em contêineres Docker.

{
  "mcpServers": {
    "singlestore-mcp-server": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--init", "--pull=always",
        "-e", "MCP_API_KEY=your_api_key_here",
        "singlestore/mcp-server-singlestore"
      ]
    }
  }
}

Você mesmo pode construir a imagem Docker:

docker build -t singlestore/mcp-server-singlestore .

Para maior segurança, recomendamos usar o Docker Desktop para configurar o servidor MCP SingleStore — veja este post no blog para detalhes sobre o novo Catálogo MCP do Docker.

Componentes

Ferramentas

O servidor implementa as seguintes ferramentas:

• get_user_info: Recupera detalhes sobre o usuário atual

  • Nenhum argumento necessário
  • Retorna informações e detalhes do usuário

• organization_info: Recupera detalhes sobre a organização atual do usuário

  • Nenhum argumento necessário
  • Retorna detalhes da organização

• choose_organization: Escolhe entre as organizações disponíveis (disponível apenas quando a variável de ambiente da chave de API não está definida)

  • Nenhum argumento necessário
  • Retorna uma lista de organizações disponíveis para escolha

• set_organization: Define a organização ativa (disponível apenas quando a variável de ambiente da chave de API não está definida)

  • Argumentos: organization_id (string)
  • Define a organização especificada como ativa

• workspace_groups_info: Recupera detalhes sobre os grupos de workspace acessíveis ao usuário

  • Nenhum argumento necessário
  • Retorna detalhes dos grupos de workspace

• workspaces_info: Recupera detalhes sobre os workspaces em um grupo de workspace específico

  • Argumentos: workspace_group_id (string)
  • Retorna detalhes dos workspaces

• resume_workspace: Retoma um workspace suspenso

  • Argumentos: workspace_id (string)
  • Retoma o workspace especificado

• list_starter_workspaces: Lista todos os workspaces iniciais acessíveis ao usuário

  • Nenhum argumento necessário
  • Retorna detalhes dos workspaces iniciais disponíveis

• create_starter_workspace: Cria um novo workspace inicial

  • Argumentos: parâmetros de configuração do workspace
  • Retorna detalhes do workspace inicial criado

• terminate_starter_workspace: Encerra um workspace inicial existente

  • Argumentos: workspace_id (string)
  • Encerra o workspace inicial especificado

• list_regions: Recupera uma lista de todas as regiões que suportam workspaces

  • Nenhum argumento necessário
  • Retorna uma lista de regiões disponíveis

• list_sharedtier_regions: Recupera uma lista de regiões de tier compartilhado

  • Nenhum argumento necessário
  • Retorna uma lista de regiões de tier compartilhado

• run_sql: Executa operações SQL em um workspace conectado

  • Argumentos: workspace_id, database, sql_query e parâmetros de conexão
  • Retorna os resultados da consulta SQL em um formato estruturado

• create_notebook_file: Cria um novo arquivo de notebook no SingleStore Spaces

  • Argumentos: notebook_name, content (opcional)
  • Retorna detalhes do notebook criado

• upload_notebook_file: Envia um arquivo de notebook para o SingleStore Spaces

  • Argumentos: file_path, notebook_name
  • Retorna detalhes do notebook enviado

• create_job_from_notebook: Cria um job agendado a partir de um notebook

  • Argumentos: configuração do job incluindo notebook_path, schedule_mode, etc.
  • Retorna detalhes do job criado

• get_job: Recupera detalhes de um job existente

  • Argumentos: job_id (string)
  • Retorna detalhes do job especificado

• delete_job: Exclui um job existente

  • Argumentos: job_id (string)
  • Exclui o job especificado

• stage_list_files: Lista arquivos e pastas no sistema de arquivos de uma implantação Stage

  • Argumentos: deployment_id (string), path (string, opcional)
  • Retorna o conteúdo da pasta, incluindo arquivos e subpastas

• stage_get_file: Obtém um arquivo do Stage pelo caminho

  • Argumentos: deployment_id (string), path (string), return_type (string: 'metadata', 'url' ou 'content')
  • Retorna metadados do arquivo, uma URL de download ou conteúdo de texto

• stage_create_folder: Cria uma pasta no Stage

  • Argumentos: deployment_id (string), path (string)
  • Retorna o status da criação

• stage_upload_file: Envia um arquivo para o Stage com conteúdo de texto

  • Argumentos: deployment_id (string), path (string), content (string), local_path (string)
  • Retorna o status do envio

• stage_move: Move ou renomeia um arquivo ou pasta no Stage

  • Argumentos: deployment_id (string), source_path (string), destination_path (string)
  • Retorna o status da movimentação

• stage_delete: Exclui um arquivo ou pasta do Stage

  • Argumentos: deployment_id (string), path (string)
  • Retorna o status da exclusão

Nota: As ferramentas de gerenciamento de organização (choose_organization e set_organization) estão disponíveis apenas quando a variável de ambiente da chave de API não está definida, permitindo a seleção interativa da organização durante a autenticação OAuth.

Desenvolvimento

Pré-requisitos

• Python >= 3.11
• uv para gerenciamento de dependências

Configuração

1. Clone o repositório:

git clone https://github.com/singlestore-labs/mcp-server-singlestore.git
cd mcp-server-singlestore

1. Instale as dependências:

uv sync --dev

1. Configure os hooks de pre-commit (opcional, mas recomendado):

uv run pre-commit install

Fluxo de Trabalho de Desenvolvimento

# Quick quality checks (fast feedback)
./scripts/check.sh

# Run tests independently
./scripts/test.sh

# Comprehensive validation (before PRs)
./scripts/check-all.sh

# Create and publish releases
./scripts/release.sh

Executando Testes

# Run test suite with coverage
./scripts/test.sh

# Or use pytest directly
uv run pytest
uv run pytest --cov=src --cov-report=html

Qualidade do Código

Usamos Ruff tanto para linting quanto para formatação:

# Format code
uv run ruff format src/ tests/

# Lint code
uv run ruff check src/ tests/

# Lint and fix issues automatically
uv run ruff check --fix src/ tests/

Processo de Lançamento

Os lançamentos são gerenciados por meio de tags git e publicação automatizada no PyPI:

1. Criar lançamento: ./scripts/release.sh (ferramenta interativa)
2. Publicação automática: Acionada ao enviar tags de versão
3. Sem uploads manuais para o PyPI - pipeline totalmente automatizado

Consulte scripts/dev-workflow.md para documentação detalhada do fluxo de trabalho.