MCPal

MCPal

Servidor MCP leve para notificações nativas de desktop com botões de ação, respostas de texto e ícones com reconhecimento de LLM.
Compatível com qualquer cliente MCP.

Uso

Adicione ao seu MCP Config manualmente:

// JSON
{
  "mcpServers": {
    "mcpal": {
      "command": "npx",
      "args": ["mcpal@latest"]
    }
  }
}

Ou TOML (Codex):

// TOML
[mcp_servers.mcpal]
command = "npx"
args = ["-y", "mcpal@latest"]

Codex CLI

Adicione o MCPal diretamente via CLI:

codex mcp add mcpal -- npx -y mcpal@latest

Claude Code

Adicione o MCPal diretamente via CLI:

# Project scope (current project only)
claude mcp add mcpal -- npx -y mcpal@latest

# User scope (available in all projects)
claude mcp add mcpal --scope user -- npx -y mcpal@latest

Configurando Notificações Proativas

O MCPal inclui instruções MCP integradas que informam aos clientes como usar as notificações. Para configurar quando seu assistente deve notificá-lo proativamente, adicione isto ao seu arquivo de instruções do cliente. Isso deve ser AGENTS.md ou CLAUDE.md dependendo do seu modelo:

## Post Task Completion Hook

ALWAYS use MCPal MCP tool (if available) to notify me when you finish any tasks (this includes reading files, investigating, coding). You should use this tool before you terminate conversations. Refer to tool instructions precisely to craft your response.

Personalize isso de acordo com suas preferências - alguns usuários querem atualizações frequentes, outros só querem notificações para decisões importantes.

Outros Clientes MCP

O MCPal funciona com qualquer cliente compatível com MCP (Cursor, VS Code com extensões MCP, etc.). A configuração varia por cliente - consulte a documentação do seu cliente para adicionar servidores MCP.

Ferramenta: send_notification

Envie notificações nativas com recursos opcionais.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
message	string	Sim	O texto do corpo da notificação
title	string	Não	O título da notificação (padrão: "MCPal")
actions	string[]	Não	Botões de ação (ex.: ["Yes", "No", "Maybe"])
dropdownLabel	string	Não	Rótulo para o menu suspenso de ações (obrigatório para múltiplas ações)
reply	boolean	Não	Habilitar entrada de resposta de texto

Exemplos

Notificação simples:

{
  "message": "Build complete!",
  "title": "CI/CD"
}

Com ações:

{
  "message": "Deploy to production?",
  "title": "Deployment",
  "actions": ["Deploy", "Cancel"],
  "dropdownLabel": "Choose"
}

Com resposta:

{
  "message": "What should I name this file?",
  "title": "Question",
  "reply": true
}

Você pode responder diretamente da notificação sem trocar de aplicativo:

Contrato de Resultado da Ferramenta

send_notification agora retorna um contrato duplo:

• Saída canônica de máquina via structuredContent (recomendado para análise)
• Saída de texto compatível com versões anteriores em content[0].text

Campos estruturados:

• status: "sent" ou "error"
• title?: Título da notificação
• message?: Mensagem realmente enviada após a sanitização
• response?: Resposta da notificação ("timeout", ação clicada, etc.)
• activationType?: Fonte de ativação ("replied", "actionClicked", etc.)
• reply?: Resposta livre do usuário
• error?: Mensagem de erro quando status é "error"
• sanitized?: true quando o MCPal precisou sanitizar ou truncar entradas

O texto legado ainda é baseado em linhas, mas cada valor é codificado em JSON em uma única linha para segurança do parser, por exemplo:

status: "sent"
title: "MCPal"
message: "Line 1\nLine 2"
response: "timeout"

Sanitização de Entrada

Antes da entrega, o MCPal aplica sanitização de melhor esforço para reduzir falhas de notificador/parser:

• Normalizar finais de linha: \r\n / \r -> \n
• Remover caracteres de controle inseguros (mantém \n e \t)
• Limites de truncamento:
  • title: 256 caracteres
  • message: 4000 caracteres
  • actions: máximo 3 itens, cada um com 64 caracteres
  • dropdownLabel: 64 caracteres

Ícones com Reconhecimento de LLM

O MCPal detecta qual cliente MCP está chamando a ferramenta e exibe o ícone apropriado nas notificações.

Cliente	Ícone
Claude Desktop / Claude Code / Opus	Logotipo Claude
Codex / OpenAI / ChatGPT	Logotipo OpenAI
Cursor	Logotipo Cursor
VS Code	Logotipo VS Code
Desconhecido	Sem ícone

Isso funciona por meio da identificação do cliente no protocolo MCP - cada cliente envia seu nome durante a inicialização.

Adicionando Novos Ícones de Cliente

Para adicionar suporte a um novo cliente LLM, adicione um PNG em src/assets/clients/ e atualize o mapeamento em src/notify.config.ts.

Especificações do Ícone:

Propriedade	Requisito
Formato	PNG com transparência (RGBA)
Dimensões	128×128 pixels
Tamanho do arquivo	<10KB (use pngquant para compressão)

# Optimize a new icon
convert input.png -resize 128x128 -background none -gravity center -extent 128x128 temp.png
pngquant --quality=65-80 --output src/assets/clients/newclient.png temp.png
rm temp.png

Ícone Personalizado do Aplicativo

O pacote inclui um ícone de notificação personalizado que substitui o ícone padrão do Terminal no desktop. Isso é configurado automaticamente durante a instalação por meio do script postinstall.

Permissões de Notificação

Após a primeira notificação, seu sistema pode solicitar que você permita notificações de "MCPal". Você pode gerenciar isso em:

Configurações do Sistema > Notificações > MCPal

Desenvolvimento

# Install dependencies
pnpm install

# Build (required after clone - sets up desktop notification app)
pnpm run build

# Type check
pnpm run typecheck

# Lint
pnpm run lint:fix

# Format
pnpm run format:fix

MCP Inspector

Teste o servidor MCP interativamente usando o inspetor oficial:

pnpx @modelcontextprotocol/inspector node dist/index.js

Isso abre uma interface web onde você pode:

• Visualizar as ferramentas disponíveis e seus esquemas
• Enviar notificações de teste com diferentes parâmetros
• Ver mensagens brutas do protocolo MCP

Solução de Problemas de Desenvolvimento Local

Se você executar uma compilação local diretamente de dist/index.js e as notificações não estiverem funcionando, certifique-se de que o ponto de entrada seja executável:

chmod +x dist/index.js

Testando Notificações

Teste o sistema de notificações diretamente sem executar o servidor MCP:

# Simple notification (default)
pnpm run test:notification

# With action buttons
pnpm run test:notification actions

# With reply input
pnpm run test:notification reply

# Run all tests
pnpm run test:notification all

Licença

Código: Licença MIT

Ícone e Marca MCPal: © 2025 Todos os Direitos Reservados. O logotipo e os designs de ícones do MCPal não podem ser usados sem permissão.