Human-in-the-Loop Slack MCP Server

Permite que los asistentes de IA soliciten información y reciban respuestas de humanos a través de Slack.

GitHub
6
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Slack con Intervención Humana

Un servidor de Protocolo de Contexto de Modelo (MCP) que permite a los asistentes de IA solicitar información a humanos a través de Slack. Este servidor actúa como un puente entre los sistemas de IA y los expertos humanos, permitiendo que la IA haga preguntas y reciba respuestas a través de Slack cuando necesita conocimiento humano o aclaraciones.

Inicio Rápido con npx

Ejecuta directamente desde GitHub sin instalación:

npx github:trtd56/AskOnSlackMCP \
  --slack-bot-token "xoxb-your-bot-token" \
  --slack-app-token "xapp-your-app-token" \
  --slack-channel-id "C1234567890" \
  --slack-user-id "U1234567890"

Ejemplo con Claude Desktop

Agrega a tu configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "slack-human": {
      "command": "npx",
      "args": [
        "github:trtd56/AskOnSlackMCP",
        "--slack-bot-token", "xoxb-your-actual-token",
        "--slack-app-token", "xapp-your-actual-token", 
        "--slack-channel-id", "C1234567890",
        "--slack-user-id", "U1234567890"
      ]
    }
  }
}

Características

  • 🤖 Servidor compatible con MCP para integración con asistentes de IA
  • 💬 Integración en tiempo real con Slack mediante conexión WebSocket en Modo Socket
  • 🧵 Conversaciones basadas en hilos para mantener el contexto
  • ⏱️ Tiempo de espera de 60 segundos para respuestas humanas
  • 📢 Menciones de usuarios (@username) para notificaciones
  • 🔍 Capacidades integrales de depuración y registro
  • 🔐 Manejo seguro de tokens
  • 🚀 Inicialización dinámica de manejadores para un inicio más rápido
  • ⚡ Optimizado para detección instantánea de respuestas con arquitectura basada en eventos

Requisitos Previos

  1. Configuración de la App de Slack

    • Crea una nueva app de Slack en https://api.slack.com/apps
    • Habilita el Modo Socket en la configuración de tu app
    • Genera un Token a Nivel de App con el alcance connections:write
    • Instala la app en tu espacio de trabajo

  2. Alcances del Token del Bot

    • chat:write - Enviar mensajes
    • channels:read - Acceder a información del canal
    • users:read - Acceder a información del usuario

  3. Modo Socket

    • Habilita el Modo Socket en la configuración de tu app
    • Esto es necesario para que la app reciba eventos en tiempo real

  4. Suscripciones a Eventos

    • Habilita la API de Eventos
    • Suscríbete a eventos del bot:
      • message.channels - Mensajes en canales públicos
      • message.groups - Mensajes en canales privados
      • message.im - Mensajes directos (opcional)
    • Guarda los cambios y reinstala la app en tu espacio de trabajo

Instalación (Opcional)

Si deseas instalar localmente en lugar de usar npx:

  1. Clona el repositorio:
git clone https://github.com/trtd56/AskOnSlackMCP.git
cd AskOnSlackMCP
  1. Instala las dependencias:
npm install
  1. Compila el código TypeScript:
npm run build

Configuración

Toda la configuración se pasa mediante argumentos de línea de comandos:

  • --slack-bot-token - Token OAuth del Bot de Usuario (xoxb-...)
  • --slack-app-token - Token a Nivel de App para Modo Socket (xapp-...)
  • --slack-channel-id - ID del canal donde operará el bot
  • --slack-user-id - ID del usuario a mencionar al hacer preguntas
  • --log-level - (Opcional) Nivel de registro (predeterminado: INFO)

Uso

Modo de Desarrollo

Ejecuta con recarga automática:

npm run dev

Modo de Producción

Compila y ejecuta:

npm run build
npm start

Con Cliente MCP (Usando npx)

Configura tu cliente MCP para usar este servidor directamente desde GitHub:

{
  "mcpServers": {
    "human-in-the-loop-slack": {
      "command": "npx",
      "args": [
        "github:trtd56/AskOnSlackMCP",
        "--slack-bot-token", "xoxb-your-token",
        "--slack-app-token", "xapp-your-token",
        "--slack-channel-id", "C1234567890",
        "--slack-user-id", "U1234567890"
      ]
    }
  }
}

Con Cliente MCP (Instalación Local)

Si has instalado localmente:

{
  "mcpServers": {
    "human-in-the-loop-slack": {
      "command": "node",
      "args": [
        "/path/to/AskOnSlackMCP/dist/index.js",
        "--slack-bot-token", "xoxb-your-token",
        "--slack-app-token", "xapp-your-token",
        "--slack-channel-id", "C1234567890",
        "--slack-user-id", "U1234567890"
      ]
    }
  }
}

Herramientas Disponibles

ask_on_slack

Herramienta principal para hacer preguntas a humanos a través de Slack.

Parámetros:

  • question (cadena): La pregunta para hacer al humano. Sé específico y proporciona contexto.

Ejemplo:

{
  "tool": "ask_on_slack",
  "arguments": {
    "question": "What is the API endpoint for the production server?"
  }
}

Notas de Uso:

  • El bot mencionará al usuario especificado en el canal de Slack
  • El humano tiene 60 segundos para responder en un hilo
  • La herramienta devolverá la respuesta del humano o expirará después de 60 segundos

Desarrollo

Scripts

  • npm run build - Compilar TypeScript
  • npm run dev - Ejecutar con recarga automática
  • npm start - Ejecutar código compilado
  • npm test - Ejecutar pruebas con Vitest
  • npm run test:ci - Ejecutar pruebas con cobertura
  • npm run lint - Ejecutar ESLint
  • npm run format - Formatear código con Prettier
  • npm run clean - Limpiar artefactos de compilación

Estructura del Proyecto

src/
├── index.ts                  # Main MCP server implementation
├── bin.ts                    # Binary entry point for npx execution
├── human.ts                  # Abstract Human interface
├── slack-client.ts           # Socket Mode Slack implementation
└── types.ts                  # TypeScript type definitions

tests/
├── human.test.ts             # Human abstract class tests
├── index.test.ts             # CLI argument parsing tests
├── slack-client.test.ts      # Slack client tests
└── types.test.ts             # Type definition tests

Pruebas

El proyecto utiliza Vitest para las pruebas. Las pruebas se encuentran en el directorio tests/.

Para ejecutar las pruebas:

npm test              # Run tests in watch mode
npm run test:ci       # Run tests once with coverage

CI/CD

El proyecto utiliza GitHub Actions para integración y despliegue continuos.

  • Flujo de Trabajo de CI (ci.yml): Se ejecuta en cada push y pull request

    • Pruebas en Node.js 18.x, 20.x y 22.x
    • Ejecuta linting y verificación de tipos
    • Genera informes de cobertura de código
    • Compila el proyecto

  • Flujo de Trabajo de Lanzamiento (release.yml): Se ejecuta en etiquetas de versión

    • Compila y prueba el proyecto
    • Crea lanzamientos de GitHub
    • Publica en npm (requiere el secreto NPM_TOKEN)

Solución de Problemas

  1. Problemas de Conexión

    • Verifica que todos los tokens sean correctos
    • Comprueba que el bot esté invitado al canal
    • Asegúrate de que el Modo Socket esté habilitado en tu app de Slack

  2. No se Recibe Respuesta

    • Verifica que el ID del usuario sea correcto (formato: U1234567890)
    • Asegúrate de que el usuario responda en el hilo del mensaje, no en el canal principal
    • Comprueba que el bot tenga permiso para leer mensajes en el canal

  3. Errores de Autenticación

    • El token del bot debe comenzar con xoxb-
    • El token de la app debe comenzar con xapp-
    • Regenera los tokens si es necesario
    • Verifica que el bot tenga los alcances requeridos: chat:write, channels:read, users:read

  4. Optimización del Rendimiento

    • El servidor utiliza arquitectura basada en eventos para detección instantánea de respuestas
    • La conexión WebSocket asegura la entrega de mensajes en tiempo real
    • Registros detallados de tiempo disponibles con el prefijo [TIMING] para depuración

Licencia

MIT