Hacker News MCP Server

Integre dados e discussões em tempo real do Hacker News em seus aplicativos e fluxos de trabalho.

Documentação

🚀 Hacker News MCP Server

A maneira mais fácil de trazer dados e discussões do Hacker News em tempo real para seus fluxos de trabalho com LLM, agentes ou aplicativos.

Transforme instantaneamente o Hacker News em uma base de conhecimento programável e conversacional para seus agentes e aplicativos de IA!

✨ Por que usar isso?

Plug-and-play: Conecte instantaneamente LLMs, agentes ou chatbots a dados e discussões ao vivo do Hacker News.
Flexível: Use como ferramenta local, API em nuvem ou microsserviço containerizado.
Apto para linguagem natural: Os usuários podem referenciar histórias por título, palavras-chave ou linguagem natural ("O que estão dizendo sobre computação quântica?").
Prompts ricos: Modelos de prompt integrados para resumos, tópicos em alta, análise de usuários e muito mais.
Pronto para produção: Tratamento robusto de erros, verificações de saúde e suporte a implantação em nuvem prontos para uso.

🌟 Recursos

⚡ Múltiplos modos de transporte: STDIO/MCP e SSE/MCP para integração flexível com LLM/agentes
🌐 Endpoints REST/OpenAPI: Acesso HTTP direto com documentação gerada automaticamente
📰 Cobertura completa do Hacker News: Acesse histórias, comentários, usuários, tópicos em alta e muito mais
🛡️ Tratamento robusto de erros: Modelos de resposta e códigos de status claros
🧩 Configuração fácil: Variáveis de ambiente para chaves de API, host e registro de logs
🐳 Pronto para contêineres: Docker e Docker Compose para implantação sem complicações
❤️ Monitoramento de saúde: Endpoint de verificação de saúde integrado
🔒 Suporte a CORS: Origens seguras e configuráveis para integração web

📚 Endpoints da API

Todos os endpoints estão disponíveis por padrão em http://localhost:8000 (ou no host/porta configurado).

🔎 Endpoints da API REST

Histórias

GET /api/stories/top?limit=30 — Obter principais histórias
GET /api/stories/best?limit=30 — Obter melhores histórias
GET /api/stories/new?limit=30 — Obter histórias mais recentes
GET /api/stories/ask?limit=30 — Obter histórias Ask HN
GET /api/stories/show?limit=30 — Obter histórias Show HN
GET /api/stories/search?query=YOUR_QUERY&limit=5 — Pesquisar histórias por título ou palavras-chave
GET /api/stories/by-date?days_ago=1&limit=30 — Obter histórias de N dias atrás

Detalhes da história

GET /api/item/{item_id} — Obter um item do Hacker News por ID
GET /api/story/by-title?title=YOUR_TITLE — Obter uma história (e comentários) por título/palavras-chave
GET /api/story/{story_id}/comments?comment_limit=10 — Obter uma história e seus principais comentários

Recuperação de conteúdo

GET /api/story/{story_id}/content?format=markdown — Obter o conteúdo real do URL de uma história
GET /api/story/content-by-title?title=YOUR_TITLE&format=markdown — Obter conteúdo pelo título da história
- O parâmetro format aceita markdown (padrão) ou json

Usuários

GET /api/user/{username} — Obter um usuário do Hacker News pelo nome de usuário

Sistema e atualizações

GET /api/maxitem — Obter o maior ID de item atual
GET /api/updates — Obter o item mais recente e alterações de perfil
GET /health — Endpoint de verificação de saúde
GET /sse-info — Informações sobre o endpoint SSE

SSE e MCP

GET /sse — Endpoint Server-Sent Events (SSE) para o protocolo MCP

OpenAPI e documentação

GET /docs — Swagger UI (documentação interativa da API)
GET /openapi.json — Esquema OpenAPI (para integração de ferramentas)

🗣️ Consultas em linguagem natural e baseadas em título

Você pode pesquisar e recuperar histórias usando linguagem natural ou palavras-chave, não apenas IDs numéricos!

Exemplo:
- GET /api/stories/search?query=quantum computing — Encontrar histórias sobre computação quântica
- GET /api/story/by-title?title=React framework — Obter a história mais recente e comentários sobre o framework React
Apto para linguagem natural:
- "Conte-me sobre aquela história de computação quântica de ontem"
- "Como está a discussão sobre o novo framework React?"

Essas consultas são tratadas pelos endpoints /api/stories/search e /api/story/by-title.

🧑‍💻 Exemplo de uso

Pesquisar histórias por título/palavras-chave:

curl "http://localhost:8000/api/stories/search?query=AI+ethics&limit=3"

Obter uma história e seus comentários por título:

curl "http://localhost:8000/api/story/by-title?title=OpenAI+GPT-4"

Obter o conteúdo real do URL de uma história (como Markdown):

curl "http://localhost:8000/api/story/12345/content?format=markdown"

Obter conteúdo pelo título da história:

curl "http://localhost:8000/api/story/content-by-title?title=quantum+computing&format=markdown"

Verificação de saúde:

curl "http://localhost:8000/health"

Obter principais histórias:

curl "http://localhost:8000/api/stories/top?limit=5"

Consulte /docs para documentação interativa completa e teste os endpoints ao vivo.

👤 Para quem é isso?

Desenvolvedores de LLM/agentes de IA: Adicione notícias e discussões reais e atualizadas aos seus agentes.
Criadores de chatbots: Alimente seus bots com histórias em alta e insights da comunidade.
Pesquisadores e cientistas de dados: Analise tendências do Hacker News, atividade de usuários e sentimento de tópicos.
Entusiastas de produtividade: Crie painéis personalizados, bots de notificação ou ferramentas de pesquisa.
Qualquer pessoa que queira tornar o Hacker News programável!

ℹ️ Dica: Você não precisa saber IDs de histórias—basta pedir histórias por título, tópico ou palavras-chave!

⚡ Início rápido

🛠️ Instale em segundos, execute em qualquer lugar!

1. Instalação

# Clone the repository
git clone https://github.com/yourusername/hacker-news-mcp.git
cd hacker-news-mcp

# Install dependencies
pip install -r requirements.txt

2. Executando o servidor

# Run with SSE transport (default, good for web/remote)
python run.py --transport sse --host 127.0.0.1 --port 8000

# Run with STDIO transport (for direct LLM/agent integration)
python run.py --transport stdio

# Optional: Run with custom log level
env LOG_LEVEL=debug python run.py --transport sse

3. 🚢 Implantação com Docker

# Build and run with Docker
docker build -t hacker-news-mcp .
docker run -p 8000:8000 hacker-news-mcp

# Or use Docker Compose
docker-compose up -d

🛠️ Configuração do MCP

💡 Dica: Funciona com Claude Desktop, Windsurf, Cursor IDE e qualquer LLM/agente que suporte MCP!

🎛️ Exemplo com Claude Desktop

STDIO (Local):

{
  "mcpServers": {
    "hackerNews": {
      "command": "python",
      "args": ["/path/to/hacker-news-mcp/run.py", "--transport", "stdio"],
      "env": { "LOG_LEVEL": "info" }
    }
  }
}

🖥️ Exemplo com Windsurf/Cursor IDE

STDIO (Local):

{
  "mcpServers": {
    "hackerNews": {
      "command": "python",
      "args": ["/path/to/hacker-news-mcp/run.py", "--transport", "stdio"],
      "env": { "LOG_LEVEL": "info" }
    }
  }
}

SSE (Remoto):

{
  "mcpServers": {
    "hackerNews": {
      "url": "https://your-deployed-server.com/sse",
      "transport": "sse"
    }
  }
}

🧰 Ferramentas, recursos e prompts

🛠️ Ferramentas disponíveis

🔎 Recuperação básica de dados
- get_item(id): Obter um item do Hacker News por ID
- get_user(id): Obter um usuário do Hacker News por ID
- get_max_item_id(): Obter o maior ID de item atual
🏆 Listagens de histórias
- get_top_stories(limit): Obter principais histórias
- get_best_stories(limit): Obter melhores histórias
- get_new_stories(limit): Obter histórias mais recentes
- get_ask_stories(limit): Obter histórias Ask HN
- get_show_stories(limit): Obter histórias Show HN
- get_job_stories(limit): Obter histórias de empregos
📝 Recuperação de conteúdo
- get_story_content(story_id, format): Obter o conteúdo real do URL de uma história
- get_story_content_by_title(title, format): Obter conteúdo pelo título da história
- Opções de formato: "markdown" (padrão) ou "json"
💬 Recuperação avançada de histórias
- get_story_with_comments(story_id, comment_limit): Obter uma história com seus comentários
- find_stories_by_title(query, limit): Encontrar histórias por título ou palavras-chave
- get_story_by_title(title): Encontrar e recuperar uma história por título ou palavras-chave com comentários
🔄 Outras ferramentas
- get_updates(): Obter o item mais recente e alterações de perfil
- search_by_date(days_ago, limit): Pesquisar histórias de aproximadamente N dias atrás

📦 Recursos

🧑‍💻 Recursos de itens
- hn://item/{id}: Obter item por ID
- hn://user/{id}: Obter usuário por ID
📋 Recursos de listagem de histórias
- hn://top/{limit}: Obter principais histórias
- hn://best/{limit}: Obter melhores histórias
- hn://new/{limit}: Obter histórias mais recentes
- hn://ask/{limit}: Obter histórias Ask HN
- hn://show/{limit}: Obter histórias Show HN
- hn://jobs/{limit}: Obter histórias de empregos

🧠 Modelos de prompt

💡 Apto para linguagem natural: Os usuários podem referenciar histórias por título, palavras-chave ou apenas fazer perguntas em inglês simples!

🧠 Roteador inteligente
- hn_router(query): Analisa qualquer consulta relacionada ao HN e roteia para as melhores ferramentas e abordagem
📝 Análise de histórias
- hn_story_summary_by_id(story_id): Resumir uma história do Hacker News por ID
- hn_story_summary_by_title(title): Resumir uma história por título/palavras-chave
- hn_story_comment_analysis(title|id): Analisar comentários de uma história
📰 Recuperação e análise de conteúdo
- hn_story_content_by_id(story_id): Obter e analisar o conteúdo completo do artigo do URL de uma história
- hn_story_content_by_title(title): Obter e analisar conteúdo pesquisando uma história por título/palavras-chave
- hn_content_filter(story_id, filter_type): Extrair tipos específicos de conteúdo (técnico, código, opiniões, etc.)
🔎 Pesquisa avançada e comparação
- hn_advanced_search(query, days, min_score, min_comments): Encontrar histórias que correspondam a critérios específicos
- hn_compare_stories(story_ids): Comparar várias histórias para identificar semelhanças e diferenças
- hn_multi_source_analysis(query, sources_count): Analisar várias fontes sobre o mesmo tópico
📈 Análise de tendências
- hn_trending_topics(): Listar tópicos atuais em alta
- hn_trend_analysis(days, story_type, topic): Analisar tendências ao longo do tempo, opcionalmente focado em um tópico específico
👤 Análise de usuários
- hn_user_profile_analysis(username): Analisar a atividade e os interesses de um usuário

🗣️ Exemplos de solicitações de usuários

"Resuma aquela história do HN sobre computação quântica"
"O que está em alta no Hacker News hoje?"
"Conte-me sobre o usuário do HN 'dang'"
"Dê-me uma análise detalhada da discussão sobre regulação de IA"

⚡ Sem necessidade de IDs! Basta perguntar naturalmente—este servidor corresponde sua solicitação ao prompt e às ferramentas certas.

💬 Exemplos avançados de prompts

Roteador inteligente

"What can you tell me about quantum computing discussions on Hacker News?"

O roteador analisa sua consulta, identifica a intenção e recomenda a melhor abordagem usando as ferramentas disponíveis (por exemplo, pesquisar histórias de computação quântica, analisar conteúdo, comparar perspectivas).

Análise de múltiplas fontes

"Compare different perspectives on blockchain from Hacker News"
"What are the various opinions about the new MacBook Pro?"

Recupera várias fontes sobre o mesmo tópico, extrai seu conteúdo e fornece uma análise abrangente de diferentes pontos de vista, áreas de concordância/discordância e sintetiza insights.

Filtragem de conteúdo

"Show me just the technical parts of HN story 12345"
"Extract the code examples from that article about Rust"

Recupera o conteúdo de uma história e o filtra de acordo com necessidades específicas (detalhes técnicos, exemplos de código, opiniões, explicações para iniciantes, etc.).

Pesquisa avançada

"Find popular stories about quantum computing with lots of discussion"
"What are the highest-rated AI stories from the past month?"

Executa pesquisa avançada com filtragem por pontuação, contagem de comentários e período de tempo, e depois analisa os resultados.

Análise de tendências

"How has discussion about AI changed on HN over the last month?"
"What topics are gaining traction compared to last week?"

Compara histórias atuais com dados históricos para identificar tópicos emergentes, interesses em mudança e padrões de engajamento da comunidade.

Comparação de histórias

"Compare HN stories 12345 and 67890"
"What's the difference between those two quantum computing articles?"

Compara várias histórias para identificar semelhanças, diferenças e relações entre elas.

Documentação da API

Ao executar com transporte SSE, a documentação OpenAPI está disponível em:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc
OpenAPI JSON: http://localhost:8000/openapi.json

Configuração

Variáveis de ambiente

HN_API_KEY: Chave de API para o Hacker News (se necessário no futuro)
LOG_LEVEL: Nível de registro de logs (debug, info, warning, error, critical)
FASTMCP_TOOL_ATTEMPT_PARSE_JSON_ARGS: Defina como 1 para habilitar a análise JSON para argumentos de ferramentas

Implantação em nuvem

Implantação no Google Cloud Run

Crie e envie a imagem Docker

# Build the Docker image
docker build -t gcr.io/your-project-id/hacker-news-mcp .

# Push to Google Container Registry
docker push gcr.io/your-project-id/hacker-news-mcp

Implante no Cloud Run

gcloud run deploy hacker-news-mcp \
  --image gcr.io/your-project-id/hacker-news-mcp \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --memory 512Mi \
  --set-env-vars="LOG_LEVEL=info"

Configure os consumidores MCP com o URL do Cloud Run

Após a implantação, o Cloud Run fornecerá um URL como https://hacker-news-mcp-abcdef123-uc.a.run.app. Use este URL na sua configuração MCP:

{
  "name": "Hacker News",
  "url": "https://hacker-news-mcp-abcdef123-uc.a.run.app/sse",
  "transport": "sse"
}

Implantação no AWS Lambda

Empacote o aplicativo

# Create a deployment package
zip -r deployment.zip . -x "*.git*" -x "*.pytest_cache*" -x "__pycache__/*"

Crie a função Lambda com API Gateway

Crie uma função Lambda no Console da AWS
Envie o pacote deployment.zip
Configure um gatilho de API Gateway
Defina as variáveis de ambiente conforme necessário

Configure os consumidores MCP com o URL do API Gateway

Use o URL do API Gateway na sua configuração MCP:

{
  "name": "Hacker News",
  "url": "https://abcdef123.execute-api.us-east-1.amazonaws.com/prod/sse",
  "transport": "sse"
}

Exemplos de integração

Cliente Python

import asyncio
from fastmcp import Client
from fastmcp.client.transports import SSETransport
import json

async def main():
    # Connect to the server
    client = Client(SSETransport("http://localhost:8000/sse"))
    
    async with client:
        # List available tools
        tools = await client.list_tools()
        print(f"Available tools: {len(tools)}")
        
        # Get top stories
        top_stories = await client.call_tool("get_top_stories", {"limit": 5})
        story_ids = json.loads(top_stories[0].text)
        print(f"Top stories: {story_ids}")
        
        # Get a specific story
        if story_ids:
            story_result = await client.call_tool("get_item", {"id": story_ids[0]})
            story_data = json.loads(story_result[0].text)
            print(f"Story: {story_data.get('title')}")

if __name__ == "__main__":
    asyncio.run(main())

Integração STDIO

Para agentes LLM que suportam servidores MCP baseados em STDIO:

# Run the server in STDIO mode
python run.py --transport stdio

Testes

Executando testes

# Run all tests
python -m pytest tests/

# Run specific test file
python -m pytest tests/test_server.py

Testes manuais com o cliente de teste

# Start the server in one terminal
python run.py --transport sse

# Run the test client in another terminal
python test_client.py

Solução de problemas

Problemas comuns

Conexão recusada
- Certifique-se de que o servidor está em execução e a porta está correta
- Verifique as configurações do firewall
Transporte não suportado
- Verifique se você está usando um transporte suportado ("stdio" ou "sse")
Erros de análise JSON
- Para LLMs mais antigos, defina FASTMCP_TOOL_ATTEMPT_PARSE_JSON_ARGS=1
Dependências ausentes
- Execute pip install -r requirements.txt para garantir que todas as dependências estejam instaladas

Contribuindo

Faça um fork do repositório
Crie sua branch de recurso (git checkout -b feature/amazing-feature)
Faça commit das suas alterações (git commit -m 'Add some amazing feature')
Envie para a branch (git push origin feature/amazing-feature)
Abra um Pull Request

Licença

Este projeto é licenciado sob a GNU Affero General Public License v3.0 (AGPLv3) — consulte o arquivo LICENSE para obter detalhes.

A AGPLv3 é uma licença copyleft que exige que qualquer pessoa que distribua seu código ou um trabalho derivado disponibilize o código-fonte sob os mesmos termos, e também estende esse requisito a usuários que interagem com o software por meio de uma rede.

AVISO DE USO COMERCIAL Se você quiser usar ou implantar este código de qualquer forma como parte de um serviço monetizado para terceiros, mesmo que não cobre especificamente pelo código, precisará entrar em contato comigo para obter permissão (isso significa VOCÊ, Smithery/Glama ou qualquer serviço similar) — que só será concedida mediante o pagamento da taxa de licenciamento apropriada. Não, você pode não estar cobrando pelo uso do código em si, e pode estar fornecendo a infraestrutura, mas estaria usando MEU código para facilitar SEU serviço. Essa é uma dependência intrínseca que DEVE ser licenciada. COLOCAR ATRÁS DE PAYWALL o uso de Software de Código Aberto não é democratizar o software, é restringi-lo apenas para aqueles que podem pagar, o que é contrário ao espírito do Licenciamento de Código Aberto.

Para qualquer outra pessoa, seja você uma empresa ou um indivíduo, espero que seja útil para você. Aproveite.

Hacker News MCP Server

Documentação