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:

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

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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**:

{ "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](https://modelcontextprotocol.io/specification)
- [MCP Introduction](https://modelcontextprotocol.io/introduction)
- [MCP Server Examples](https://github.com/modelcontextprotocol/examples)

### Turso
- [Turso Documentation](https://docs.turso.tech/)
- [LibSQL SDK](https://github.com/tursodatabase/libsql)

## 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