FastIntercom

Um servidor MCP de alto desempenho para analisar conversas do Intercom com acesso local rápido via cache e sincronização em segundo plano.

GitHubExperimente este MCPPatrocinado

Documentação

FastIntercom MCP Server

Fast Check

Servidor de alto desempenho do Model Context Protocol (MCP) para análise de conversas do Intercom. Fornece acesso local rápido às conversas do Intercom por meio de cache inteligente e sincronização em segundo plano.

Recursos

  • 🚀 Acesso Local Rápido: Tempos de resposta abaixo de 100ms para buscas de conversas
  • 🧠 Sincronização Inteligente: Atualizações em segundo plano acionadas por solicitações garantem dados atualizados
  • 💾 Armazenamento Eficiente: Armazenamento local baseado em SQLite (~2KB por conversa)
  • 🔍 Busca Poderosa: Períodos de tempo em linguagem natural e busca por texto
  • ⚡ Integração MCP: Integração direta com Claude Desktop e clientes MCP

Início Rápido

Instalação

# Clone and install
git clone <repository-url>
cd fast-intercom-mcp
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

Configuração

# Initialize with your Intercom credentials
fast-intercom-mcp init

# Check status
fast-intercom-mcp status

# Sync conversation history
fast-intercom-mcp sync --force --days 7

Integração com Claude Desktop

Adicione à sua configuração do Claude Desktop (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "fast-intercom-mcp": {
      "command": "fast-intercom-mcp",
      "args": ["start"],
      "env": {
        "INTERCOM_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Uso

Comandos CLI

fast-intercom-mcp status              # Show server status and statistics
fast-intercom-mcp sync                # Incremental sync of recent conversations  
fast-intercom-mcp sync --force --days 7  # Force sync last 7 days
fast-intercom-mcp start               # Start MCP server
fast-intercom-mcp logs                # View recent log entries
fast-intercom-mcp reset               # Reset all data

Ferramentas MCP

Depois de conectado ao Claude Desktop, você pode fazer perguntas como:

  • "Buscar conversas sobre cobrança nos últimos 7 dias"
  • "Mostrar conversas de clientes de ontem"
  • "Qual é o status do servidor FastIntercom?"
  • "Obter detalhes da conversa com ID 123456789"

Configuração

Variáveis de Ambiente

INTERCOM_ACCESS_TOKEN=your_token_here
FASTINTERCOM_LOG_LEVEL=INFO
FASTINTERCOM_MAX_SYNC_AGE_MINUTES=5
FASTINTERCOM_BACKGROUND_SYNC_INTERVAL=10

Arquivo de Configuração

Localizado em ~/.fast-intercom-mcp/config.json:

{
  "log_level": "INFO",
  "max_sync_age_minutes": 5,
  "background_sync_interval_minutes": 10,
  "initial_sync_days": 30
}

Arquitetura

Estratégia de Sincronização Inteligente

O FastIntercom usa uma estratégia sofisticada de cache:

  1. Resposta Imediata: Solicitações MCP retornam dados instantaneamente do cache local
  2. Sincronização em Segundo Plano: Períodos desatualizados acionam atualizações em segundo plano
  3. Gatilhos Inteligentes: O sistema aprende com padrões de solicitação para otimizar o tempo de sincronização
  4. Dados Atualizados: A próxima solicitação obtém dados atualizados da sincronização em segundo plano

Componentes

  • Banco de Dados: SQLite com esquema otimizado para buscas rápidas
  • Serviço de Sincronização: Serviço em segundo plano com lógica inteligente de atualização
  • Servidor MCP: Implementação do Model Context Protocol
  • Interface CLI: Ferramentas de linha de comando para gerenciamento e monitoramento

Desenvolvimento

Testes

Testes Rápidos

# Unit tests
pytest tests/

# Integration test (requires API key)
./scripts/run_integration_test.sh

# Docker test
./scripts/test_docker_install.sh

Testes Abrangentes

# Full unit test suite with coverage
pytest tests/ --cov=fast_intercom_mcp

# Integration test with performance report
./scripts/run_integration_test.sh --performance-report

# Docker clean install test
./scripts/test_docker_install.sh --with-api-test

# Performance benchmarking
./scripts/run_performance_test.sh

Integração CI/CD

  • Verificação Rápida: Executada em cada PR (testes unitários, linting, imports)
  • Teste de Integração: Acionamento manual/semanal com dados reais da API
  • Teste Docker: Em releases e validação de implantação

Para procedimentos detalhados de teste, consulte:

Desenvolvimento Local

# Install in development mode
pip install -e .

# Run with verbose logging
fast-intercom-mcp --verbose status

# Monitor logs in real-time
tail -f ~/.fast-intercom-mcp/logs/fast-intercom-mcp.log

Desempenho

Métricas Típicas de Desempenho

  • Tempo de Resposta: <100ms para consultas em cache
  • Eficiência de Armazenamento: ~2KB por conversa em média
  • Velocidade de Sincronização: 10-50 conversas/segundo
  • Uso de Memória: <100MB para o processo do servidor

Requisitos de Armazenamento

  • Workspace pequeno: 100-500 conversas, ~5-25 MB
  • Workspace médio: 1.000-5.000 conversas, ~50-250 MB
  • Workspace grande: 10.000+ conversas, ~500+ MB

Solução de Problemas

Problemas Comuns

Falha na Conexão

  • Verifique seu token de acesso do Intercom
  • Verifique as permissões do token (leitura de conversas é necessária)
  • Teste: curl -H "Authorization: Bearer YOUR_TOKEN" https://api.intercom.io/me

Banco de Dados Bloqueado

  • Pare qualquer processo FastIntercom em execução: ps aux | grep fast-intercom-mcp
  • Verifique o arquivo de log: ~/.fast-intercom-mcp/logs/fast-intercom-mcp.log

Servidor MCP Não Respondendo

  • Verifique a sintaxe JSON da configuração do Claude Desktop
  • Reinicie o Claude Desktop após alterações de configuração
  • Verifique se o comando fast-intercom-mcp está disponível no PATH

Modo de Depuração

fast-intercom-mcp --verbose start    # Enable verbose logging
export FASTINTERCOM_LOG_LEVEL=DEBUG  # Set debug level

Referência da API

Ferramentas MCP

search_conversations

Buscar conversas com filtros flexíveis.

Parâmetros:

  • query (string): Texto para buscar nas mensagens das conversas
  • timeframe (string): Período em linguagem natural ("últimos 7 dias", "este mês", etc.)
  • customer_email (string): Filtrar por e-mail específico do cliente
  • limit (integer): Número máximo de conversas a retornar (padrão: 50)

get_conversation

Obter detalhes completos de uma conversa específica.

Parâmetros:

  • conversation_id (string, obrigatório): ID da conversa no Intercom

get_server_status

Obter status e estatísticas do servidor.

Parâmetros: Nenhum

sync_conversations

Acionar sincronização manual de conversas.

Parâmetros:

  • force (boolean): Forçar sincronização completa mesmo se houver dados recentes

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de feature (git checkout -b feature/amazing-feature)
  3. Faça commit das suas alterações (git commit -m 'Add amazing feature')
  4. Envie para o branch (git push origin feature/amazing-feature)
  5. Abra um Pull Request

Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Suporte

  • Problemas: GitHub Issues
  • Documentação: Este README e a documentação de código inline
  • Logs: Verifique ~/.fast-intercom-mcp/logs/fast-intercom-mcp.log para obter informações detalhadas