Hacker News

Obtén e interactúa con contenido de Hacker News, incluyendo historias principales, comentarios y funcionalidad de búsqueda.

GitHub
3
Prueba este MCPPatrocinado

Documentación

📰 Servidor MCP de Hacker News

CI License: MIT

A Model Context Protocol (MCP) servidor que proporciona herramientas para obtener e interactuar con el contenido de Hacker News. Este servidor permite a los asistentes de IA acceder a datos en tiempo real de Hacker News, incluyendo historias principales, detalles de historias, comentarios y funcionalidad de búsqueda.

Hacker News Server MCP server

🚀 Características

🛠️ Herramientas disponibles

  • get_top_stories - Obtener las últimas historias principales de Hacker News

    • Recuento configurable (1-100 historias)
    • Inclusión opcional de contenido de texto
    • Devuelve metadatos de la historia, incluyendo título, URL, puntuación, autor y número de comentarios

  • get_story_details - Obtener información detallada sobre una historia específica

    • Obtener metadatos completos de la historia
    • Inclusión opcional de comentarios con estructura de hilo
    • Extracción opcional de contenido Markdown de artículos enlazados

  • get_story_comments - Recuperar comentarios populares de una historia

    • Filtrado configurable por puntuación mínima
    • Profundidad ajustable del hilo de comentarios (1-10 niveles)
    • Límite de comentarios devueltos (1-100)
    • Formateado como texto legible con estructura de hilo

  • search_stories - Buscar historias recientes por palabras clave

    • Buscar en títulos, contenido y URLs de historias
    • Rango de tiempo configurable (1-168 horas)
    • Límite de resultados (1-50 historias)

📋 Requisitos previos

  • Node.js 18+
  • npm o yarn
  • Un cliente compatible con MCP (como Claude Desktop)

🔧 Instalación

1. Clonar el repositorio

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

2. Instalar dependencias

npm install

3. Compilar el servidor

npm run build

🎯 Uso

Con Claude Desktop

Añade el servidor a tu configuración de 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"]
    }
  }
}

Con otros clientes MCP

El servidor se comunica a través de stdio y puede usarse con cualquier cliente compatible con MCP:

node build/index.js

🔍 Ejemplo de uso

Una vez conectado, puedes preguntar a tu asistente de IA cosas como:

  • "¿Cuáles son las historias principales de Hacker News hoy?"
  • "Obtén detalles sobre la historia 12345678 de Hacker News"
  • "Muéstrame comentarios sobre esa historia viral de IA"
  • "Busca historias recientes sobre TypeScript"

🛠️ Desarrollo

Compilar el proyecto

npm run build

Modo de observación para desarrollo

npm run watch

Lint y formateo del código

npm run lint
npm run format

Ejecutar el MCP Inspector

Para depuración y pruebas:

npm run inspector

Esto iniciará el MCP Inspector, proporcionando una interfaz web para probar las herramientas del servidor e inspeccionar la comunicación.

📦 Calidad del código y contribuciones

  • Calidad del código:
    Este proyecto aplica calidad y estilo de código usando ESLint y Prettier. Todo el código se verifica en CI (GitHub Actions) y debe pasar el linting y el formateo antes de fusionarse.
  • Seguridad de tipos:
    Todos los manejadores de herramientas usan guardas de tipo explícitas para la validación de argumentos en tiempo de ejecución y tipos TypeScript robustos.
  • CI/CD:
    Cada push y pull request ejecuta la compilación completa, el lint y la (futura) suite de pruebas mediante GitHub Actions.
  • Cómo contribuir:
    1. Haz un fork del repositorio
    2. Crea una rama de características (git checkout -b feature/amazing-feature)
    3. Realiza tus cambios (git commit -m 'Add amazing feature')
    4. Ejecuta npm run lint y npm run format antes de hacer push
    5. Haz push a la rama (git push origin feature/amazing-feature)
    6. Abre un Pull Request

📚 Referencia de la 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)
}

🏗️ Arquitectura

El servidor está construido con:

  • TypeScript para seguridad de tipos y experiencia de desarrollo
  • @modelcontextprotocol/sdk para la implementación del protocolo MCP
  • axios para solicitudes HTTP a la API de Hacker News
  • jsdom y turndown para la conversión de HTML a Markdown
  • private-ip para seguridad (bloquea el acceso a IP privadas)

Componentes clave

  • src/index.ts - Implementación principal del servidor con manejadores de herramientas
  • src/fetcher.ts - Clase de utilidad para obtener y convertir contenido web
  • build/ - Salida de JavaScript compilado (generada automáticamente)

🔒 Seguridad

  • Bloquea solicitudes a direcciones IP privadas para prevenir el acceso a la red local
  • Límite de velocidad mediante los límites naturales de la API de Hacker News
  • Validación de entrada para todos los parámetros de las herramientas
  • Manejo de errores y degradación elegante

📜 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

🙏 Agradecimientos

  • Hacker News por proporcionar la excelente API
  • Model Context Protocol por el estándar
  • La comunidad de código abierto por las increíbles herramientas y bibliotecas

📞 Soporte

Si encuentras algún problema o tienes preguntas:

  1. Consulta la página de Issues
  2. Usa el MCP Inspector para depuración: npm run inspector
  3. Crea un nuevo issue con información detallada sobre tu problema

Hecho con ❤️ para la comunidad MCP