Human-in-the-Loop Slack MCP Server

Permite que assistentes de IA solicitem informações e recebam respostas de humanos via Slack.

GitHub
6
Experimente este MCPPatrocinado

Documentação

Human-in-the-Loop Slack MCP Server

Um servidor Model Context Protocol (MCP) que permite que assistentes de IA solicitem informações de humanos via Slack. Este servidor atua como uma ponte entre sistemas de IA e especialistas humanos, permitindo que a IA faça perguntas e receba respostas através do Slack quando precisa de conhecimento humano ou esclarecimentos.

Quick Start com npx

Execute diretamente do GitHub sem instalação:

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"

Exemplo com Claude Desktop

Adicione à sua configuração do 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"
      ]
    }
  }
}

Recursos

  • 🤖 Servidor compatível com MCP para integração com assistentes de IA
  • 💬 Integração em tempo real com Slack via conexão WebSocket do Socket Mode
  • 🧵 Conversas baseadas em threads para manter o contexto
  • ⏱️ Timeout de 60 segundos para respostas humanas
  • 📢 Menções de usuário (@username) para notificações
  • 🔍 Recursos abrangentes de depuração e registro de logs
  • 🔐 Manuseio seguro de tokens
  • 🚀 Inicialização dinâmica de handlers para inicialização mais rápida
  • ⚡ Otimizado para detecção instantânea de respostas com arquitetura orientada a eventos

Pré-requisitos

  1. Configuração do App Slack

    • Crie um novo app Slack em https://api.slack.com/apps
    • Ative o Socket Mode nas configurações do seu app
    • Gere um Token de Nível de App com escopo connections:write
    • Instale o app no seu workspace

  2. Escopos do Token do Bot

    • chat:write - Enviar mensagens
    • channels:read - Acessar informações do canal
    • users:read - Acessar informações do usuário

  3. Socket Mode

    • Ative o Socket Mode nas configurações do seu app
    • Isso é necessário para que o app receba eventos em tempo real

  4. Assinaturas de Eventos

    • Ative a API de Eventos
    • Assine os eventos do bot:
      • message.channels - Mensagens em canais públicos
      • message.groups - Mensagens em canais privados
      • message.im - Mensagens diretas (opcional)
    • Salve as alterações e reinstale o app no seu workspace

Instalação (Opcional)

Se você quiser instalar localmente em vez de usar npx:

  1. Clone o repositório:
git clone https://github.com/trtd56/AskOnSlackMCP.git
cd AskOnSlackMCP
  1. Instale as dependências:
npm install
  1. Compile o código TypeScript:
npm run build

Configuração

Toda a configuração é passada via argumentos de linha de comando:

  • --slack-bot-token - Token OAuth do Bot (xoxb-...)
  • --slack-app-token - Token de Nível de App para Socket Mode (xapp-...)
  • --slack-channel-id - ID do canal onde o bot operará
  • --slack-user-id - ID do usuário a ser mencionado ao fazer perguntas
  • --log-level - (Opcional) Nível de log (padrão: INFO)

Uso

Modo de Desenvolvimento

Execute com hot-reload:

npm run dev

Modo de Produção

Compile e execute:

npm run build
npm start

Com Cliente MCP (Usando npx)

Configure seu cliente MCP para usar este servidor diretamente do 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"
      ]
    }
  }
}

Com Cliente MCP (Instalação Local)

Se você instalou 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"
      ]
    }
  }
}

Ferramentas Disponíveis

ask_on_slack

Ferramenta principal para fazer perguntas a humanos via Slack.

Parâmetros:

  • question (string): A pergunta a ser feita ao humano. Seja específico e forneça contexto.

Exemplo:

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

Notas de Uso:

  • O bot mencionará o usuário especificado no canal do Slack
  • O humano tem 60 segundos para responder em uma thread
  • A ferramenta retornará a resposta do humano ou expirará após 60 segundos

Desenvolvimento

Scripts

  • npm run build - Compilar TypeScript
  • npm run dev - Executar com hot-reload
  • npm start - Executar código compilado
  • npm test - Executar testes com Vitest
  • npm run test:ci - Executar testes com cobertura
  • npm run lint - Executar ESLint
  • npm run format - Formatar código com Prettier
  • npm run clean - Limpar artefatos de build

Estrutura do Projeto

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

Testes

O projeto usa Vitest para testes. Os testes estão localizados no diretório tests/.

Para executar os testes:

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

CI/CD

O projeto usa GitHub Actions para integração contínua e implantação.

  • Workflow de CI (ci.yml): Executa em cada push e pull request

    • Testes em Node.js 18.x, 20.x e 22.x
    • Executa linting e verificação de tipos
    • Gera relatórios de cobertura de código
    • Compila o projeto

  • Workflow de Release (release.yml): Executa em tags de versão

    • Compila e testa o projeto
    • Cria releases do GitHub
    • Publica no npm (requer o segredo NPM_TOKEN)

Solução de Problemas

  1. Problemas de Conexão

    • Verifique se todos os tokens estão corretos
    • Verifique se o bot foi convidado para o canal
    • Certifique-se de que o Socket Mode está ativado no seu app Slack

  2. Nenhuma Resposta Recebida

    • Verifique se o ID do usuário está correto (formato: U1234567890)
    • Certifique-se de que o usuário responda na thread da mensagem, não no canal principal
    • Verifique se o bot tem permissão para ler mensagens no canal

  3. Erros de Autenticação

    • O token do bot deve começar com xoxb-
    • O token do app deve começar com xapp-
    • Regenere os tokens se necessário
    • Verifique se o bot tem os escopos necessários: chat:write, channels:read, users:read

  4. Otimização de Desempenho

    • O servidor usa arquitetura orientada a eventos para detecção instantânea de respostas
    • A conexão WebSocket garante entrega de mensagens em tempo real
    • Logs detalhados de tempo disponíveis com o prefixo [TIMING] para depuração

Licença

MIT