🌟 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:

# 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:

git clone <url-do-repositorio>
cd mcp-server

2. Instale as dependências:

npm install

3. Execute o servidor:

npm start

🛠️ Uso

Como Servidor MCP Standalone

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

node index.js

Integração com Clientes MCP

Claude Desktop / Cursor (via NPX)

Adicione ao arquivo de configuração MCP:

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

Claude Desktop / Cursor (instalação local)

Para desenvolvimento local:

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

Cliente MCP Personalizado (via NPX)

import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

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

Cliente MCP Personalizado (local)

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:

{
  "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

# 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

// 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

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

# 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

# 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

# Primeiro login
npm login

# Publicar
npm publish

5. Verificação

# Teste via npx
npx greeting-mcp-server

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

6. Atualizações

# 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 para detalhes.

🔗 Links Úteis

• Model Context Protocol Specification
• MCP SDK Documentation
• Claude MCP Integration

Feito com ❤️ e muito café ☕