===============================================================================
                           HACKERNEWS MCP SERVER
===============================================================================
              Sovereign Model Context Protocol (MCP) Server
               for HackerNews Firebase REST API & Automation
===============================================================================

  Author: Peter Lodri (pocok0xRE) & Antigravity AI
  License: MIT
  Repository: https://github.com/peterlodri-sec/hackernews-mcp
  Language: Python 3.12+ (Asyncio TaskGroups, Structural Pattern Matching)

-------------------------------------------------------------------------------
1. OVERVIEW
-------------------------------------------------------------------------------

  hackernews-mcp is a high-performance Model Context Protocol (MCP) server
  that connects LLM Agents (Claude, Antigravity, GPT-4o, Cursor) directly to
  HackerNews.

  It provides structured access to:
    - Live HackerNews Submissions and Items via Firebase REST API
    - Concurrent Sub-tree Comment Fetching using Python 3.12 TaskGroups
    - Algolia HackerNews Search Index
    - Authenticated Comment Posting via Web Session Credentials
    - HackerNews User Profiles and Karma Records

-------------------------------------------------------------------------------
2. ARCHITECTURE
-------------------------------------------------------------------------------

     +-------------------+          +--------------------+
     |   LLM Agent       |  MCP     |   HackerNews MCP   |
     | (Claude/AGY/etc)  | -------->|   Server           |
     +-------------------+  stdio   +--------------------+
                                             |
                   +-------------------------+-------------------------+
                   |                         |                         |
                   v                         v                         v
         +-------------------+     +-------------------+     +-------------------+
         | Firebase REST API |     | Algolia Search    |     | HN Web Interface  |
         | (Read Submissions)|     | (Fast Queries)    |     | (Auth & Post)     |
         +-------------------+     +-------------------+     +-------------------+

-------------------------------------------------------------------------------
3. QUICK START & INSTALLATION
-------------------------------------------------------------------------------

  Prerequisites:
    - Python 3.12+
    - uv or pip package manager

  Setup:

    git clone https://github.com/peterlodri-sec/hackernews-mcp.git
    cd hackernews-mcp
    python3 -m venv .venv
    source .venv/bin/activate
    pip install -r requirements.txt

  Configuration (.env):

    cp .env.example .env

    Set your HackerNews credentials in .env:

    HN_USERNAME=pocok0xRE
    HN_PASSWORD=your_secure_password_here
    HN_SUBMISSION_ID=49252727

-------------------------------------------------------------------------------
4. MCP CONFIGURATION (.mcp.json)
-------------------------------------------------------------------------------

  Add the following server entry to your project or root .mcp.json file:

  {
    "mcpServers": {
      "hackernews-mcp": {
        "command": "python3",
        "args": [
          "/path/to/hackernews-mcp/hackernews_mcp.py"
        ],
        "description": "HackerNews MCP Server for LLM Agents."
      }
    }
  }

-------------------------------------------------------------------------------
5. EXPOSED MCP TOOLS
-------------------------------------------------------------------------------

  1. get_submission(item_id: int = 49252727)
     Fetches item details (title, author, score, url, comment count).
     Default item_id 49252727 targets the Vaked Constellation Show HN.

  2. get_comments(item_id: int = 49252727, limit: int = 10)
     Fetches top-level comments concurrently using asyncio.TaskGroup.

  3. post_comment(parent_id: int, text: str)
     Authenticates with HN_USERNAME / HN_PASSWORD and posts a comment.

  4. search_hn(query: str, limit: int = 5)
     Searches Algolia HN index for articles or discussions.

  5. get_user_profile(username: str = "pocok0xRE")
     Fetches karma, creation date, and about bio for a given user.

-------------------------------------------------------------------------------
6. RUNNING TESTS
-------------------------------------------------------------------------------

  Run local self-check verification:

    python3 hackernews_mcp.py --test

-------------------------------------------------------------------------------
7. LICENSE
-------------------------------------------------------------------------------

  MIT License. Copyright (c) 2026 Peter Lodri (EV / pocok0xRE).
  All rights reserved.

===============================================================================
                       THE CONSTELLATION -- VAKED.DEV
===============================================================================