Turso Cloud

Integre com bancos de dados Turso para LLMs, com um sistema de autenticação de dois níveis para operações seguras.

Documentação

mcp-turso-cloud

Um servidor Model Context Protocol (MCP) que fornece integração com bancos de dados Turso para LLMs. Este servidor implementa um sistema de autenticação de dois níveis para lidar com operações tanto no nível da organização quanto no nível do banco de dados, facilitando o gerenciamento e a consulta de bancos de dados Turso diretamente de LLMs.

Recursos

🏢 Operações no Nível da Organização

Listar Bancos de Dados: Visualize todos os bancos de dados na sua organização Turso
Criar Banco de Dados: Crie novos bancos de dados com opções personalizáveis
Excluir Banco de Dados: Remova bancos de dados da sua organização
Gerar Token de Banco de Dados: Crie tokens de autenticação para bancos de dados específicos

💾 Operações no Nível do Banco de Dados

Listar Tabelas: Visualize todas as tabelas em um banco de dados específico
Executar Consulta Somente Leitura: Execute consultas SELECT e PRAGMA (operações somente leitura)
Executar Consulta: Execute consultas SQL potencialmente destrutivas (INSERT, UPDATE, DELETE, etc.)
Descrever Tabela: Obtenha informações de esquema para tabelas do banco de dados
Busca Vetorial: Realize busca por similaridade vetorial usando extensões vetoriais do SQLite

⚠️ IMPORTANTE: Segurança na Execução de Consultas ⚠️

Este servidor implementa uma separação focada em segurança entre operações de banco de dados somente leitura e destrutivas:

Use execute_read_only_query para consultas SELECT e PRAGMA (operações seguras, somente leitura)
Use execute_query para INSERT, UPDATE, DELETE, CREATE, DROP e outras operações que modificam dados

Essa separação permite diferentes níveis de permissão e requisitos de aprovação:

Operações somente leitura podem ser aprovadas automaticamente em muitos contextos
Operações destrutivas podem exigir aprovação explícita por segurança

SEMPRE LEIA E REVISE CUIDADOSAMENTE AS CONSULTAS SQL ANTES DE APROVÁ-LAS! Isso é especialmente crítico para operações destrutivas que podem modificar ou excluir dados. Reserve um tempo para entender o que cada consulta faz antes de permitir sua execução.

Sistema de Autenticação de Dois Níveis

O servidor implementa um sistema de autenticação sofisticado:

Autenticação no Nível da Organização
- Usa um token de API da Plataforma Turso
- Gerencia bancos de dados e operações no nível da organização
- Obtido através do painel da Turso
Autenticação no Nível do Banco de Dados
- Usa tokens específicos do banco de dados
- Gerados automaticamente usando o token da organização
- Armazenados em cache para desempenho e rotacionados conforme necessário

Configuração

Este servidor requer configuração através do seu cliente MCP. Aqui estão exemplos para diferentes ambientes:

Configuração Cline/Claude Desktop

Adicione isto às configurações MCP do seu Cline/Claude Desktop:

{
	"mcpServers": {
		"mcp-turso-cloud": {
			"command": "npx",
			"args": ["-y", "mcp-turso-cloud"],
			"env": {
				"TURSO_API_TOKEN": "your-turso-api-token",
				"TURSO_ORGANIZATION": "your-organization-name",
				"TURSO_DEFAULT_DATABASE": "optional-default-database"
			}
		}
	}
}

Configuração Claude Desktop com WSL

Para ambientes WSL, adicione isto à sua configuração do Claude Desktop:

{
	"mcpServers": {
		"mcp-turso-cloud": {
			"command": "wsl.exe",
			"args": [
				"bash",
				"-c",
				"TURSO_API_TOKEN=your-token TURSO_ORGANIZATION=your-org node /path/to/mcp-turso-cloud/dist/index.js"
			]
		}
	}
}

Variáveis de Ambiente

O servidor requer as seguintes variáveis de ambiente:

TURSO_API_TOKEN: Seu token de API da Plataforma Turso (obrigatório)
TURSO_ORGANIZATION: O nome da sua organização Turso (obrigatório)
TURSO_DEFAULT_DATABASE: Banco de dados padrão a ser usado quando nenhum for especificado (opcional)
TOKEN_EXPIRATION: Tempo de expiração para tokens de banco de dados gerados (opcional, padrão: '7d')
TOKEN_PERMISSION: Nível de permissão para tokens gerados (opcional, padrão: 'full-access')

API

O servidor implementa Ferramentas MCP organizadas por categoria:

Ferramentas da Organização

list_databases

Lista todos os bancos de dados na sua organização Turso.

Parâmetros: Nenhum

Exemplo de resposta:

{
	"databases": [
		{
			"name": "customer_db",
			"id": "abc123",
			"region": "us-east",
			"created_at": "2023-01-15T12:00:00Z"
		},
		{
			"name": "product_db",
			"id": "def456",
			"region": "eu-west",
			"created_at": "2023-02-20T15:30:00Z"
		}
	]
}

create_database

Cria um novo banco de dados na sua organização.

Parâmetros:

name (string, obrigatório): Nome para o novo banco de dados
group (string, opcional): Grupo ao qual atribuir o banco de dados
regions (string[], opcional): Regiões para implantar o banco de dados

Exemplo:

{
	"name": "analytics_db",
	"group": "production",
	"regions": ["us-east", "eu-west"]
}

delete_database

Exclui um banco de dados da sua organização.

Parâmetros:

name (string, obrigatório): Nome do banco de dados a ser excluído

Exemplo:

{
	"name": "test_db"
}

generate_database_token

Gera um novo token para um banco de dados específico.

Parâmetros:

database (string, obrigatório): Nome do banco de dados
expiration (string, opcional): Tempo de expiração do token
permission (string, opcional): Nível de permissão ('full-access' ou 'read-only')

Exemplo:

{
	"database": "customer_db",
	"expiration": "30d",
	"permission": "read-only"
}

Ferramentas do Banco de Dados

list_tables

Lista todas as tabelas em um banco de dados.

Parâmetros:

database (string, opcional): Nome do banco de dados (usa o contexto se não for fornecido)

Exemplo:

{
	"database": "customer_db"
}

execute_read_only_query

Executa uma consulta SQL somente leitura (SELECT, PRAGMA) em um banco de dados.

Parâmetros:

query (string, obrigatório): Consulta SQL a ser executada (deve ser SELECT ou PRAGMA)
params (object, opcional): Parâmetros da consulta
database (string, opcional): Nome do banco de dados (usa o contexto se não for fornecido)

Exemplo:

{
	"query": "SELECT * FROM users WHERE age > ?",
	"params": { "1": 21 },
	"database": "customer_db"
}

execute_query

Executa uma consulta SQL potencialmente destrutiva (INSERT, UPDATE, DELETE, CREATE, etc.) em um banco de dados.

Parâmetros:

query (string, obrigatório): Consulta SQL a ser executada (não pode ser SELECT ou PRAGMA)
params (object, opcional): Parâmetros da consulta
database (string, opcional): Nome do banco de dados (usa o contexto se não for fornecido)

Exemplo:

{
	"query": "INSERT INTO users (name, age) VALUES (?, ?)",
	"params": { "1": "Alice", "2": 30 },
	"database": "customer_db"
}

describe_table

Obtém informações de esquema para uma tabela.

Parâmetros:

table (string, obrigatório): Nome da tabela
database (string, opcional): Nome do banco de dados (usa o contexto se não for fornecido)

Exemplo:

{
	"table": "users",
	"database": "customer_db"
}

vector_search

Realiza busca por similaridade vetorial usando extensões vetoriais do SQLite.

Parâmetros:

table (string, obrigatório): Nome da tabela
vector_column (string, obrigatório): Coluna contendo vetores
query_vector (number[], obrigatório): Vetor de consulta para busca por similaridade
limit (number, opcional): Número máximo de resultados (padrão: 10)
database (string, opcional): Nome do banco de dados (usa o contexto se não for fornecido)

Exemplo:

{
	"table": "embeddings",
	"vector_column": "embedding",
	"query_vector": [0.1, 0.2, 0.3, 0.4],
	"limit": 5,
	"database": "vector_db"
}

Desenvolvimento

Configuração Inicial

Clone o repositório
Instale as dependências:

npm install

Compile o projeto:

npm run build

Execute em modo de desenvolvimento:

npm run dev

Publicação

Atualize a versão no package.json
Compile o projeto:

npm run build

Publique no npm:

npm publish

Solução de Problemas

Problemas com Token de API

Se você encontrar erros de autenticação:

Verifique se o seu token de API Turso é válido e possui as permissões necessárias
Verifique se o nome da sua organização está correto
Certifique-se de que o seu token não expirou

Problemas de Conexão com o Banco de Dados

Se você tiver problemas para conectar aos bancos de dados:

Verifique se o banco de dados existe na sua organização
Verifique se o seu token de API tem acesso ao banco de dados
Certifique-se de que o nome do banco de dados está escrito corretamente

Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença

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

Agradecimentos

Construído com: