# 🚀 MCP MySQL Server

Um servidor MCP (Model Context Protocol) robusto e profissional para interação com bancos MySQL através de agentes de IA. Este projeto demonstra implementação avançada de protocolos MCP com gerenciamento inteligente de conexões e ferramentas especializadas para análise de bancos de dados.

## ✨ Características Principais

- 🔐 **Gerenciamento Inteligente de Conexões** - Configuração dinâmica via tools MCP
- 🛡️ **Segurança Robusta** - Apenas operações SELECT permitidas, validação de entrada com Zod
- 🔄 **Múltiplos Transportes** - Suporte a stdio e SSE para diferentes cenários de uso
- 📊 **Ferramentas Especializadas** - Análise de schema, foreign keys e estrutura de tabelas
- 🚀 **Configuração Automática** - Descoberta inteligente de configurações MySQL
- 💡 **Fallback Interativo** - Solicita configuração quando necessário

## 🛠️ Ferramentas Disponíveis

### 🔧 Configuração de Conexão
- **`mysql_configure_connection`** - Configuração dinâmica de conexão MySQL
- **`mysql_auto_configure_connection`** - Descoberta automática de configuração
- **`mysql_get_connection_status`** - Status atual da conexão
- **`mysql_check_connection`** - Teste de conectividade

### 📊 Operações no Banco
- **`mysql_list_tables`** - Listagem de todas as tabelas
- **`mysql_get_table_info`** - Estrutura detalhada de tabelas
- **`mysql_execute_query`** - Execução de queries SELECT
- **`mysql_analyze_schema`** - Análise completa do schema
- **`mysql_list_foreign_keys`** - Mapeamento de relacionamentos

## 🚀 Instalação e Configuração

### 1. Clone e Instale
```bash
git clone https://github.com/efeabio/mcp-mysql-server.git
cd mcp-mysql-server
npm install
npm run build
```

### 2. Configure o Cursor

Adicione a seguinte configuração no seu arquivo `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "mysql": {
      "command": "/caminho/para/seu/projeto/start-mcp.sh"
    }
  }
}
```

**⚠️ Importante:** Substitua `/caminho/para/seu/projeto/` pelo caminho real onde você clonou o repositório.

### 3. Configure o start-mcp.sh

Edite o arquivo `start-mcp.sh` e altere o caminho para corresponder à sua instalação:

```bash
#!/bin/bash
node /caminho/para/seu/projeto/dist/index.js
```

### 4. Configuração da Conexão MySQL

O projeto oferece **3 formas** de configurar a conexão MySQL:

#### 🔧 **Configuração Manual via Tool (Recomendado)**
Use a tool `mysql_configure_connection` para configurar dinamicamente:

```typescript
await mysql_configure_connection({
  host: "localhost",
  port: 3306,
  user: "root",
  password: "sua_senha",
  database: "seu_banco"
});
```

#### 📁 **Configuração via Arquivo**
Crie um arquivo `config.json` na raiz do projeto:

```json
{
  "mysql": {
    "host": "localhost",
    "port": 3306,
    "user": "root",
    "password": "sua_senha",
    "database": "seu_banco"
  }
}
```

#### 🔍 **Descoberta Automática**
Use a tool `mysql_auto_configure_connection` para tentar descobrir configuração automaticamente.

## 🎯 Casos de Uso

### 🔍 Análise de Banco de Dados
- **Auditoria de Schema** - Mapeamento completo de estruturas
- **Análise de Relacionamentos** - Identificação de foreign keys
- **Documentação Automática** - Geração de documentação de banco

### 🤖 Integração com Agentes de IA
- **Consultas Inteligentes** - Execução de queries via linguagem natural
- **Exploração Interativa** - Descoberta de dados sem conhecimento prévio
- **Análise Automática** - Insights sobre estrutura e relacionamentos

### 🚀 Desenvolvimento e DevOps
- **Migração de Dados** - Análise de estrutura antes de migrações
- **Debugging** - Investigação de problemas de banco
- **Monitoramento** - Verificação de integridade de dados

## 🔒 Segurança e Boas Práticas

- ✅ **Operações Somente Leitura** - Apenas SELECT é permitido
- ✅ **Validação de Entrada** - Schema validation com Zod
- ✅ **Teste de Conexão** - Verificação antes de aceitar configurações
- ✅ **Configuração via Tools** - Interface segura para configuração
- ✅ **Isolamento de Conexões** - Gerenciamento seguro de múltiplas conexões

## 🚀 Execução

```bash
# Modo stdio (padrão para MCP)
./start-mcp.sh

# Modo SSE para desenvolvimento
node dist/index.js sse
```

## 📚 Exemplos de Uso

### Configuração Inicial
```typescript
// Configure conexão dinamicamente
await mysql_configure_connection({
  host: "localhost",
  port: 3306,
  user: "root",
  password: "sua_senha",
  database: "test"
});

// Verifique se funcionou
await mysql_check_connection();

// Explore o banco
await mysql_list_tables();
```

### Análise de Schema
```typescript
// Análise completa
await mysql_analyze_schema();

// Relacionamentos
await mysql_list_foreign_keys();

// Estrutura específica
await mysql_get_table_info("users");
```

### Consultas Personalizadas
```typescript
// Execute queries SELECT
await mysql_execute_query("SELECT COUNT(*) as total FROM users");

// Análise de dados
await mysql_execute_query("SELECT table_name, table_rows FROM information_schema.tables");
```

## 🏗️ Arquitetura

O projeto utiliza uma arquitetura modular com:

- **MCP SDK** - Implementação do protocolo Model Context Protocol
- **MySQL2** - Driver nativo e performático para MySQL
- **TypeScript** - Tipagem estática e desenvolvimento robusto
- **Zod** - Validação de schemas e entrada de dados
- **Express** - Suporte opcional para transporte SSE

## 🔧 Desenvolvimento

```bash
# Build do projeto
npm run build

# Execução em modo desenvolvimento
npm start

# Execução com SSE
npm start sse
```

## 📄 Licença

MIT License - veja o arquivo LICENSE para detalhes.

## 🤝 Contribuição

Contribuições são bem-vindas! Este projeto demonstra implementação profissional de protocolos MCP e serve como referência para desenvolvimento de servidores MCP robustos.

---

**Desenvolvido com ❤️ para demonstrar expertise em protocolos MCP, integração com MySQL e desenvolvimento de ferramentas para agentes de IA.**