avp-devlanvi-tabnews-mcp-server/README.md

Servidor MCP com ferramentas de saudação dinâmica e consulta à API do TabNews

# 🤝 Servidor MCP TabNews & Saudação

Um servidor **Model Context Protocol (MCP)** que implementa ferramentas de saudação personalizada e consulta à API do **TabNews** - a rede social brasileira de tecnologia.

## ✨ Funcionalidades

- 🌅 Saudações contextualizadas por horário (bom dia/tarde/noite)
- 📰 Consulta aos artigos mais recentes do TabNews
- 📅 Data e hora atuais formatadas em português brasileiro
- 🎯 Personalização com nome e ocasião
- 🤖 Compatível com qualquer cliente MCP

## 📦 Instalação

### Via NPX (Recomendado)

```bash
# Executar diretamente via npx
npx tabnews-mcp-server
```

### Via NPM Global

```bash
# Instalar globalmente
npm install -g tabnews-mcp-server

# Executar
tabnews-mcp-server
```

### Desenvolvimento Local

```bash
# Clonar o repositório
git clone https://github.com/seu-usuario/tabnews-mcp-server.git
cd tabnews-mcp-server

# Instalar dependências
npm install

# Executar
npm start
```

## 🛠️ Ferramentas Disponíveis

### 1. `saudacao_amistosa`

Gera uma saudação calorosa e personalizada com informações atuais.

**Parâmetros:**
- `nome` (obrigatório): Nome da pessoa para personalizar a saudação
- `ocasiao` (opcional): Contexto da saudação (padrão: "encontro")

**Exemplo de resposta:**
```
🌅 Bom dia, João!

É um prazer te encontrar neste meeting! 🤝

📅 Hoje é segunda-feira, 23 de dezembro de 2024
🕐 Agora são exatamente 09:15:32

Espero que você esteja tendo um dia maravilhoso! ✨
Como posso ajudá-lo(a) hoje? 😊
```

### 2. `consultar_tabnews`

Consulta os artigos mais recentes do TabNews e retorna informações detalhadas.

**Parâmetros:**
- `limite` (opcional): Número de artigos (1-100, padrão: 10)
- `pagina` (opcional): Página para paginação (padrão: 1)

**Exemplo de resposta:**
```
📰 **ARTIGOS DO TABNEWS** 📰

📊 **Página:** 1 | **Limite:** 10
🔗 **Total encontrado:** 10 artigos

═══════════════════════════════════════════════════

**1. Uma curiosidade sobre o bcrypt que não se fala muito**
🔗 **URL:** https://www.tabnews.com.br/gabolera/uma-curiosidade-sobre-o-bcrypt-que-nao-se-fala-muito
👤 **Autor:** @gabolera
📅 **Data:** 15/07/2025
💰 **TabCoins:** 15 | 💬 **Comentários:** 3

─────────────────────────────────────────────────────

✨ **Dados atualizados em:** 15/07/2025 17:30:00
🌐 **Fonte:** TabNews API (https://www.tabnews.com.br/api/v1/contents)
```

## 🚀 Como Usar

### 1. Executar o Servidor

```bash
# Via npx (mais simples)
npx tabnews-mcp-server

# Ou instalação local
npm start
```

### 2. Conectar um Cliente MCP

O servidor usa **STDIO transport**, conecte a qualquer cliente MCP:

```bash
# Configuração para Claude Desktop (claude_desktop_config.json)
{
  "mcpServers": {
    "tabnews-server": {
      "command": "npx",
      "args": ["tabnews-mcp-server"]
    }
  }
}
```

### 3. Exemplo de Uso Programático

```javascript
// Listar ferramentas disponíveis
const tools = await client.request({ method: "tools/list" });

// Executar saudação
const saudacao = await client.request({
  method: "tools/call",
  params: {
    name: "saudacao_amistosa",
    arguments: { nome: "Maria", ocasiao: "hackathon" }
  }
});

// Consultar TabNews
const artigos = await client.request({
  method: "tools/call",
  params: {
    name: "consultar_tabnews",
    arguments: { limite: 5, pagina: 1 }
  }
});
```

## 🏗️ Arquitetura

```mermaid
graph LR
    A[Cliente MCP] -->|STDIO| B[Servidor TabNews]
    B --> C[Ferramenta: saudacao_amistosa]
    B --> D[Ferramenta: consultar_tabnews]
    C --> E[Data/Hora Atual]
    D --> F[API TabNews]
    D --> G[Formatação de Artigos]
```

## 📋 Requisitos

- **Node.js** >= 18.0.0
- **@modelcontextprotocol/sdk** ^1.12.1
- Conexão com internet (para consultar TabNews)

## 🔧 Desenvolvimento

```bash
# Clonar o projeto
git clone https://github.com/seu-usuario/tabnews-mcp-server.git
cd tabnews-mcp-server

# Instalar dependências
npm install

# Executar em modo desenvolvimento
npm run dev

# Verificar sintaxe
npm test
```

## 🤝 Integrações Sugeridas

Este servidor pode ser integrado com:

- **Claude Desktop** via configuração MCP
- **IDEs** com suporte a MCP  
- **Chatbots** personalizados
- **Aplicações web** com clientes MCP
- **Ferramentas de linha de comando**
- **Dashboards** de conteúdo

## 🌐 API do TabNews

Este servidor utiliza a API pública do TabNews:
- **Endpoint:** `https://www.tabnews.com.br/api/v1/contents`
- **Documentação:** [TabNews API](https://www.tabnews.com.br/api)
- **Rate Limiting:** Respeita os limites da API

## 🐛 Logs e Debugging

O servidor registra informações no **stderr**:

```
🚀 Servidor MCP de Saudação e TabNews iniciado com sucesso!
💡 Ferramentas disponíveis:
   • saudacao_amistosa
   • consultar_tabnews
```

## 📄 Licença

MIT - Veja o arquivo LICENSE para detalhes.

## 🤝 Contribuições

Contribuições são bem-vindas! Por favor:

1. Faça um fork do projeto
2. Crie uma branch para sua feature
3. Faça commit das suas mudanças
4. Envie um pull request

---

*Desenvolvido com ❤️ usando o Model Context Protocol e a API do TabNews* 🇧🇷