CockroachDB

Servidor MCP do CockroachDB

English | 简体中文

Este é um servidor MCP do CockroachDB para Cursor, implementado com base na especificação do Model Context Protocol (MCP), permitindo que você interaja diretamente com o banco de dados CockroachDB no Cursor.

Recursos

• Conectar ao banco de dados CockroachDB
• Obter todas as tabelas do banco de dados
• Obter informações da estrutura das tabelas
• Executar consultas SQL
• Fornecer recursos de status do banco de dados
• Fornecer modelos de consulta SQL
• Mecanismo automático de reconexão para garantir estabilidade da conexão
• Mecanismo de manutenção da conexão para evitar timeout
• Tratamento adequado de encerramento do processo
• Registros detalhados para solução de problemas
• Suporte a desconexão manual

Instalação

Instalação via Smithery

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

npx -y @smithery/cli install @Swayingleaves/cockroachdb-mcp-server --client claude

1. Clone o repositório e entre no diretório do projeto
2. Instale as dependências:

pip install -r requirements.txt

3. Instale o uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Uso no Cursor

{
    "mcpServers": {
        "cockroachdb-mcp": {
            "command": "uv",
            "args": [
                "--directory",
                "/Users/local/cockroachdb-mcp",
                "run",
                "server.py"
            ],
            "jdbc_url": "jdbc:postgresql://localhost:26257/defaultdb",
            "username": "root",
            "password": "root"
        }
    }
  }

Descrição das Funções MCP

Ferramentas

connect_database

Conecta ao banco de dados CockroachDB.

Parâmetros:

• jdbc_url: URL de conexão JDBC (ex.: jdbc:postgresql://localhost:26257/defaultdb)
• username: Nome de usuário do banco de dados
• password: Senha do banco de dados

initialize_connection

Inicializa a conexão com o banco de dados; pode ser chamado imediatamente após conectar ao servidor MCP para estabelecer uma conexão com o banco.

Parâmetros:

• jdbc_url: URL de conexão JDBC (ex.: jdbc:postgresql://localhost:26257/defaultdb)
• username: Nome de usuário do banco de dados
• password: Senha do banco de dados

disconnect_database

Desconecta manualmente do banco de dados.

Sem parâmetros.

get_tables

Obtém todas as tabelas do banco de dados.

Sem parâmetros.

get_table_schema

Obtém informações da estrutura de uma tabela especificada.

Parâmetros:

• table_name: Nome da tabela

execute_query

Executa consulta SQL.

Parâmetros:

• query: Instrução de consulta SQL

Recursos

db://status

Obtém o status da conexão com o banco de dados.

Retorna:

• Quando não conectado: "Not connected"
• Quando conectado: "Connected - [Database version]"
• Quando há erro de conexão: "Connection error - [Error message]"

Prompts

sql_query_template

Modelo de consulta SQL para ajudar os usuários a escrever consultas SQL.

Registros

Os registros do servidor são salvos no arquivo logs/cockroachdb_mcp.log. Você pode verificar este arquivo para entender o status de execução do servidor e os registros detalhados.

O arquivo de registro usa um mecanismo de rotação de logs, com tamanho máximo de 10MB por arquivo e retenção de até 5 arquivos de backup para evitar uso excessivo de espaço em disco.

Tratamento de Caracteres Especiais

Este servidor usa psycopg2 para conectar diretamente ao banco de dados CockroachDB, que trata automaticamente caracteres especiais em nomes de usuário e senhas sem necessidade de codificação adicional de URL. Isso garante uma conexão correta ao banco de dados mesmo quando as senhas contêm caracteres especiais (como @, %, &, etc.).

Configurações de TCP Keep-alive

O servidor é configurado com mecanismo TCP keep-alive por padrão para evitar que conexões sejam encerradas devido a longos períodos de inatividade:

• keepalives=1: Ativar TCP keepalive
• keepalives_idle=30: Enviar keepalive após 30 segundos de inatividade
• keepalives_interval=10: Enviar keepalive a cada 10 segundos
• keepalives_count=5: Desistir após 5 tentativas

Solução de Problemas

Se você encontrar problemas, verifique o arquivo de registro logs/cockroachdb_mcp.log, que ajudará a entender o status de execução do servidor e possíveis problemas.

Problemas Comuns

1. Conexão Recusada: Certifique-se de que o servidor CockroachDB está em execução e acessível a partir da sua máquina.
2. Falha de Autenticação: Verifique se o nome de usuário e a senha estão corretos.
3. Timeout de Conexão: Verifique se a conexão de rede está estável, especialmente ao conectar a um banco de dados remoto.
4. Problemas no Servidor de Banco de Dados: Verifique se o servidor CockroachDB está funcionando corretamente.