# 🔌 MCP MySQL Server

**Servidor MCP (Model Context Protocol) para MySQL** - Módulo reutilizável que permite integração nativa entre Cursor IDE e qualquer banco de dados MySQL.

---

## 📋 O que é isso?

Este é um servidor MCP que permite que o Cursor (e outras ferramentas que suportam MCP) executem queries SQL diretamente no seu banco MySQL local, facilitando:

- ✅ Análise de estrutura de tabelas
- ✅ Consultas de dados em tempo real
- ✅ Geração de código baseado no schema
- ✅ Debugging de queries
- ✅ Inspeção de relacionamentos

---

## 🚀 Instalação Rápida

### 1. Instalar Dependências

```bash
cd mcp-mysql-server
npm install
```

### 2. Configurar Credenciais

```bash
# Windows
copy env.example .env

# Linux/Mac
cp env.example .env
```

Edite o arquivo `.env` com suas credenciais:

```env
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=sua_senha_aqui
MYSQL_DATABASE=food
```

### 3. Testar Conexão

```bash
npm start
```

Se aparecer `[MCP MySQL] Servidor MCP iniciado com sucesso`, está funcionando! ✅

---

## ⚙️ Configuração no Cursor

### Windows

Edite o arquivo de configuração do Cursor:

**Caminho:** `%APPDATA%\Cursor\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json`

Ou acesse via Cursor: `Settings` → `Extensions` → `MCP Servers`

Adicione:

```json
{
  "mcpServers": {
    "mysql-food": {
      "command": "node",
      "args": ["G:/IA/Estudos/mcp-mysql-server/src/index.js"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "SuaSenhaAqui",
        "MYSQL_DATABASE": "food"
      }
    }
  }
}
```

### Linux/Mac

**Caminho:** `~/.config/Cursor/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json`

```json
{
  "mcpServers": {
    "mysql-food": {
      "command": "node",
      "args": ["/caminho/completo/mcp-mysql-server/src/index.js"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "SuaSenhaAqui",
        "MYSQL_DATABASE": "food"
      }
    }
  }
}
```

### 4. Reiniciar Cursor

Feche e abra o Cursor completamente para carregar o servidor MCP.

---

## 🛠️ Ferramentas Disponíveis

### 1. `mysql_execute_query`

Executa qualquer query SQL.

**Exemplo:**
```sql
SELECT * FROM combos WHERE COD = 9;
```

**Parâmetros:**
- `query` (string): Query SQL
- `params` (array, opcional): Parâmetros para prepared statements

**Uso com prepared statements:**
```sql
SELECT * FROM users WHERE id = ? AND status = ?
Params: [1, "active"]
```

---

### 2. `mysql_list_tables`

Lista todas as tabelas do banco de dados.

**Retorna:**
```json
{
  "success": true,
  "database": "food",
  "tableCount": 15,
  "tables": ["combos", "detcombos", "produtos", ...]
}
```

---

### 3. `mysql_describe_table`

Mostra a estrutura completa de uma tabela.

**Parâmetros:**
- `table_name` (string): Nome da tabela

**Exemplo:**
```javascript
table_name: "combos"
```

**Retorna:**
```json
{
  "success": true,
  "table": "combos",
  "columns": [
    {
      "Field": "COD",
      "Type": "int",
      "Null": "NO",
      "Key": "PRI",
      "Default": null,
      "Extra": "auto_increment"
    },
    ...
  ]
}
```

---

### 4. `mysql_show_databases`

Lista todos os databases disponíveis no servidor.

**Retorna:**
```json
{
  "success": true,
  "databases": ["food", "mysql", "information_schema", ...]
}
```

---

### 5. `mysql_table_info`

Retorna informações completas: colunas, índices e contagem de registros.

**Parâmetros:**
- `table_name` (string): Nome da tabela

**Retorna:**
```json
{
  "success": true,
  "table": "combos",
  "rowCount": 25,
  "columns": [...],
  "indexes": [...]
}
```

---

## 🎯 Exemplos de Uso

### No Chat do Cursor

Depois de configurado, você pode pedir ao assistente:

```
"Liste todas as tabelas do banco food"
"Mostre a estrutura da tabela combos"
"Execute: SELECT * FROM detcombos WHERE CODCOMBO = 9"
"Quantos registros tem na tabela movimento?"
```

O assistente vai usar automaticamente as ferramentas MCP!

---

## 🔒 Segurança

### ✅ Boas Práticas

1. **Nunca commite o arquivo `.env`**
   - Ele está no `.gitignore` por segurança

2. **Use usuário com permissões limitadas**
   ```sql
   CREATE USER 'cursor_readonly'@'localhost' IDENTIFIED BY 'senha_segura';
   GRANT SELECT ON food.* TO 'cursor_readonly'@'localhost';
   FLUSH PRIVILEGES;
   ```

3. **Conexão apenas local**
   - O servidor só aceita conexões de `localhost`

4. **Prepared Statements**
   - Use sempre parâmetros em vez de concatenar strings

---

## 🐛 Troubleshooting

### Erro: "MYSQL_DATABASE não está configurado"

**Solução:** Crie o arquivo `.env` a partir do `env.example`

### Erro: "Access denied for user"

**Solução:** Verifique usuário e senha no `.env`

### Erro: "connect ECONNREFUSED"

**Solução:** 
1. Verifique se o MySQL está rodando
2. Confirme a porta (padrão: 3306)

### Cursor não encontra o servidor

**Solução:**
1. Verifique o caminho absoluto no `args`
2. Reinicie o Cursor completamente
3. Verifique logs em: `View` → `Output` → `MCP`

### Teste manual da conexão

```bash
# Testar se o MySQL está respondendo
mysql -u root -p -h localhost -P 3306

# Testar o servidor MCP
cd mcp-mysql-server
node src/index.js
```

---

## 📂 Estrutura do Projeto

```
mcp-mysql-server/
├── src/
│   └── index.js          # Servidor MCP principal
├── package.json          # Dependências e scripts
├── env.example           # Template de configuração
├── .gitignore           # Arquivos ignorados pelo Git
└── README.md            # Este arquivo
```

---

## 🔄 Usar em Múltiplos Projetos

### Opção 1: Instalar Globalmente

```bash
cd mcp-mysql-server
npm link
```

Depois em qualquer projeto:
```bash
npm link @local/mcp-mysql-server
```

### Opção 2: Referenciar Diretamente

No Cursor, aponte para o caminho absoluto do `index.js`:

```json
"args": ["G:/IA/Estudos/mcp-mysql-server/src/index.js"]
```

### Opção 3: Múltiplos Bancos

Crie múltiplas configurações no Cursor:

```json
{
  "mcpServers": {
    "mysql-food": {
      "command": "node",
      "args": ["G:/IA/Estudos/mcp-mysql-server/src/index.js"],
      "env": {
        "MYSQL_DATABASE": "food",
        ...
      }
    },
    "mysql-ecommerce": {
      "command": "node",
      "args": ["G:/IA/Estudos/mcp-mysql-server/src/index.js"],
      "env": {
        "MYSQL_DATABASE": "ecommerce",
        ...
      }
    }
  }
}
```

---

## 📦 Dependências

- `@modelcontextprotocol/sdk` - SDK oficial do MCP
- `mysql2` - Driver MySQL para Node.js (com suporte a Promises)
- `dotenv` - Gerenciamento de variáveis de ambiente

---

## 🤝 Contribuindo

Sinta-se livre para melhorar este módulo:

1. Adicionar mais ferramentas
2. Melhorar tratamento de erros
3. Adicionar cache de queries
4. Implementar rate limiting
5. Adicionar logs estruturados

---

## 📝 Licença

MIT - Use livremente em seus projetos!

---

## 🎓 Recursos Adicionais

- [Documentação MCP](https://modelcontextprotocol.io/)
- [MySQL2 Docs](https://github.com/sidorares/node-mysql2)
- [Cursor IDE](https://cursor.sh/)

---

## ✨ Autor

Criado para facilitar o desenvolvimento com IA e bancos de dados MySQL.

**Versão:** 1.0.0  
**Node.js:** >= 18.0.0  
**Testado em:** Node v22.12.0