MCP Connect Database

Este projeto é um servidor MCP (Model Context Protocol) que fornece uma interface para conectar e consultar um banco de dados SQLite com informações de clientes. O servidor oferece ferramentas para listar, buscar e contar clientes através do protocolo MCP.

📋 Sobre o Projeto

O MCP Connect Database é um servidor que implementa o Model Context Protocol para fornecer acesso a dados de clientes armazenados em um banco SQLite. Ele oferece as seguintes funcionalidades:

Listar clientes: Exibe todos os clientes cadastrados no sistema
Quantidade de clientes: Retorna o total de clientes cadastrados
Buscar por origem: Filtra clientes ativos por origem (facebook, instagram, tiktok)
Quantidade por origem: Conta clientes ativos por origem específica
Métricas avançadas: Fornece análises detalhadas incluindo distribuição por origem e crescimento mensal

Estrutura dos Dados

Cada cliente possui os seguintes campos:

ID (auto-incremento)
Nome
Email (único)
Endereço (bairro, cidade, estado, CEP)
Status ativo/inativo
Origem (facebook, instagram, tiktok)
Data de criação e atualização

🚀 Como Executar

Pré-requisitos

Node.js: versão 16 ou superior (recomendado: 18+)
npm: versão 7 ou superior (ou yarn)
Claude Desktop: versão mais recente
Sistema Operacional: macOS, Windows ou Linux

Compatibilidade

✅ Claude Desktop: Totalmente compatível
✅ MCP SDK: v1.17.2+
✅ SQLite: v5.1.7+
✅ TypeScript: v5.9.2+

Instalação

Clone o repositório e navegue até o diretório:

cd mcp-connect-database

Instale as dependências:

npm install

Configuração do Banco de Dados

Execute o seed para criar a tabela e popular com dados de exemplo:

npm run seed

Este comando irá:

Criar a tabela clientes no arquivo mcp.sqlite
Inserir 50 clientes fictícios usando a biblioteca Faker

Compilação e Execução

Compile o projeto TypeScript:

npm run build

Execute o servidor:

npm start

O servidor será iniciado e ficará aguardando conexões via stdio para comunicação MCP.

🛠️ Scripts Disponíveis

npm run build: Compila o TypeScript e torna o servidor executável
npm start: Executa o servidor compilado
npm run seed: Cria a tabela e popula com dados de exemplo

📁 Estrutura do Projeto

mcp-connect-database/
├── src/
│   ├── server.ts      # Servidor MCP principal
│   └── helpers.ts     # Funções de acesso ao banco de dados
├── build/             # Arquivos compilados
├── seed.ts           # Script para popular o banco
├── mcp.sqlite        # Banco de dados SQLite
└── package.json      # Configurações do projeto
├── tsconfig.json     # Configuração do TypeScript
├── .gitignore        # Arquivos a serem ignorados pelo Git
├── README.md         # Documentação do projeto

🔧 Tecnologias Utilizadas

TypeScript: Linguagem principal
SQLite3: Banco de dados
Model Context Protocol SDK: Framework para servidor MCP
Faker.js: Geração de dados fictícios
Zod: Validação de esquemas

📖 Ferramentas MCP Disponíveis

Após executar o servidor, ele estará disponível para receber comandos MCP através de stdio. As ferramentas disponíveis são:

1. listar-clientes

Descrição: Lista todos os clientes cadastrados no sistema
Parâmetros: Nenhum
Retorno: Lista formatada com todos os clientes e suas informações

2. quantidade-clientes

Descrição: Retorna o total de clientes cadastrados
Parâmetros: Nenhum
Retorno: Número total de clientes no banco

3. buscar-clientes-por-origem

Descrição: Busca clientes ativos por origem específica
Parâmetros:
- origem (string): facebook, instagram ou tiktok
Retorno: Lista de clientes ativos da origem especificada

4. quantidade-clientes-ativos-por-origem

Descrição: Conta clientes ativos por origem específica
Parâmetros:
- origem (string): facebook, instagram ou tiktok
Retorno: Número de clientes ativos da origem especificada

5. obter-metricas-clientes

Descrição: Obtém métricas completas dos clientes
Parâmetros: Nenhum
Retorno: Objeto JSON com métricas detalhadas incluindo:
- Total de clientes
- Clientes ativos
- Distribuição por origem
- Crescimento mensal (últimos 12 meses)

💡 Exemplo de Uso

O servidor formatará as respostas de forma legível, incluindo emojis e formatação markdown para melhor visualização dos dados.

Exemplos de Respostas:

Listagem de Clientes:

📋 Lista de Clientes (50 encontrados)

1. **João Silva**
   📧 Email: joao.silva@email.com
   📍 Endereço: Centro, São Paulo - SP
   📮 CEP: 01234-567
   ✅ Ativo: Sim
   🏢 Origem: facebook
   📅 Criado em: 2024-01-15

Métricas de Clientes:

📊 Métricas de clientes: {
  "totalClientes": 50,
  "clientesAtivos": 42,
  "clientesPorOrigem": [
    {"origem": "facebook", "quantidade": 18},
    {"origem": "instagram", "quantidade": 16},
    {"origem": "tiktok", "quantidade": 8}
  ],
  "crescimentoMensal": [
    {"mes": "2024-01", "quantidade": 15},
    {"mes": "2023-12", "quantidade": 12}
  ]
}

🖥️ Configuração para Claude Desktop

Para usar este servidor MCP com o Claude Desktop, adicione a seguinte configuração ao arquivo de configuração do Claude:

macOS

Edite o arquivo ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-connect-database": {
      "command": "node",
      "args": ["/caminho/absoluto/para/mcp-connect-database/build/server.js"],
      "env": {}
    }
  }
}

Windows

Edite o arquivo %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-connect-database": {
      "command": "node",
      "args": ["C:\\caminho\\absoluto\\para\\mcp-connect-database\\build\\server.js"],
      "env": {}
    }
  }
}

Passos para Configuração:

Compile o projeto:
```
npm run build
```
Encontre o caminho absoluto do projeto:
```
pwd
```
Substitua /caminho/absoluto/para/mcp-connect-database pelo caminho real do seu projeto
Reinicie o Claude Desktop para carregar a nova configuração
Teste a conexão perguntando ao Claude para listar os clientes ou obter métricas

Exemplo de Uso no Claude Desktop:

Por favor, liste todos os clientes cadastrados no sistema.

Mostre as métricas dos clientes.

Busque clientes da origem "facebook".

🔧 Troubleshooting

Problemas Comuns:

Erro "Cannot find module":
- Certifique-se de que executou npm install e npm run build
- Verifique se o caminho no arquivo de configuração está correto
Claude Desktop não reconhece o servidor:
- Verifique se o arquivo claude_desktop_config.json está no local correto
- Reinicie completamente o Claude Desktop
- Verifique se a sintaxe JSON está correta (sem vírgulas extras)
Banco de dados não encontrado:
- Execute npm run seed para criar e popular o banco
- Certifique-se de que o arquivo mcp.sqlite existe no diretório raiz
Permissões no macOS/Linux:
```
chmod +x build/server.js
```

Logs de Debug:

Para verificar se o servidor está funcionando, você pode testá-lo diretamente:

# Teste direto do servidor
node build/server.js

🔄 Desenvolvimento

Para desenvolvimento, você pode usar:

# Executar em modo de desenvolvimento
npx ts-node src/server.ts

# Recriar dados de teste
npm run seed

# Executar com watch mode (reinicia automaticamente)
npx ts-node --watch src/server.ts

Estrutura de Desenvolvimento:

src/server.ts: Servidor MCP principal com definição das ferramentas
src/helpers.ts: Funções de acesso ao banco de dados SQLite
seed.ts: Script para popular o banco com dados de teste
build/: Diretório com arquivos compilados para produção

🤝 Contribuição

Contribuições são bem-vindas! Para contribuir:

Faça um fork do projeto
Crie uma branch para sua feature (git checkout -b feature/nova-funcionalidade)
Commit suas mudanças (git commit -am 'Adiciona nova funcionalidade')
Push para a branch (git push origin feature/nova-funcionalidade)
Abra um Pull Request

📄 Licença

Este projeto está sob a licença ISC. Veja o arquivo package.json para mais detalhes.

🆘 Suporte

Se você encontrar problemas ou tiver dúvidas:

Verifique a seção de Troubleshooting
Consulte a documentação do Model Context Protocol
Abra uma issue no repositório do projeto

SQLite Database