MCP POC

MCP POC - Servidor Model Context Protocol

Um servidor MCP (Model Context Protocol) desenvolvido em Node.js/TypeScript com arquitetura modular compatível com Claude Desktop.

O que é MCP?

O Model Context Protocol (MCP) é um protocolo aberto desenvolvido pela Anthropic que permite que modelos de IA interajam de forma segura com ferramentas e fontes de dados externas. Pense no MCP como o "USB-C" das integrações de IA: um padrão único que conecta muitos serviços.

Componentes do MCP:

• Servidores MCP: Atuam como pontes para APIs, bancos de dados ou código
• Clientes MCP: Utilizam o protocolo para interagir com os servidores
• Hosts MCP: Sistemas que gerenciam a comunicação (como Claude Desktop)

Características

Este servidor MCP inclui três ferramentas de exemplo:

1. greeting - Gera saudações personalizadas em espanhol (formal/informal)
2. calculator - Realiza operações matemáticas básicas (adição, subtração, multiplicação, divisão)
3. get_current_datetime - Obtém a data e hora atuais em diferentes formatos

Instalação

🚀 Opção 1: A partir do NPM (Recomendado)

# Instalar globalmente
npm install -g @sokardys/mcp-poc

# O usar npx (sin instalación)
npx sokardys-mcp-poc

💻 Opção 2: Desenvolvimento local

git clone <tu-repositorio>
cd mcp-poc
npm install
npm run build

3. Configurar Claude Desktop

Edite o arquivo de configuração do Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Adicione a configuração do servidor:

Para instalação via NPM:

{
  "mcpServers": {
    "mcp-poc": {
      "command": "npx",
      "args": ["@sokardys/mcp-poc@latest"],
      "env": {
      }
    }
  }
} 

Para desenvolvimento local:

{
  "mcpServers": {
    "mcp-poc": {
      "command": "node",
      "args": [
        "/ruta/completa/a/tu/proyecto/mcp-poc/build/index.js"
      ]
    }
  }
}

Importante: Para desenvolvimento local, altere /ruta/completa/a/tu/proyecto/mcp-poc/ pelo caminho real onde você clonou o projeto.

4. Reiniciar Claude Desktop

Feche e reabra o Claude Desktop para carregar a nova configuração.

Uso

Uma vez configurado, você pode usar as ferramentas no Claude Desktop:

Exemplos de uso:

• Saudação: "Cumprimente a Maria de forma formal" → Usa greeting
• Cálculo: "Calcule 15 × 8" → Usa calculator
• Data: "Que horas são?" → Usa get_current_datetime

Ferramentas disponíveis:

Ferramenta	Descrição	Parâmetros
greeting	Saudações personalizadas	name (string), formal (boolean)
calculator	Operações matemáticas	operation (add/subtract/multiply/divide), a (number), b (number)
get_current_datetime	Data e hora atuais	format (short/long/iso)

Scripts disponíveis

# Compilar el proyecto
npm run build

# Modo desarrollo (recompilación automática)
npm run dev

# Ejecutar directamente (después de compilar)
npm start

# Inspeccionar el servidor MCP
npm run inspector

# Testing
npm test                # Ejecutar todos los tests
npm run test:watch      # Tests en modo watch
npm run test:ui         # Interfaz visual de tests
npm run test:coverage   # Tests con cobertura de código

Testes

Este projeto inclui um conjunto completo de testes usando Vitest e mcpgod:

Executar testes

# Tests básicos
npm test

# Tests en modo watch (reejecutar al cambiar código)
npm run test:watch

# Interfaz visual para tests
npm run test:ui

# Tests con reporte de cobertura
npm run test:coverage

O que é testado

Os testes validam:

✅ Lista de ferramentas - Verifica se todas as ferramentas estão disponíveis ✅ Ferramenta greeting - Formatos formal e informal, nomes personalizados ✅ Calculadora - Adição, subtração, multiplicação, divisão com validação Zod ✅ Tratamento de erros - Divisão por zero, parâmetros ausentes, McpError apropriados ✅ Data e hora - Diferentes formatos (curto, longo, ISO), fusos horários ✅ Validação de entrada - Schemas Zod, tipos incorretos, parâmetros obrigatórios ✅ Arquitetura modular - Separação resolver/usecase, orquestrador central

Testes manuais com mcpgod

# Listar herramientas disponibles
npx mcpgod tools build/index.js

# Probar herramientas específicas
npx mcpgod tool build/index.js greeting name="Ana" formal=true
npx mcpgod tool build/index.js calculator operation="add" a=15 b=25
npx mcpgod tool build/index.js get_current_datetime format="long"

Recursos adicionais

• Documentação oficial do MCP
• Servidor de referência da Anthropic
• SDK TypeScript
• Vitest - Framework de testes
• mcpgod - CLI para MCP

Licença

MIT - consulte o arquivo LICENSE para mais detalhes.

---

Aproveite para construir ferramentas incríveis com MCP! 🚀