=============================================================================== 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