Hacker News MCP Server

Integra datos y discusiones en tiempo real de Hacker News en tus aplicaciones y flujos de trabajo.

GitHub
3
Prueba este MCPPatrocinado

Documentación

🚀 Servidor MCP de Hacker News

La forma más fácil de incorporar datos y discusiones de Hacker News en tiempo real a tus flujos de trabajo con LLM, agentes o aplicaciones.

FastMCP Hacker News API License: AGPL v3

¡Convierte Hacker News al instante en una base de conocimiento programable y conversacional para tus agentes y aplicaciones de IA!

✨ ¿Por qué usarlo?

  • Plug-and-play: Conecta al instante LLMs, agentes o chatbots a los datos y discusiones en vivo de Hacker News.
  • Flexible: Úsalo como herramienta local, API en la nube o microservicio contenerizado.
  • Amigable con el lenguaje natural: Los usuarios pueden referirse a historias por título, palabras clave o lenguaje natural ("¿Qué dice la gente sobre la computación cuántica?").
  • Prompts enriquecidos: Plantillas de prompt integradas para resúmenes, temas de tendencia, análisis de usuarios y más.
  • Listo para producción: Manejo robusto de errores, verificaciones de salud y soporte de despliegue en la nube incluidos.

🌟 Características

  • ⚡ Múltiples modos de transporte: STDIO/MCP y SSE/MCP para una integración flexible con LLM/agentes
  • 🌐 Endpoints REST/OpenAPI: Acceso HTTP directo con documentación autogenerada
  • 📰 Cobertura completa de Hacker News: Accede a historias, comentarios, usuarios, temas de tendencia y más
  • 🛡️ Manejo robusto de errores: Modelos de respuesta y códigos de estado claros
  • 🧩 Configuración fácil: Variables de entorno para claves API, host y registro
  • 🐳 Listo para contenedores: Docker y Docker Compose para un despliegue sin complicaciones
  • ❤️ Monitoreo de salud: Endpoint de verificación de salud integrado
  • 🔒 Soporte CORS: Orígenes seguros y configurables para integración web

📚 Endpoints de API

Todos los endpoints están disponibles por defecto en http://localhost:8000 (o el host/puerto que configures).

🔎 Endpoints de API REST

Historias

  • GET /api/stories/top?limit=30 — Obtener historias principales
  • GET /api/stories/best?limit=30 — Obtener mejores historias
  • GET /api/stories/new?limit=30 — Obtener historias más recientes
  • GET /api/stories/ask?limit=30 — Obtener historias de Ask HN
  • GET /api/stories/show?limit=30 — Obtener historias de Show HN
  • GET /api/stories/search?query=YOUR_QUERY&limit=5 — Buscar historias por título o palabras clave
  • GET /api/stories/by-date?days_ago=1&limit=30 — Obtener historias de hace N días

Detalles de historias

  • GET /api/item/{item_id} — Obtener un elemento de Hacker News por ID
  • GET /api/story/by-title?title=YOUR_TITLE — Obtener una historia (y comentarios) por título/palabras clave
  • GET /api/story/{story_id}/comments?comment_limit=10 — Obtener una historia y sus comentarios principales

Recuperación de contenido

  • GET /api/story/{story_id}/content?format=markdown — Obtener el contenido real de la URL de una historia
  • GET /api/story/content-by-title?title=YOUR_TITLE&format=markdown — Obtener contenido por título de historia
    • El parámetro format acepta markdown (predeterminado) o json

Usuarios

  • GET /api/user/{username} — Obtener un usuario de Hacker News por nombre de usuario

Sistema y actualizaciones

  • GET /api/maxitem — Obtener el ID de elemento más grande actual
  • GET /api/updates — Obtener el elemento más reciente y cambios de perfil
  • GET /health — Endpoint de verificación de salud
  • GET /sse-info — Información sobre el endpoint SSE

SSE y MCP

  • GET /sse — Endpoint de Eventos Enviados por el Servidor (SSE) para el protocolo MCP

OpenAPI y documentación

  • GET /docs — Interfaz Swagger UI (documentación interactiva de API)
  • GET /openapi.json — Esquema OpenAPI (para integración de herramientas)

🗣️ Consultas por lenguaje natural y basadas en título

Puedes buscar y recuperar historias usando lenguaje natural o palabras clave, ¡no solo IDs numéricos!

  • Ejemplo:

    • GET /api/stories/search?query=quantum computing — Encontrar historias sobre computación cuántica
    • GET /api/story/by-title?title=React framework — Obtener la historia más reciente y comentarios sobre el framework React

  • Amigable con el lenguaje natural:

    • "Cuéntame sobre esa historia de computación cuántica de ayer"
    • "¿Cómo es la discusión sobre el nuevo framework React?"

Estas consultas se manejan a través de los endpoints /api/stories/search y /api/story/by-title.

🧑‍💻 Ejemplo de uso

Buscar historias por título/palabras clave:

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

Obtener una historia y sus comentarios por título:

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

Obtener el contenido real de la URL de una historia (como Markdown):

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

Obtener contenido por título de historia:

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

Verificación de salud:

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

Obtener historias principales:

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

Consulta /docs para obtener documentación interactiva completa y probar los endpoints en vivo.

👤 ¿Para quién es?

  • Desarrolladores de LLM/Agentes de IA: Añade noticias y discusiones del mundo real y actualizadas a tus agentes.
  • Creadores de chatbots: Potencia tus bots con historias de tendencia y perspectivas de la comunidad.
  • Investigadores y científicos de datos: Analiza tendencias de Hacker News, actividad de usuarios y sentimiento de temas.
  • Entusiastas de la productividad: Construye paneles personalizados, bots de notificaciones o herramientas de investigación.
  • ¡Cualquiera que quiera hacer Hacker News programable!

ℹ️ Consejo: No necesitas saber los IDs de las historias—¡solo pregunta por historias por título, tema o palabras clave!

⚡ Inicio rápido

🛠️ ¡Instala en segundos, ejecuta en cualquier lugar!

1. Instalación

# 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. Ejecutar el 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. 🚢 Despliegue con 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

🛠️ Configuración de MCP

💡 Consejo: Funciona con Claude Desktop, Windsurf, Cursor IDE y cualquier LLM/agente que soporte MCP.

🎛️ Ejemplo con Claude Desktop

STDIO (Local):

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

🖥️ Ejemplo con 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"
    }
  }
}

🧰 Herramientas, recursos y prompts

🛠️ Herramientas disponibles

  • 🔎 Recuperación básica de datos
    • get_item(id): Obtener un elemento de Hacker News por ID
    • get_user(id): Obtener un usuario de Hacker News por ID
    • get_max_item_id(): Obtener el ID de elemento más grande actual
  • 🏆 Listados de historias
    • get_top_stories(limit): Obtener historias principales
    • get_best_stories(limit): Obtener mejores historias
    • get_new_stories(limit): Obtener historias más recientes
    • get_ask_stories(limit): Obtener historias de Ask HN
    • get_show_stories(limit): Obtener historias de Show HN
    • get_job_stories(limit): Obtener historias de empleo
  • 📝 Recuperación de contenido
    • get_story_content(story_id, format): Obtener el contenido real de la URL de una historia
    • get_story_content_by_title(title, format): Obtener contenido por título de historia
    • Opciones de formato: "markdown" (predeterminado) o "json"
  • 💬 Recuperación avanzada de historias
    • get_story_with_comments(story_id, comment_limit): Obtener una historia con sus comentarios
    • find_stories_by_title(query, limit): Encontrar historias por título o palabras clave
    • get_story_by_title(title): Encontrar y recuperar una historia por su título o palabras clave con comentarios
  • 🔄 Otras herramientas
    • get_updates(): Obtener el elemento más reciente y cambios de perfil
    • search_by_date(days_ago, limit): Buscar historias de aproximadamente N días atrás

📦 Recursos

  • 🧑‍💻 Recursos de elementos
    • hn://item/{id}: Obtener elemento por ID
    • hn://user/{id}: Obtener usuario por ID
  • 📋 Recursos de listados de historias
    • hn://top/{limit}: Obtener historias principales
    • hn://best/{limit}: Obtener mejores historias
    • hn://new/{limit}: Obtener historias más recientes
    • hn://ask/{limit}: Obtener historias de Ask HN
    • hn://show/{limit}: Obtener historias de Show HN
    • hn://jobs/{limit}: Obtener historias de empleo

🧠 Plantillas de prompts

💡 Amigable con el lenguaje natural: ¡Los usuarios pueden referirse a historias por título, palabras clave o simplemente hacer preguntas en inglés sencillo!

  • 🧠 Enrutador inteligente

    • hn_router(query): Analiza cualquier consulta relacionada con HN y enruta a las mejores herramientas y enfoque

  • 📝 Análisis de historias

    • hn_story_summary_by_id(story_id): Resumir una historia de Hacker News por ID
    • hn_story_summary_by_title(title): Resumir una historia por título/palabras clave
    • hn_story_comment_analysis(title|id): Analizar comentarios de una historia

  • 📰 Recuperación y análisis de contenido

    • hn_story_content_by_id(story_id): Obtener y analizar el contenido completo del artículo desde la URL de una historia
    • hn_story_content_by_title(title): Obtener y analizar contenido buscando una historia por título/palabras clave
    • hn_content_filter(story_id, filter_type): Extraer tipos específicos de contenido (técnico, código, opiniones, etc.)

  • 🔎 Búsqueda avanzada y comparación

    • hn_advanced_search(query, days, min_score, min_comments): Encontrar historias que coincidan con criterios específicos
    • hn_compare_stories(story_ids): Comparar múltiples historias para identificar similitudes y diferencias
    • hn_multi_source_analysis(query, sources_count): Analizar múltiples fuentes sobre el mismo tema

  • 📈 Análisis de tendencias

    • hn_trending_topics(): Listar temas de tendencia actuales
    • hn_trend_analysis(days, story_type, topic): Analizar tendencias a lo largo del tiempo, opcionalmente enfocado en un tema específico

  • 👤 Análisis de usuarios

    • hn_user_profile_analysis(username): Analizar la actividad e intereses de un usuario

🗣️ Ejemplos de solicitudes de usuarios

  • "Resume esa historia de HN sobre computación cuántica"
  • "¿Qué está en tendencia en Hacker News hoy?"
  • "Cuéntame sobre el usuario de HN 'dang'"
  • "Dame un análisis detallado de la discusión sobre la regulación de la IA"

⚡ ¡No necesitas IDs! Solo pregunta de forma natural—este servidor empareja tu solicitud con el prompt y las herramientas adecuadas.

💬 Ejemplos avanzados de prompts

Enrutador inteligente

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

El enrutador analiza tu consulta, identifica la intención y recomienda el mejor enfoque usando las herramientas disponibles (por ejemplo, buscar historias de computación cuántica, analizar contenido, comparar perspectivas).

Análisis de múltiples fuentes

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

Recupera múltiples fuentes sobre el mismo tema, extrae su contenido y proporciona un análisis completo de diferentes puntos de vista, áreas de acuerdo/desacuerdo y sintetiza perspectivas.

Filtrado de contenido

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

Recupera el contenido de una historia y lo filtra según necesidades específicas (detalles técnicos, ejemplos de código, opiniones, explicaciones para principiantes, etc.).

Búsqueda avanzada

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

Realiza una búsqueda avanzada con filtrado por puntuación, número de comentarios y período de tiempo, y luego analiza los resultados.

Análisis de tendencias

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

Compara historias actuales con datos históricos para identificar temas emergentes, intereses cambiantes y patrones de participación de la comunidad.

Comparación de historias

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

Compara múltiples historias para identificar similitudes, diferencias y relaciones entre ellas.

Documentación de API

Cuando se ejecuta con transporte SSE, la documentación de OpenAPI está disponible en:

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

Configuración

Variables de entorno

  • HN_API_KEY: Clave API para Hacker News (si se requiere en el futuro)
  • LOG_LEVEL: Nivel de registro (debug, info, warning, error, critical)
  • FASTMCP_TOOL_ATTEMPT_PARSE_JSON_ARGS: Establecer en 1 para habilitar el análisis JSON para argumentos de herramientas

Despliegue en la nube

Despliegue en Google Cloud Run

  1. Construir y enviar la imagen 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
  1. Desplegar en 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"
  1. Configurar los consumidores de MCP con la URL de Cloud Run

Después del despliegue, Cloud Run proporcionará una URL como https://hacker-news-mcp-abcdef123-uc.a.run.app. Usa esta URL en tu configuración de MCP:

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

Despliegue en AWS Lambda

  1. Empaquetar la aplicación
# Create a deployment package
zip -r deployment.zip . -x "*.git*" -x "*.pytest_cache*" -x "__pycache__/*"
  1. Crear la función Lambda con API Gateway
  • Crea una función Lambda en la consola de AWS
  • Sube el paquete deployment.zip
  • Configura un disparador de API Gateway
  • Establece las variables de entorno según sea necesario
  1. Configurar los consumidores de MCP con la URL de API Gateway

Usa la URL de API Gateway en tu configuración de MCP:

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

Ejemplos de integración

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())

Integración STDIO

Para agentes LLM que soporten servidores MCP basados en STDIO:

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

Pruebas

Ejecutar pruebas

# Run all tests
python -m pytest tests/

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

Pruebas manuales con el cliente de prueba

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

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

Solución de problemas

Problemas comunes

  1. Conexión rechazada

    • Asegúrate de que el servidor esté ejecutándose y el puerto sea correcto
    • Verifica la configuración del firewall

  2. Transporte no soportado

    • Verifica que estés usando un transporte soportado ("stdio" o "sse")

  3. Errores de análisis JSON

    • Para LLMs más antiguos, establece FASTMCP_TOOL_ATTEMPT_PARSE_JSON_ARGS=1

  4. Dependencias faltantes

    • Ejecuta pip install -r requirements.txt para asegurarte de que todas las dependencias estén instaladas

Contribuciones

  1. Haz un fork del repositorio
  2. Crea tu rama de características (git checkout -b feature/amazing-feature)
  3. Haz commit de tus cambios (git commit -m 'Add some amazing feature')
  4. Haz push a la rama (git push origin feature/amazing-feature)
  5. Abre una solicitud de extracción (Pull Request)

Licencia

Este proyecto está licenciado bajo la Licencia Pública General Affero de GNU v3.0 (AGPLv3) — consulta el archivo LICENSE para más detalles.

La AGPLv3 es una licencia copyleft que requiere que cualquier persona que distribuya tu código o una obra derivada ponga el código fuente a disposición bajo los mismos términos, y también extiende este requisito a los usuarios que interactúan con el software a través de una red.

ADVERTENCIA DE USO COMERCIAL Si deseas usar o implementar este código de cualquier forma como parte de un servicio monetizado para otros, incluso si no cobras específicamente por el código, necesitas contactarme para obtener permiso (esto significa TÚ Smithery/Glama o cualquier servicio similar), que solo se otorgará tras el pago de la tarifa de licencia correspondiente. No, puede que no estés cobrando por el uso del código en sí, y puede que estés proporcionando la infraestructura, pero estarías usando MI código para facilitar TU servicio. Esa es una dependencia intrínseca que DEBE ser licenciada. PONER DETRÁS DE UN MURO DE PAGO el uso de Software de Código Abierto no es democratizar el software, es restringirlo solo para aquellos que pueden permitirse pagar, lo cual es contrario al espíritu de las Licencias de Código Abierto.

Para cualquier otra persona, ya sea una empresa o un individuo, espero que te sea útil. Disfrútalo.

Agradecimientos