MCP Turso

MCP Turso

   

English | Português

Português

Sobre o Projeto

MCP Turso é a primeira solução completa para integrar bancos de dados Turso Cloud com o Model Context Protocol (MCP) no VSCode. Este projeto permite que o GitHub Copilot interaja diretamente com seus bancos Turso através de ferramentas MCP, facilitando operações CRUD e consultas SQL.

Por que este projeto existe?

• Primeira solução MCP para Turso: Não existia nenhuma implementação disponível para VSCODE
• Integração nativa com VSCode: Funciona perfeitamente com o GitHub Copilot
• Fácil configuração: Setup simples para Windows
• Ferramentas completas: Suporte a todas as operações básicas de banco de dados

Arquitetura MCP

Como o MCP Funciona

O Model Context Protocol (MCP) é um protocolo aberto que permite aos Large Language Models (LLMs) se conectarem a ferramentas e dados externos de forma padronizada.

Componentes Principais:

• Cliente MCP: Aplicação que usa o protocolo (ex: GitHub Copilot, Claude Desktop)
• Servidor MCP: Programa que expõe ferramentas e recursos (este projeto)
• Comunicação: Via stdio (stdin/stdout) usando JSON-RPC 2.0

Fluxo de Funcionamento:

1. Cliente MCP inicia o servidor
2. Servidor registra suas ferramentas via ListTools
3. Cliente pode chamar ferramentas via CallTool
4. Servidor executa a operação e retorna resultado

Segurança:

• Queries SELECT são validadas automaticamente
• Operações de escrita usam prepared statements
• Comunicação local via stdio (não expõe portas de rede)

Estrutura do Projeto

mcp-turso/
├── src/
│   └── index.ts          # Servidor MCP principal
├── dist/                 # Código compilado (gerado)
├── .env                  # Variáveis de ambiente (não versionado)
├── package.json          # Dependências e scripts
├── tsconfig.json         # Configuração TypeScript
└── README.md             # Esta documentação

Pré-requisitos

• Node.js 18+ (compatível com as dependências)
• Uma conta Turso Cloud com banco de dados ativo
• VSCode com GitHub Copilot instalado

Instalação

Passo 1: Criar o projeto

# Criar pasta do projeto
mkdir mcp-turso
cd mcp-turso

# Inicializar projeto Node.js
npm init -y

Passo 2: Instalar dependências

npm install @modelcontextprotocol/sdk @libsql/client dotenv
npm install -D typescript @types/node tsx

Passo 3: Configurar TypeScript

Crie o arquivo tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Passo 4: Criar o código do servidor

Crie a pasta src e o arquivo src/index.ts com o código fornecido no repositório.

Passo 5: Configurar package.json

Edite o package.json para incluir:

{
  "name": "mcp-turso",
  "version": "1.0.0",
  "type": "module",
  "bin": {
    "mcp-turso": "./dist/index.js"
  },
  "scripts": {
    "build": "tsc",
    "dev": "tsx src/index.ts",
    "start": "node dist/index.js"
  },
  "dependencies": {
    "@libsql/client": "^0.14.0",
    "@modelcontextprotocol/sdk": "^1.0.4",
    "dotenv": "^16.4.5"
  },
  "devDependencies": {
    "@types/node": "^22.10.2",
    "tsx": "^4.19.2",
    "typescript": "^5.7.2"
  }
}

Passo 6: Compilar o projeto

npm run build

Isso cria a pasta dist/ com o código JavaScript compilado.

Configuração

Variáveis de Ambiente

Crie um arquivo .env na raiz do projeto:

TURSO_DATABASE_URL=libsql://seu-banco.turso.io
TURSO_AUTH_TOKEN=seu-token-aqui

Para obter o token: ``bash turso auth token ``

Configuração no VSCode

Passo 1: Criar arquivo MCP

Na raiz do seu projeto (não do mcp-turso), crie .vscode/mcp.json:

{
  "mcpServers": {
    "turso-": {
      "command": "node",
      "args": ["C:/caminho/completo/mcp-turso/dist/index.js"],
      "env": {
        "TURSO_DATABASE_URL": "libsql://seu-banco.turso.io",
        "TURSO_AUTH_TOKEN": "seu-token-aqui"
      }
    }
  }
}

Importante: Substitua C:/caminho/completo/ pelo caminho real onde você criou o projeto mcp-turso.

Passo 2: Reiniciar VSCode

Feche completamente o VSCode e reabra para carregar a configuração MCP.

Uso no GitHub Copilot

Abra o Copilot Chat (Ctrl + Shift + I) e teste os comandos:

Liste todas as tabelas do meu banco de times

Mostre a estrutura da tabela jogadores

Conte quantos jogadores estão confirmados

Insira um novo jogador: nome "Carlos", whatsapp "11987654321"

Adicione uma coluna telefone do tipo TEXT na tabela jogadores

Crie um índice único no email dos usuários

Adicione uma foreign key entre jogadores e times

Ferramentas Disponíveis

| Ferramenta | Descrição | Exemplo | |------------|-----------|---------| | list_tables | Lista todas as tabelas | {} | | describe_table | Mostra estrutura de uma tabela | {"table": "jogadores"} | | execute_select | Executa SELECT (somente leitura) | {"query": "SELECT * FROM jogadores"} | | insert_data | Insere dados | {"table": "jogadores", "data": {"nome": "João"}} | | update_data | Atualiza dados | {"table": "jogadores", "data": {"status": "confirmado"}, "where": "id = 1"} | | delete_data | Deleta dados | {"table": "jogadores", "where": "id = 1"} | | count_rows | Conta registros | {"table": "jogadores", "where": "status = 'ativo'"} | | add_column | Adiciona coluna a tabela | {"table": "jogadores", "column": "telefone", "type": "TEXT"} | | execute_ddl | Executa comandos DDL | {"sql": "ALTER TABLE jogadores ADD COLUMN email TEXT"} | | create_index | Cria índice | {"name": "idx_jogadores_nome", "table": "jogadores", "column": "nome"} | | add_constraint | Adiciona constraint | {"table": "jogadores", "constraint_name": "fk_time", "constraint_type": "FOREIGN KEY", "columns": ["time_id"], "referenced_table": "times", "referenced_columns": ["id"]} | | begin_transaction | Inicia transação | {} | | commit_transaction | Confirma transação | {} | | rollback_transaction | Cancela transação | {} |

API Reference

Esquemas Detalhados das Ferramentas

list_tables

Descrição: Lista todas as tabelas do banco de dados Parâmetros: Nenhum Retorno: Lista de nomes de tabelas

describe_table

Descrição: Mostra a estrutura completa de uma tabela Parâmetros: ``json { "type": "object", "properties": { "table": { "type": "string", "description": "Nome da tabela a ser descrita" } }, "required": ["table"] } `` Retorno: Schema da tabela com colunas, tipos e constraints

execute_select

Descrição: Executa uma query SELECT (somente leitura) Parâmetros: ``json { "type": "object", "properties": { "query": { "type": "string", "description": "Query SQL SELECT válida" } }, "required": ["query"] } `` Validação: Query deve começar com "SELECT" (case insensitive) Retorno: Resultado da query em formato JSON

insert_data

Descrição: Insere um novo registro na tabela Parâmetros: ``json { "type": "object", "properties": { "table": { "type": "string", "description": "Nome da tabela" }, "data": { "type": "object", "description": "Objeto com dados a inserir", "additionalProperties": true } }, "required": ["table", "data"] } `` Retorno: ID do registro inserido

update_data

Descrição: Atualiza registros existentes Parâmetros: ``json { "type": "object", "properties": { "table": { "type": "string", "description": "Nome da tabela" }, "data": { "type": "object", "description": "Dados a atualizar", "additionalProperties": true }, "where": { "type": "string", "description": "Condição WHERE para identificar registros" } }, "required": ["table", "data", "where"] } `` Retorno: Número de registros afetados

delete_data

Descrição: Remove registros da tabela Parâmetros: ``json { "type": "object", "properties": { "table": { "type": "string", "description": "Nome da tabela" }, "where": { "type": "string", "description": "Condição WHERE para identificar registros" } }, "required": ["table", "where"] } `` Retorno: Número de registros removidos

count_rows

Descrição: Conta registros em uma tabela Parâmetros: ``json { "type": "object", "properties": { "table": { "type": "string", "description": "Nome da tabela" }, "where": { "type": "string", "description": "Condição WHERE opcional" } }, "required": ["table"] } `` Retorno: Número total de registros

add_column

Descrição: Adiciona uma nova coluna a uma tabela existente Parâmetros: ``json { "type": "object", "properties": { "table": { "type": "string", "description": "Nome da tabela" }, "column": { "type": "string", "description": "Nome da nova coluna" }, "type": { "type": "string", "description": "Tipo de dados da coluna (ex: 'TEXT', 'INTEGER', 'REAL', 'BLOB')" }, "nullable": { "type": "boolean", "description": "Se a coluna pode ser NULL (padrão: true)", "default": true }, "default_value": { "type": "string", "description": "Valor padrão da coluna (opcional)" } }, "required": ["table", "column", "type"] } `` Retorno: Confirmação da adição da coluna

Desenvolvimento

Para desenvolvimento local:

npm run dev  # Executa com tsx (hot reload)

Troubleshooting

Erro "command not found"

• Use caminho absoluto em args no .vscode/mcp.json
• Exemplo: C:/Users/Lucas Silva/projetos/mcp-turso/dist/index.js

Erro de permissão

• No primeiro uso, o Copilot vai pedir permissão
• Clique em "Allow" ou "Continue"

Ferramentas não aparecem

• Verifique se npm run build foi executado
• Reinicie o VSCode completamente
• Confirme se o caminho no .vscode/mcp.json está correto
• Verifique logs em Output → MCP

Erro de conexão com Turso

• Confirme se TURSO_DATABASE_URL e TURSO_AUTH_TOKEN estão corretos
• Execute turso auth token para gerar um novo token se necessário

Scripts Disponíveis

• npm run build: Compila TypeScript
• npm run dev: Executa em modo desenvolvimento
• npm start: Executa versão compilada

Roadmap

Próximas Funcionalidades

• [ ] Suporte a transações SQL
• [ ] Queries complexas com JOIN
• [ ] Backup e restore de bancos
• [ ] Interface web opcional para administração
• [ ] Suporte a múltiplos bancos Turso
• [ ] Integração com outras ferramentas MCP

Melhorias Planejadas

• [ ] Validação de schema mais rigorosa
• [ ] Suporte a tipos de dados avançados
• [ ] Cache de queries frequentes
• [ ] Logs estruturados
• [ ] Métricas de performance

Recursos Adicionais

Documentação MCP

• Especificação Oficial MCP
• Introdução ao MCP
• Exemplos de Servidores MCP

Turso

• Documentação Turso
• SDK LibSQL

Contribuição

1. Fork o projeto
2. Crie uma branch: git checkout -b feature/nome
3. Commit suas mudanças
4. Abra um Pull Request

Licença

MIT

---

English

About the Project

MCP Turso is the first complete solution to integrate Turso Cloud databases with Model Context Protocol (MCP) in VSCode. This project allows GitHub Copilot to interact directly with your Turso databases through MCP tools, facilitating CRUD operations and SQL queries.

Why this project exists?

• First MCP solution for Turso: No implementation was available
• Native VSCode integration: Works perfectly with GitHub Copilot
• Easy Windows setup: Simple configuration for Windows
• Complete tools: Support for all basic database operations

MCP Architecture

How MCP Works

Model Context Protocol (MCP) is an open protocol that allows Large Language Models (LLMs) to connect to external tools and data in a standardized way.

Main Components:

• MCP Client: Application that uses the protocol (e.g., GitHub Copilot, Claude Desktop)
• MCP Server: Program that exposes tools and resources (this project)
• Communication: Via stdio (stdin/stdout) using JSON-RPC 2.0

Operation Flow:

1. MCP Client starts the server
2. Server registers its tools via ListTools
3. Client can call tools via CallTool
4. Server executes the operation and returns result

Security:

• SELECT queries are automatically validated
• Write operations use prepared statements
• Local communication via stdio (no network ports exposed)

Project Structure

mcp-turso/
├── src/
│   └── index.ts          # Main MCP server
├── dist/                 # Compiled code (generated)
├── .env                  # Environment variables (not versioned)
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── README.md             # This documentation

Prerequisites

• Node.js 18+ (compatible with dependencies)
• A Turso Cloud account with active database
• VSCode with GitHub Copilot installed

Installation

Step 1: Create the project

# Create project folder
mkdir mcp-turso
cd mcp-turso

# Initialize Node.js project
npm init -y

Step 2: Install dependencies

npm install @modelcontextprotocol/sdk @libsql/client dotenv
npm install -D typescript @types/node tsx

Step 3: Configure TypeScript

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Step 4: Create server code

Create src folder and src/index.ts with the code provided in the repository.

Step 5: Configure package.json

Edit package.json to include:

{
  "name": "mcp-turso",
  "version": "1.0.0",
  "type": "module",
  "bin": {
    "mcp-turso": "./dist/index.js"
  },
  "scripts": {
    "build": "tsc",
    "dev": "tsx src/index.ts",
    "start": "node dist/index.js"
  },
  "dependencies": {
    "@libsql/client": "^0.14.0",
    "@modelcontextprotocol/sdk": "^1.0.4",
    "dotenv": "^16.4.5"
  },
  "devDependencies": {
    "@types/node": "^22.10.2",
    "tsx": "^4.19.2",
    "typescript": "^5.7.2"
  }
}

Step 6: Build the project

npm run build

This creates the dist/ folder with compiled JavaScript code.

Configuration

Environment Variables

Create a .env file in the project root:

TURSO_DATABASE_URL=libsql://your-database.turso.io
TURSO_AUTH_TOKEN=your-token-here

To get the token: ``bash turso auth token ``

VSCode Configuration

Step 1: Create MCP file

In the root of your project (not mcp-turso), create .vscode/mcp.json:

{
  "mcpServers": {
    "turso": {
      "command": "node",
      "args": ["C:/full/path/mcp-turso/dist/index.js"],
      "env": {
        "TURSO_DATABASE_URL": "libsql://your-database.turso.io",
        "TURSO_AUTH_TOKEN": "your-token-here"
      }
    }
  }
}

Important: Replace C:/full/path/ with the actual path where you created the mcp-turso project.

Step 2: Restart VSCode

Close VSCode completely and reopen to load the MCP configuration.

Usage in GitHub Copilot

Open Copilot Chat (Ctrl + Shift + I) and test commands:

List all tables in my times database

Show the structure of the players table

Count how many players are confirmed

Insert a new player: name "Carlos", whatsapp "11987654321"

Add a phone column of type TEXT to the players table

Create a unique index on user emails

Add a foreign key between players and teams

Available Tools

| Tool | Description | Example | |------|-------------|---------| | list_tables | Lists all tables | {} | | describe_table | Shows table structure | {"table": "players"} | | execute_select | Executes SELECT (read-only) | {"query": "SELECT * FROM players"} | | insert_data | Inserts data | {"table": "players", "data": {"name": "John"}} | | update_data | Updates data | {"table": "players", "data": {"status": "confirmed"}, "where": "id = 1"} | | delete_data | Deletes data | {"table": "players", "where": "id = 1"} | | count_rows | Counts records | {"table": "players", "where": "status = 'active'"} | | add_column | Adds column to table | {"table": "players", "column": "phone", "type": "TEXT"} | | execute_ddl | Executes DDL commands | {"sql": "ALTER TABLE players ADD COLUMN email TEXT"} | | create_index | Creates index | {"name": "idx_players_name", "table": "players", "column": "name"} | | add_constraint | Adds constraint | {"table": "players", "constraint_name": "fk_team", "constraint_type": "FOREIGN KEY", "columns": ["team_id"], "referenced_table": "teams", "referenced_columns": ["id"]} | | begin_transaction | Begins transaction | {} | | commit_transaction | Commits transaction | {} | | rollback_transaction | Rollbacks transaction | {} |

API Reference

Detailed Tool Schemas

list_tables

Description: Lists all database tables Parameters: None Return: List of table names

describe_table

Description: Shows complete table structure Parameters: ``json { "type": "object", "properties": { "table": { "type": "string", "description": "Name of the table to describe" } }, "required": ["table"] } `` Return: Table schema with columns, types and constraints

execute_select

Description: Executes a SELECT query (read-only) Parameters: ``json { "type": "object", "properties": { "query": { "type": "string", "description": "Valid SQL SELECT query" } }, "required": ["query"] } `` Validation: Query must start with "SELECT" (case insensitive) Return: Query result in JSON format

insert_data

Description: Inserts a new record into the table Parameters: ``json { "type": "object", "properties": { "table": { "type": "string", "description": "Table name" }, "data": { "type": "object", "description": "Object with data to insert", "additionalProperties": true } }, "required": ["table", "data"] } `` Return: ID of the inserted record

update_data

Description: Updates existing records Parameters: ``json { "type": "object", "properties": { "table": { "type": "string", "description": "Table name" }, "data": { "type": "object", "description": "Data to update", "additionalProperties": true }, "where": { "type": "string", "description": "WHERE condition to identify records" } }, "required": ["table", "data", "where"] } `` Return: Number of affected records

delete_data

Description: Removes records from the table Parameters: ``json { "type": "object", "properties": { "table": { "type": "string", "description": "Table name" }, "where": { "type": "string", "description": "WHERE condition to identify records" } }, "required": ["table", "where"] } `` Return: Number of removed records

count_rows

Description: Counts records in a table Parameters: ``json { "type": "object", "properties": { "table": { "type": "string", "description": "Table name" }, "where": { "type": "string", "description": "Optional WHERE condition" } }, "required": ["table"] } `` Return: Total number of records

add_column

Description: Adds a new column to an existing table Parameters: ``json { "type": "object", "properties": { "table": { "type": "string", "description": "Table name" }, "column": { "type": "string", "description": "Name of the new column" }, "type": { "type": "string", "description": "Data type of the column (e.g., 'TEXT', 'INTEGER', 'REAL', 'BLOB')" }, "nullable": { "type": "boolean", "description": "Whether the column can be NULL (default: true)", "default": true }, "default_value": { "type": "string", "description": "Default value for the column (optional)" } }, "required": ["table", "column", "type"] } `` Return: Confirmation of column addition

execute_ddl

Description: Executes safe DDL (Data Definition Language) commands Parameters: ``json { "type": "object", "properties": { "sql": { "type": "string", "description": "Valid DDL SQL command (ALTER TABLE, CREATE INDEX, etc.)" } }, "required": ["sql"] } `` Validation: Blocks DROP, TRUNCATE, DELETE commands. Allows only ALTER TABLE, CREATE INDEX, ADD CONSTRAINT Return: Confirmation of command execution

create_index

Description: Creates an index on a specific column Parameters: ``json { "type": "object", "properties": { "name": { "type": "string", "description": "Index name" }, "table": { "type": "string", "description": "Table name" }, "column": { "type": "string", "description": "Column name" }, "unique": { "type": "boolean", "description": "Whether it should be a unique index", "default": false } }, "required": ["name", "table", "column"] } `` Return: Confirmation of index creation

add_constraint

Description: Adds constraints (foreign key, check, unique) to tables Parameters: ``json { "type": "object", "properties": { "table": { "type": "string", "description": "Table name" }, "constraint_name": { "type": "string", "description": "Constraint name" }, "constraint_type": { "type": "string", "description": "Type: 'FOREIGN KEY', 'CHECK', 'UNIQUE'", "enum": ["FOREIGN KEY", "CHECK", "UNIQUE"] }, "columns": { "type": "array", "items": {"type": "string"}, "description": "Columns involved" }, "referenced_table": { "type": "string", "description": "Referenced table (for FK)" }, "referenced_columns": { "type": "array", "items": {"type": "string"}, "description": "Referenced columns (for FK)" }, "check_expression": { "type": "string", "description": "CHECK expression (for CHECK)" } }, "required": ["table", "constraint_name", "constraint_type", "columns"] } `` Return: Confirmation of constraint addition

begin_transaction

Description: Begins a new transaction Parameters: None Return: Confirmation of transaction start

commit_transaction

Description: Commits all operations in the current transaction Parameters: None Return: Confirmation of commit

rollback_transaction

Description: Cancels all operations in the current transaction Parameters: None Return: Confirmation of rollback

Development

}, "column": { "type": "string", "description": "Nome da coluna" }, "unique": { "type": "boolean", "description": "Se deve ser índice único", "default": false } }, "required": ["name", "table", "column"] } ``` Return: Confirmação da criação do índice

add_constraint

Descrição: Adiciona constraints (foreign key, check, unique) a tabelas Parâmetros: ``json { "type": "object", "properties": { "table": { "type": "string", "description": "Nome da tabela" }, "constraint_name": { "type": "string", "description": "Nome da constraint" }, "constraint_type": { "type": "string", "description": "Tipo: 'FOREIGN KEY', 'CHECK', 'UNIQUE'", "enum": ["FOREIGN KEY", "CHECK", "UNIQUE"] }, "columns": { "type": "array", "items": {"type": "string"}, "description": "Colunas envolvidas" }, "referenced_table": { "type": "string", "description": "Tabela referenciada (para FK)" }, "referenced_columns": { "type": "array", "items": {"type": "string"}, "description": "Colunas referenciadas (para FK)" }, "check_expression": { "type": "string", "description": "Expressão CHECK (para CHECK)" } }, "required": ["table", "constraint_name", "constraint_type", "columns"] } `` Return: Confirmação da adição da constraint

begin_transaction

Descrição: Inicia uma nova transação Parâmetros: Nenhum Return: Confirmação do início da transação

commit_transaction

Descrição: Confirma todas as operações da transação atual Parâmetros: Nenhum Return: Confirmação do commit

rollback_transaction

Descrição: Cancela todas as operações da transação atual Parâmetros: Nenhum Return: Confirmação do rollback

Development

For local development:

npm run dev  # Runs with tsx (hot reload)

Troubleshooting

"command not found" error

• Use absolute path in args in .vscode/mcp.json
• Example: C:/Users/Lucas Silva/projects/mcp-turso/dist/index.js

Permission error

• On first use, Copilot will ask for permission
• Click "Allow" or "Continue"

Tools don't appear

• Make sure npm run build was executed
• Restart VSCode completely
• Confirm the path in .vscode/mcp.json is correct
• Check logs in Output → MCP

Turso connection error

• Confirm TURSO_DATABASE_URL and TURSO_AUTH_TOKEN are correct
• Run turso auth token to generate a new token if needed

Available Scripts

• npm run build: Compiles TypeScript
• npm run dev: Runs in development mode
• npm start: Runs compiled version

Roadmap

Upcoming Features

• [ ] SQL transactions support
• [ ] Complex queries with JOIN
• [ ] Database backup and restore
• [ ] Optional web interface for administration
• [ ] Support for multiple Turso databases
• [ ] Integration with other MCP tools

Planned Improvements

• [ ] More rigorous schema validation
• [ ] Support for advanced data types
• [ ] Cache for frequent queries
• [ ] Structured logging
• [ ] Performance metrics

Additional Resources

MCP Documentation

• Official MCP Specification
• MCP Introduction
• MCP Server Examples

Turso

• Turso Documentation
• LibSQL SDK

Contributing

1. Fork the project
2. Create a branch: git checkout -b feature/name
3. Commit your changes
4. Open a Pull Request

License

MIT