MCPal

MCPal

Servidor MCP ligero para notificaciones nativas de escritorio con botones de acción, respuestas de texto e iconos conscientes de LLM.
Compatible con cualquier cliente MCP.

Uso

Añádelo a tu configuración MCP manualmente:

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

O TOML (Codex):

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

Codex CLI

Añade MCPal directamente mediante la CLI:

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

Claude Code

Añade MCPal directamente mediante la 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

Configuración de Notificaciones Proactivas

MCPal incluye instrucciones MCP integradas que indican a los clientes cómo usar las notificaciones. Para configurar cuándo tu asistente debe notificarte de forma proactiva, añade esto a tu archivo de instrucciones del cliente. Esto debería ser AGENTS.md o CLAUDE.md según tu 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.

Personaliza esto según tus preferencias: algunos usuarios quieren actualizaciones frecuentes, otros solo quieren notificaciones para decisiones importantes.

Otros Clientes MCP

MCPal funciona con cualquier cliente compatible con MCP (Cursor, VS Code con extensiones MCP, etc.). La configuración varía según el cliente; consulta la documentación de tu cliente para añadir servidores MCP.

Herramienta: send_notification

Envía notificaciones nativas con funciones opcionales.

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
message	string	Sí	El texto del cuerpo de la notificación
title	string	No	El título de la notificación (por defecto: "MCPal")
actions	string[]	No	Botones de acción (p. ej., ["Yes", "No", "Maybe"])
dropdownLabel	string	No	Etiqueta para el menú desplegable de acciones (obligatorio para múltiples acciones)
reply	boolean	No	Habilitar entrada de respuesta de texto

Ejemplos

Notificación simple:

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

Con acciones:

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

Con respuesta:

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

Puedes responder directamente desde la notificación sin cambiar de aplicación:

Contrato de Resultado de la Herramienta

send_notification ahora devuelve un contrato dual:

• Salida canónica de máquina mediante structuredContent (recomendado para análisis)
• Salida de texto compatible con versiones anteriores en content[0].text

Campos estructurados:

• status: "sent" o "error"
• title?: Título de la notificación
• message?: Mensaje realmente enviado después de la sanitización
• response?: Respuesta de la notificación ("timeout", acción pulsada, etc.)
• activationType?: Fuente de activación ("replied", "actionClicked", etc.)
• reply?: Respuesta de texto libre del usuario
• error?: Mensaje de error cuando status es "error"
• sanitized?: true cuando MCPal tuvo que sanitizar o truncar entradas

El texto heredado sigue basado en líneas, pero cada valor está codificado en JSON en una sola línea para seguridad del analizador, por ejemplo:

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

Sanitización de Entradas

Antes de la entrega, MCPal aplica sanitización de mejor esfuerzo para reducir fallos del notificador/analizador:

• Normalizar finales de línea: \r\n / \r -> \n
• Eliminar caracteres de control no seguros (conserva \n y \t)
• Límites de truncamiento:
  • title: 256 caracteres
  • message: 4000 caracteres
  • actions: máximo 3 elementos, cada uno de 64 caracteres
  • dropdownLabel: 64 caracteres

Iconos Conscientes de LLM

MCPal detecta qué cliente MCP está llamando a la herramienta y muestra el icono apropiado en las notificaciones.

Cliente	Icono
Claude Desktop / Claude Code / Opus	Logotipo de Claude
Codex / OpenAI / ChatGPT	Logotipo de OpenAI
Cursor	Logotipo de Cursor
VS Code	Logotipo de VS Code
Desconocido	Sin icono

Esto funciona mediante la identificación del cliente del protocolo MCP: cada cliente envía su nombre durante la inicialización.

Añadir Nuevos Iconos de Cliente

Para añadir soporte para un nuevo cliente LLM, añade un PNG a src/assets/clients/ y actualiza la asignación en src/notify.config.ts.

Especificaciones del Icono:

Propiedad	Requisito
Formato	PNG con transparencia (RGBA)
Dimensiones	128×128 píxeles
Tamaño de archivo	<10KB (usa pngquant para compresión)

# 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

Icono de Aplicación Personalizado

El paquete incluye un icono de notificación personalizado que reemplaza el icono de Terminal predeterminado en el escritorio. Esto se configura automáticamente durante la instalación mediante el script postinstall.

Permisos de Notificación

Después de la primera notificación, tu sistema puede pedirte que permitas notificaciones de "MCPal". Puedes gestionar esto en:

Configuración del Sistema > Notificaciones > MCPal

Desarrollo

# 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

Inspector MCP

Prueba el servidor MCP de forma interactiva usando el inspector oficial:

pnpx @modelcontextprotocol/inspector node dist/index.js

Esto abre una interfaz web donde puedes:

• Ver las herramientas disponibles y sus esquemas
• Enviar notificaciones de prueba con diferentes parámetros
• Ver mensajes crudos del protocolo MCP

Solución de Problemas de Desarrollo Local

Si ejecutas una compilación local directamente desde dist/index.js y las notificaciones no funcionan, asegúrate de que el punto de entrada sea ejecutable:

chmod +x dist/index.js

Prueba de Notificaciones

Prueba el sistema de notificaciones directamente sin ejecutar el 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

Licencia

Código: Licencia MIT

Icono y Marca de MCPal: © 2025 Todos los derechos reservados. El logotipo y los diseños de iconos de MCPal no pueden usarse sin permiso.