greeting-mcp-server/README.md

🌟 Servidor MCP de saudação amistosa com suporte a múltiplos idiomas e dados dinâmicos de data/hora

# 🌟 Servidor MCP de Saudação Amistosa

Um servidor Model Context Protocol (MCP) simples e amigável que oferece saudações personalizadas com informações dinâmicas de data e hora.

## 📋 Sobre

Este servidor MCP implementa uma única ferramenta chamada `saudacao_amistosa` que:
- 🕒 Mostra data e hora atual
- 🌍 Suporta múltiplos idiomas (Português, Inglês, Espanhol)
- 👤 Permite personalização com nome do usuário
- 🎯 Detecta automaticamente o período do dia (manhã, tarde, noite)
- ✨ Retorna saudações calorosas e motivacionais

## 🚀 Instalação e Uso

### 📦 Via NPX (Recomendado)

A forma mais fácil de usar o servidor é diretamente via npx, sem necessidade de instalação:

```bash
# Executar diretamente (sempre a versão mais recente)
npx greeting-mcp-server

# Ou instalar globalmente
npm install -g greeting-mcp-server
greeting-mcp-server
```

### 🔧 Instalação Local para Desenvolvimento

#### Pré-requisitos
- Node.js 18+ (recomendado) ou 16+ (com avisos)
- npm ou yarn

#### Passos

1. **Clone ou baixe o projeto:**
```bash
git clone <url-do-repositorio>
cd mcp-server
```

2. **Instale as dependências:**
```bash
npm install
```

3. **Execute o servidor:**
```bash
npm start
```

## 🛠️ Uso

### Como Servidor MCP Standalone

O servidor roda via STDIO e pode ser conectado a qualquer cliente MCP compatível:

```bash
node index.js
```

### Integração com Clientes MCP

#### Claude Desktop / Cursor (via NPX)
Adicione ao arquivo de configuração MCP:

```json
{
  "mcpServers": {
    "greeting-server": {
      "command": "npx",
      "args": ["greeting-mcp-server"]
    }
  }
}
```

#### Claude Desktop / Cursor (instalação local)
Para desenvolvimento local:

```json
{
  "mcpServers": {
    "greeting-server": {
      "command": "node",
      "args": ["/caminho/para/mcp-server/index.js"]
    }
  }
}
```

#### Cliente MCP Personalizado (via NPX)
```javascript
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["greeting-mcp-server"]
});
```

#### Cliente MCP Personalizado (local)
```javascript
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "node",
  args: ["./index.js"]
});
```

## 🔧 Ferramenta Disponível

### `saudacao_amistosa`

**Descrição:** Retorna uma saudação calorosa e amistosa com data e hora atual

**Parâmetros:**
- `nome` (opcional): Nome da pessoa para personalizar a saudação
- `idioma` (opcional): Idioma da saudação
  - `"pt"` - Português (padrão)
  - `"en"` - Inglês  
  - `"es"` - Espanhol

**Exemplo de uso:**
```json
{
  "name": "saudacao_amistosa",
  "arguments": {
    "nome": "Maria",
    "idioma": "pt"
  }
}
```

**Exemplo de resposta:**
```
🌟 Olá Maria! Boa tarde! 

🕒 Hoje é quinta-feira, 21 de dezembro de 2023 e são 14:30:25.

✨ Espero que você esteja tendo um dia maravilhoso! As possibilidades são infinitas, e estou aqui para te ajudar a conquistar grandes coisas! 🚀

🎯 Que tal começarmos algo incrível juntos?
```

## 🌍 Exemplos por Idioma

### Português (pt)
```
🌟 Olá João! Boa manhã! 

🕒 Hoje é sexta-feira, 22 de dezembro de 2023 e são 09:15:30.

✨ Espero que você esteja tendo um dia maravilhoso! As possibilidades são infinitas, e estou aqui para te ajudar a conquistar grandes coisas! 🚀

🎯 Que tal começarmos algo incrível juntos?
```

### Inglês (en)
```
🌟 Hello Alice! Good morning! 

🕒 Today is Friday, December 22, 2023 and it's 9:15:30 AM.

✨ Hope you're having a wonderful day! The possibilities are endless, and I'm here to help you achieve great things! 🚀
```

### Espanhol (es)
```
🌟 ¡Hola Carlos! ¡Buenas tarde! 

🕒 Hoy es viernes, 22 de diciembre de 2023 y son las 14:15:30.

✨ ¡Espero que tengas un día maravilloso! Las posibilidades son infinitas, ¡y estoy aquí para ayudarte a lograr grandes cosas! 🚀
```

## 🏗️ Arquitetura

### Estrutura do Projeto
```
mcp-server/
├── index.js          # Servidor MCP principal
├── package.json       # Dependências e scripts
└── README.md          # Esta documentação
```

### Dependências
- `@modelcontextprotocol/sdk` - SDK oficial do MCP
- `zod` - Validação de schemas TypeScript-first

### Fluxo de Funcionamento
1. **Inicialização:** Servidor MCP é iniciado via STDIO
2. **Descoberta:** Cliente lista ferramentas disponíveis (`tools/list`)
3. **Execução:** Cliente chama `saudacao_amistosa` (`tools/call`)
4. **Processamento:** 
   - Validação dos parâmetros com Zod
   - Obtenção da data/hora atual
   - Detecção do período do dia
   - Geração da saudação no idioma escolhido
5. **Resposta:** Retorna saudação formatada

## 🎛️ Configuração

### Variáveis de Ambiente
Nenhuma variável de ambiente é necessária - o servidor funciona out-of-the-box.

### Customização
Para modificar as saudações ou adicionar novos idiomas, edite a seção `switch (idioma)` no arquivo `index.js`.

## 🧪 Teste Manual

### Teste via Node.js REPL
```bash
# Terminal 1: Iniciar servidor
node index.js

# Terminal 2: Testar com cliente MCP ou enviar JSON-RPC via stdin
```

### Teste com Cliente MCP de Exemplo
```javascript
// Exemplo de teste rápido
const result = await client.callTool("saudacao_amistosa", {
  nome: "Desenvolvedor",
  idioma: "pt"
});
console.log(result.content[0].text);
```

## 🚨 Solução de Problemas

### Erro: "Unsupported engine"
**Causa:** Versão do Node.js abaixo de 18
**Solução:** Atualize para Node.js 18+ ou ignore os avisos (funcionará com limitações)

### Erro: "Module not found"
**Causa:** Dependências não instaladas
**Solução:** Execute `npm install`

### Servidor não responde
**Causa:** Problema na comunicação STDIO
**Solução:** Verifique se o cliente MCP está configurado corretamente

## 📝 Scripts Disponíveis

```bash
npm start       # Inicia o servidor
npm run dev     # Inicia com auto-reload (Node 18+)
```

## 📦 Publicação no NPM

Para publicar seu servidor MCP no npm e disponibilizá-lo via npx:

### 1. Preparação
```bash
# Certifique-se de ter uma conta no npm
npm whoami

# Se não tiver, crie uma conta
npm adduser
```

### 2. Configuração
- Atualize as informações no `package.json`:
  - `name`: Nome único no npm
  - `version`: Versão semântica (1.0.0, 1.0.1, etc.)
  - `author.email`: Seu email
  - `homepage`, `repository`, `bugs`: URLs do seu repositório

### 3. Teste Local
```bash
# Teste o pacote localmente
npm pack
# Isso criará um arquivo .tgz para verificação

# Teste a instalação
npm install -g ./greeting-mcp-server-1.0.0.tgz
```

### 4. Publicação
```bash
# Primeiro login
npm login

# Publicar
npm publish
```

### 5. Verificação
```bash
# Teste via npx
npx greeting-mcp-server

# Ou instalar globalmente
npm install -g greeting-mcp-server
```

### 6. Atualizações
```bash
# Incrementar versão
npm version patch  # 1.0.0 -> 1.0.1
npm version minor  # 1.0.0 -> 1.1.0
npm version major  # 1.0.0 -> 2.0.0

# Publicar nova versão
npm publish
```

## 🤝 Contribuindo

1. Fork do projeto
2. Crie uma branch para sua feature (`git checkout -b feature/nova-saudacao`)
3. Commit suas mudanças (`git commit -am 'Adiciona nova saudação'`)
4. Push para a branch (`git push origin feature/nova-saudacao`)
5. Abra um Pull Request

## 📄 Licença

Este projeto está licenciado sob a MIT License - veja o arquivo [LICENSE](LICENSE) para detalhes.

## 🔗 Links Úteis

- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [MCP SDK Documentation](https://github.com/modelcontextprotocol/typescript-sdk)
- [Claude MCP Integration](https://docs.anthropic.com/claude/docs/mcp)

---

**Feito com ❤️ e muito café ☕**