X (Twitter)

Servidor MCP do X (Twitter)

Uma implementação abrangente de servidor Model Context Protocol para integração com a API do X (Twitter), com automação profissional de fluxos de trabalho, tratamento aprimorado de erros e documentação em tempo real.

🚀 Recursos

• 53 Ferramentas no Total - 33 da API do Twitter + 20 capacidades aprimoradas de pesquisa do SocialData.tools
• Análises Avançadas - Análise de threads, mapeamento de redes, análise de sentimentos, rastreamento viral
• Ignora Restrições da API - Ferramentas de pesquisa aprimoradas funcionam sem requisitos do nível Pro
• Tratamento Profissional de Erros - Orientação clara de upgrade e tratamento elegante de chaves de API
• 5 Prompts de Fluxo de Trabalho - Modelos de automação pré-construídos
• 6 Recursos Dinâmicos - Documentação e status da API em tempo real
• Conformidade Total com MCP - Suporte a ferramentas, prompts e recursos

📋 Início Rápido

Pré-requisitos

• Node.js 18+
• npm ou yarn
• Credenciais da API do X (Twitter) (nível Basic mínimo - US$ 200/mês)

Instalação Local

1. Clone e Instale

   git clone <repository-url>
   cd twitter-server
   npm install
   

2. Configuração do Ambiente

   cp .env.example .env
   # Edit .env with your credentials
   

   Variáveis de Ambiente Obrigatórias:

   # Twitter API credentials (Required)
   X_API_KEY=your_api_key_here
   X_API_SECRET=your_api_secret_here  
   X_ACCESS_TOKEN=your_access_token_here
   X_ACCESS_TOKEN_SECRET=your_access_token_secret_here
   
   # SocialData.tools API key (Optional - enables enhanced research tools)
   SOCIALDATA_API_KEY=your_socialdata_api_key_here
   SOCIALDATA_BASE_URL=https://api.socialdata.tools  # Optional, uses default if not set
   

3. Compile e Execute

   npm run build
   npm start
   

4. Teste o Servidor

   # Test with JSON-RPC calls
   source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js
   
   # Test specific tool
   source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "getUserInfo", "arguments": {"username": "elonmusk"}}}' | node dist/index.js
   

🔑 Configuração da API do X (Twitter)

Credenciais Obrigatórias

Adicione estas ao seu arquivo .env:

X_API_KEY=your_api_key_here
X_API_SECRET=your_api_secret_here  
X_ACCESS_TOKEN=your_access_token_here
X_ACCESS_TOKEN_SECRET=your_access_token_secret_here

Níveis de Acesso à API

Nível	Custo	Ferramentas Funcionais	Ferramentas Limitadas
Basic	US$ 200/mês	18/22 ferramentas	searchTweets, getHashtagAnalytics
Pro	US$ 5.000/mês	Todas as 22 ferramentas	Nenhuma

🛠️ Ferramentas Disponíveis (53 no Total)

🐦 Ferramentas da API do Twitter (33 ferramentas)

✅ Operações de Tweet (Todas Funcionais)

• postTweet - Publicar novos tweets
• getTweetById - Recuperar tweets específicos
• replyToTweet - Responder a tweets
• deleteTweet - Excluir seus tweets

✅ Engajamento (Todas Funcionais)

• likeTweet / unlikeTweet - Curtir/descurtir tweets
• retweet / undoRetweet - Retweetar/desfazer retweets
• getRetweets - Obter usuários que retweetaram

✅ Gerenciamento de Usuários (Maioria Funcional)

• getUserInfo - Obter perfis de usuários ✅
• getUserTimeline - Obter tweets de usuários ✅
• followUser / unfollowUser - Seguir/deixar de seguir usuários ✅
• getFollowers - Obter seguidores ⚠️ (403 - requer permissões especiais)
• getFollowing - Obter seguidos ⚠️ (403 - requer permissões especiais)

✅ Gerenciamento de Listas (Todas Funcionais)

• createList - Criar listas do X (Twitter)
• getUserLists - Obter listas do usuário
• addUserToList / removeUserFromList - Gerenciar membros de listas
• getListMembers - Obter membros de listas

⚠️ Pesquisa e Análises (Limitadas)

• searchTweets - Pesquisar tweets (requer nível Pro - US$ 5.000/mês)
• getHashtagAnalytics - Análises de hashtags (requer nível Pro)
• getLikedTweets - Obter tweets curtidos (problema de acesso à API)

🔍 Pesquisa Aprimorada do SocialData.tools (20 ferramentas)

Observação: Essas ferramentas lidam elegantemente com chaves de API ausentes, exibindo instruções úteis de configuração

🔎 Pesquisa Avançada (6 ferramentas)

• advancedTweetSearch - Consultas complexas com operadores, ignora restrições de nível da API
• historicalTweetSearch - Acesso a tweets históricos além dos limites padrão da API
• trendingTopicsSearch - Análise de tendências em tempo real e descoberta de conteúdo popular
• bulkUserProfiles - Análise de perfil de múltiplos usuários em solicitações únicas
• userGrowthAnalytics - Análise de padrões de crescimento de usuários ao longo do tempo
• userInfluenceMetrics - Pontuação de engajamento e cálculos de influência

🧵 Análise de Threads e Conversas (3 ferramentas)

• getFullThread - Reconstruir threads completas do Twitter com métricas de engajamento
• getConversationTree - Mapear estrutura de conversas, incluindo respostas e citações
• getThreadMetrics - Análise de desempenho de threads e distribuição de engajamento

🌐 Análise de Redes (3 ferramentas)

• findMutualConnections - Descobrir conexões mútuas por meio de interações
• analyzeFollowerDemographics - Padrões de seguidores e análise demográfica
• mapInfluenceNetwork - Mapeamento de influência e análise de força de conexões

📈 Análises Avançadas (3 ferramentas)

• getHashtagTrends - Rastreamento de desempenho de hashtags ao longo do tempo com análise de tendências
• analyzeSentiment - Análise de sentimentos com rastreamento de frequência de palavras-chave
• trackVirality - Padrões de propagação viral e análise de velocidade de engajamento

📱 Mensagens Diretas e Moderação (5 ferramentas)

• Várias ferramentas de moderação de usuários e mensagens diretas

🔑 Configuração de Chaves de API

API do Twitter (Obrigatória)

Obtenha estas no Portal do Desenvolvedor do Twitter:

X_API_KEY=your_api_key_here
X_API_SECRET=your_api_secret_here  
X_ACCESS_TOKEN=your_access_token_here
X_ACCESS_TOKEN_SECRET=your_access_token_secret_here

API do SocialData.tools (Opcional)

Habilita 20 ferramentas de pesquisa aprimoradas que ignoram as limitações da API do Twitter:

1. Cadastre-se em SocialData.tools
2. Obtenha sua chave de API no painel
3. Adicione ao arquivo .env:

   SOCIALDATA_API_KEY=your_socialdata_api_key_here
   

Sem a chave de API do SocialData: As ferramentas de pesquisa aprimoradas exibirão instruções úteis de configuração em vez de erros.

🧪 Testando a Integração com o SocialData.tools

Teste as Ferramentas de Pesquisa Aprimoradas

# Test advanced tweet search (bypasses Twitter API Pro tier requirement)
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "advancedTweetSearch", "arguments": {"query": "AI OR machine learning", "maxResults": 5}}}' | node dist/index.js

# Test sentiment analysis
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "analyzeSentiment", "arguments": {"query": "ChatGPT", "sampleSize": 20}}}' | node dist/index.js

# Test user influence metrics
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "userInfluenceMetrics", "arguments": {"username": "openai"}}}' | node dist/index.js

# Test thread analysis
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "getFullThread", "arguments": {"tweetId": "1234567890123456789"}}}' | node dist/index.js

Teste Sem Chave de API

# These will show helpful setup instructions instead of errors
SOCIALDATA_API_KEY="" echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "advancedTweetSearch", "arguments": {"query": "test"}}}' | node dist/index.js

🆚 Quando Usar Quais Ferramentas

Comparação entre API do Twitter e SocialData.tools

Caso de Uso	Ferramenta da API do Twitter	Alternativa do SocialData.tools	Vantagem
Pesquisa Básica	searchTweets ⚠️ (nível Pro US$ 5 mil/mês)	advancedTweetSearch ✅	Ignora restrições da API
Análise de Usuários	getUserInfo ✅	userInfluenceMetrics ✅	Análises aprimoradas
Dados Históricos	Limitado pelo nível da API	historicalTweetSearch ✅	Acesso a tweets mais antigos
Análise de Sentimentos	Não disponível	analyzeSentiment ✅	Pontuação de sentimentos integrada
Análise de Threads	Reconstrução manual	getFullThread ✅	Mapeamento automatizado de threads
Mapeamento de Redes	Não disponível	mapInfluenceNetwork ✅	Análise de conexões
Tendências de Hashtags	getHashtagAnalytics ⚠️ (nível Pro)	getHashtagTrends ✅	Sem restrições de nível

Fluxo de Trabalho Recomendado

1. Comece com as ferramentas da API do Twitter para publicação, engajamento e operações básicas
2. Use o SocialData.tools para pesquisa, análises e insights avançados
3. Combine ambos para automação e análise abrangentes do Twitter

🎯 Prompts de Fluxo de Trabalho do MCP

Nosso servidor inclui 5 modelos profissionais de fluxo de trabalho:

1. Composição de Tweets (compose-tweet)

Orientação interativa para criar tweets envolventes com hashtags, menções e mídia.

2. Relatórios de Análises (analytics-report)

Fluxo de trabalho abrangente de análises do X (Twitter) para insights de negócios.

3. Estratégia de Conteúdo (content-strategy)

Fluxos de trabalho de planejamento estratégico de conteúdo e engajamento de público.

4. Gerenciamento de Comunidade (community-management)

Melhores práticas de atendimento ao cliente e engajamento comunitário.

5. Pesquisa de Hashtags (hashtag-research)

Pesquisa de hashtags específicas do setor e análise de tendências.

📊 Recursos Dinâmicos

Informações em tempo real acessíveis via MCP:

• Limites de Taxa da API - Monitoramento de uso ao vivo
• Status do Nível de Acesso - Capacidades atuais do nível
• Relatório de Status das Ferramentas - Ferramentas funcionais vs. limitadas
• Guia de Início Rápido - Documentação de introdução
• Modelos de Fluxo de Trabalho - Exemplos de automação pré-construídos
• Dados de Perfil de Usuário - Informações dinâmicas de usuários (chamadas de API ao vivo)

🧪 Testes

Testes Manuais

# Test working tools
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "postTweet", "arguments": {"text": "Hello from MCP!"}}}' | node dist/index.js

# Test user info
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "getUserInfo", "arguments": {"username": "elonmusk"}}}' | node dist/index.js

# Test limited tools (will show upgrade guidance)
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "searchTweets", "arguments": {"query": "MCP"}}}' | node dist/index.js

Resumo dos Resultados dos Testes

• 18 Ferramentas Funcionais no nível Basic
• 4 Ferramentas Limitadas por nível/permissões da API
• Mensagens de erro profissionais com orientação de upgrade
• Toda a funcionalidade principal operacional

🔧 Exemplos de Integração

Cliente MCP (Cursor/Claude)

{
  "mcpServers": {
    "x-twitter": {
      "command": "node",
      "args": ["/path/to/twitter-server/dist/index.js"],
      "env": {
        "X_API_KEY": "your_api_key",
        "X_API_SECRET": "your_api_secret", 
        "X_ACCESS_TOKEN": "your_access_token",
        "X_ACCESS_TOKEN_SECRET": "your_access_token_secret"
      }
    }
  }
}

JSON-RPC Direto

# Always source environment first
source .env

# List all tools
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js

# Call specific tool
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "toolName", "arguments": {"param": "value"}}}' | node dist/index.js

📝 Documentação da API

Operações de Tweet

postTweet

{
  "text": "Your tweet content (up to 280 characters)"
}

getTweetById

{
  "tweetId": "1234567890123456789",
  "tweetFields": ["created_at", "public_metrics", "author_id"]
}

replyToTweet

{
  "tweetId": "1234567890123456789", 
  "text": "Your reply content"
}

Operações de Usuário

getUserInfo

{
  "username": "elonmusk",
  "fields": ["description", "public_metrics", "profile_image_url"]
}

followUser

{
  "username": "target_username"
}

Engajamento

likeTweet

{
  "tweetId": "1234567890123456789"
}

retweet

{
  "tweetId": "1234567890123456789"
}

🚨 Tratamento de Erros

Mensagens de Erro Profissionais

Nosso tratamento aprimorado de erros fornece:

• Explicações claras do nível da API para ferramentas limitadas
• Informações de preço de upgrade (nível Pro de US$ 5.000/mês)
• Links diretos de upgrade para o Portal do Desenvolvedor do Twitter
• Sugestões de soluções alternativas

Exemplo de resposta de erro:

{
  "error": "This endpoint requires X (Twitter) API Pro tier access ($5,000/month). Visit https://developer.twitter.com/en/docs/twitter-api/getting-started/about-twitter-api#v2-access-leve to upgrade your access level."
}

📁 Estrutura do Projeto

twitter-server/
├── src/
│   ├── handlers/          # API endpoint handlers
│   ├── prompts.ts        # MCP workflow prompts  
│   ├── resources.ts      # Dynamic MCP resources
│   └── index.ts          # Main MCP server
├── dist/                 # Compiled JavaScript
├── scripts/              # Documentation & PRD
└── package.json

🔄 Desenvolvimento

Compilação e Execução

npm run build    # Compile TypeScript
npm start        # Start production server
npm run dev      # Development mode with watch

Adicionando Novas Ferramentas

1. Adicione a função de manipulação no arquivo src/handlers/ apropriado
2. Registre a ferramenta em src/index.ts
3. Adicione a documentação a este README
4. Teste com chamadas JSON-RPC

Contribuindo

1. Siga os padrões de código existentes
2. Adicione tratamento adequado de erros com mensagens profissionais
3. Teste com cenários de sucesso e falha
4. Atualize a documentação

📋 Limitações Conhecidas

Restrições do Nível da API

• searchTweets: Requer nível Pro (US$ 5.000/mês)
• getHashtagAnalytics: Requer nível Pro
• getFollowers/getFollowing: Requer permissões especiais (erros 403)
• getLikedTweets: Problemas de validação de parâmetros

Recomendações

• Configuração Atual: Excelente para automação básica do X (Twitter)
• Para Análises Avançadas: Considere upgrade para o nível Pro
• Para Seguidores/Seguidos: Solicite permissões elevadas

🆘 Solução de Problemas

Problemas Comuns

Erro: "fetch is not defined"

# Ensure Node.js 18+ 
node --version

Erros de Permissão 403

• Verifique se as credenciais da API estão corretas
• Confirme se a conta possui as permissões necessárias
• Alguns endpoints precisam de aprovação especial

Erros de Solicitação Inválida 400

• Revise os formatos dos parâmetros
• Consulte nossas mensagens de erro aprimoradas para orientação
• Verifique se o nível da API suporta o endpoint

Obtendo Ajuda

1. Verifique as mensagens de erro - Nosso tratamento aprimorado de erros fornece orientação clara
2. Revise a documentação da API - Portal do Desenvolvedor do X (Twitter)
3. Teste primeiro com ferramentas funcionais - Verifique a configuração básica
4. Verifique as variáveis de ambiente - Garanta que todas as credenciais estejam definidas

---

📊 Status Atual

• 53 Ferramentas no Total: 33 da API do Twitter + 20 de pesquisa aprimorada do SocialData.tools
• Análises Avançadas: Análise de threads, mapeamento de redes, análise de sentimentos, rastreamento viral
• Tratamento Elegante de Chaves de API: Ferramentas aprimoradas exibem instruções úteis de configuração quando a chave de API está ausente
• Ignora Restrições da API: Ferramentas de pesquisa funcionam sem requisitos do nível Pro do Twitter
• Tratamento Profissional de Erros: Orientação clara de upgrade e mensagens amigáveis
• Conformidade Total com MCP: Ferramentas, prompts e recursos
• Pronto para Produção: Confiabilidade aprimorada, análises abrangentes e excelente experiência do usuário

Construído com ❤️ usando o Model Context Protocol e integração com o SocialData.tools