Hacker News

Buscar e interagir com conteúdo do Hacker News, incluindo principais histórias, comentários e funcionalidade de busca.

Documentação

📰 Servidor MCP do Hacker News

A Model Context Protocol (MCP) servidor que fornece ferramentas para buscar e interagir com o conteúdo do Hacker News. Este servidor permite que assistentes de IA acessem dados em tempo real do Hacker News, incluindo principais histórias, detalhes de histórias, comentários e funcionalidade de busca. -->

🚀 Recursos

🛠️ Ferramentas Disponíveis

get_top_stories - Buscar as principais histórias mais recentes do Hacker News
- Contagem configurável (1-100 histórias)
- Inclusão opcional de conteúdo de texto
- Retorna metadados da história, incluindo título, URL, pontuação, autor e contagem de comentários
get_story_details - Obter informações detalhadas sobre uma história específica
- Buscar metadados completos da história
- Inclusão opcional de comentários com estrutura em tópicos
- Extração opcional de conteúdo Markdown de artigos vinculados
get_story_comments - Recuperar comentários populares para uma história
- Filtro configurável de pontuação mínima
- Profundidade ajustável do tópico de comentários (1-10 níveis)
- Limitar o número de comentários retornados (1-100)
- Formatado como texto legível com estrutura de tópicos
search_stories - Buscar histórias recentes por palavras-chave
- Buscar em títulos, conteúdo e URLs de histórias
- Intervalo de tempo configurável (1-168 horas)
- Limitar resultados (1-50 histórias)

📋 Pré-requisitos

Node.js 18+
npm ou yarn
Um cliente compatível com MCP (como o Claude Desktop)

🔧 Instalação

1. Clone o repositório

git clone https://github.com/yourusername/hackernews-mcp.git
cd hackernews-mcp

2. Instale as dependências

npm install

3. Compile o servidor

npm run build

🎯 Uso

Com o Claude Desktop

Adicione o servidor à configuração do seu Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "hackernews-mcp": {
      "command": "node",
      "args": ["/path/to/hackernews-mcp/build/index.js"]
    }
  }
}

Com Outros Clientes MCP

O servidor se comunica via stdio e pode ser usado com qualquer cliente compatível com MCP:

node build/index.js

🔍 Exemplo de Uso

Depois de conectado, você pode perguntar ao seu assistente de IA coisas como:

"Quais são as principais histórias do Hacker News hoje?"
"Obtenha detalhes sobre a história 12345678 do Hacker News"
"Mostre-me comentários para aquela história viral de IA"
"Busque histórias recentes sobre TypeScript"

🛠️ Desenvolvimento

Compile o projeto

npm run build

Modo de observação para desenvolvimento

npm run watch

Lint e formatação do código

npm run lint
npm run format

Execute o MCP Inspector

Para depuração e testes:

npm run inspector

Isso iniciará o MCP Inspector, fornecendo uma interface web para testar as ferramentas do servidor e inspecionar a comunicação.

📦 Qualidade do Código e Contribuição

Qualidade do Código:
Este projeto aplica qualidade e estilo de código usando ESLint e Prettier. Todo o código é verificado no CI (GitHub Actions) e deve passar na lintagem e formatação antes da mesclagem.
Segurança de Tipos:
Todos os manipuladores de ferramentas usam guardas de tipo explícitas para validação de argumentos em tempo de execução e tipos TypeScript robustos.
CI/CD:
Cada push e pull request executa a compilação completa, lint e (futura) suíte de testes via GitHub Actions.
Como Contribuir:
1. Faça um fork do repositório
2. Crie um branch de recurso (git checkout -b feature/amazing-feature)
3. Faça commit das suas alterações (git commit -m 'Add amazing feature')
4. Execute npm run lint e npm run format antes de enviar
5. Envie para o branch (git push origin feature/amazing-feature)
6. Abra um Pull Request

📚 Referência da API

get_top_stories

{
  count?: number;        // Number of stories (1-100, default: 30)
  include_text?: boolean; // Include story text content (default: false)
}

get_story_details

{
  story_id: number;           // Required: HN story ID
  include_comments?: boolean; // Include comments (default: false)
  include_markdown?: boolean; // Extract article as markdown (default: false)
}

get_story_comments

{
  story_id: number;    // Required: HN story ID
  min_score?: number;  // Minimum comment score (default: 1)
  max_depth?: number;  // Max thread depth (1-10, default: 3)
  limit?: number;      // Max comments (1-100, default: 20)
}

search_stories

{
  query: string;              // Required: Search keywords
  limit?: number;             // Max results (1-50, default: 20)
  time_range_hours?: number;  // Hours to search back (1-168, default: 24)
}

🏗️ Arquitetura

O servidor é construído com:

TypeScript para segurança de tipos e experiência do desenvolvedor
@modelcontextprotocol/sdk para implementação do protocolo MCP
axios para requisições HTTP à API do Hacker News
jsdom e turndown para conversão de HTML para Markdown
private-ip para segurança (bloqueia acesso a IPs privados)

Componentes Principais

src/index.ts - Implementação principal do servidor com manipuladores de ferramentas
src/fetcher.ts - Classe utilitária para buscar e converter conteúdo web
build/ - Saída JavaScript compilada (gerada automaticamente)

🔒 Segurança

Bloqueia requisições para endereços IP privados para prevenir acesso à rede local
Limitação de taxa através dos limites naturais da API do Hacker News
Validação de entrada para todos os parâmetros das ferramentas
Tratamento de erros e degradação graciosa

📜 Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

🙏 Agradecimentos

Hacker News por fornecer a excelente API
Model Context Protocol pelo padrão
A comunidade de código aberto pelas incríveis ferramentas e bibliotecas

📞 Suporte

Se você encontrar algum problema ou tiver dúvidas:

Verifique a página de Issues
Use o MCP Inspector para depuração: npm run inspector
Crie um novo issue com informações detalhadas sobre o seu problema

Feito com ❤️ para a comunidade MCP