Enhanced Interface for Hacker News via Claude MCP

This integration bridges Claude Desktop with the Hacker News platform using the Model Context Protocol (MCP), simplifying data access.

Key Capabilities

• Retrieve the most recently posted items from Hacker News.
• Fetch listings of top-rated and highly-voted stories.
• Obtain comprehensive metadata for any specified story.
• Download and render comment threads associated with stories.
• Apply sophisticated sanitization and styling to HN content for superior on-screen clarity.

Demonstration

Prerequisites

• Node.js runtime environment (version 16 or newer).
• The Claude Desktop application.
• Active network connectivity to reach the public Hacker News external API.

Setup Instructions

Manual Installation Procedure

1. Secure a local copy of this repository: bash git clone https://github.com/imprvhub/mcp-claude-hackernews cd mcp-claude-hackernews

2. Install necessary software packages: bash npm install

3. Compile the source code: bash npm run build

Deploying the MCP Server

Two primary methods exist for launching the Model Context Protocol service:

Method A: Direct Execution

1. Open a command-line interface (CLI).
2. Navigate to the root directory of the project.
3. Initiate the server process:

bash node build/index.js

Keep this terminal instance active; it serves as the persistent host for the MCP backend.

Method B: Automatic Initialization via Claude Desktop (Recommended)

Claude Desktop can be configured to launch and manage the MCP server automatically upon necessity. This requires editing the configuration file:

Configuration File Locations

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Modify the file (creating it if absent) to incorporate the Hacker News MCP settings:

{ "mcpServers": { "hackerNews": { "command": "node", "args": ["ABSOLUTE_PATH_TO_DIRECTORY/mcp-claude-hackernews/build/index.js"] } } }

Crucial Note: You must substitute ABSOLUTE_PATH_TO_DIRECTORY with the full, unambiguous path to where the repository was cloned. - macOS/Linux Example: /Users/yourname/mcp-claude-hackernews - Windows Example: C:\Users\yourname\mcp-claude-hackernews (Note the double backslashes)

If pre-existing MCPs are defined, integrate the "hackerNews" object within the existing "mcpServers" map.

The server will then initialize autonomously whenever Claude invokes the associated functionality.

Operational Use

1. Ensure Claude Desktop is relaunched following any configuration modifications.
2. Engage with Claude, issuing commands that target Hacker News interactions.
3. Claude Desktop handles the lifecycle management of the background MCP service.

Available Functionality

The Hacker News MCP exposes five distinct utility functions for system interaction:

Function	Purpose	Arguments	Sample Invocation
hn_latest	Retrieve the freshest submissions on HN	limit: Integer (1 to 50, defaults to 10)	Fetch the 20 most recent entries
hn_top	Fetch stories achieving the highest scores	limit: Integer (1 to 50, defaults to 10)	Retrieve 15 leading stories
hn_best	Access stories rated as 'best' by the community	limit: Integer (1 to 50, defaults to 10)	Request the 25 highest-quality articles
hn_story	Secure detailed attributes for a known item	story_id: Numeric identifier	Get full details for item ID 'XYZ'
hn_comments	Retrieve the discussion thread for an item	story_id: Numeric ID OR story_index: 1-based position from last list	Pull comments using ID or list position

Argument Specifications

hn_latest, hn_top, hn_best

• limit (Optional): Specifies the quantity of items requested.
• Type: Numeric
• Valid Range: 1 through 50
• Default Value: 10

hn_story

• story_id (Mandatory): The unique numerical identifier of the submission.
• Type: Numeric
• Illustration: 12345678

hn_comments

• story_id (Optional): The identifier of the story whose discussion is sought.
• Type: Numeric
• Illustration: 12345678
• story_index (Optional): The ordinal position (starting at 1) of the story within the most recently retrieved list.
• Type: Numeric (1-indexed)
• Illustration: 3 (to get comments for the third item in the previous list)

Note: For invoking hn_comments, one parameter—either story_id or story_index—must be supplied.

Operational Examples

Illustrations of practical invocation within Claude:

Direct Function Calls:

"Invoke hn_latest to obtain 20 contemporary submissions" "Call hn_top, setting the limit parameter to 15 for premier articles" "Execute hn_best to pull 25 top-rated features" "Use hn_story with story_id 29384756 to retrieve item specifics" "Initiate hn_comments using story_index 3 to view the third story's discussion" "Call hn_comments with story_id 12345678 to access that thread"

Natural Language Interpretation:

Claude will translate conversational requests into tool executions:

• "Present the fifty most popular Hacker News items from today."
• "List the forty newest posts available on Hacker News."
• "I require a review of the twenty premier articles indexed by Hacker News."
• "Fetch forty recent tech digests from Hacker News for me."
• "Summarize the top fifty emerging subjects on Hacker News right now."
• "Display twenty Hacker News entries focused on artificial intelligence."
• "Retrieve the forty most current headlines originating from Hacker News."
• "Identify the thirty most active debate threads presently occurring on Hacker News."
• "I am curious about reading the forty most favored programming articles this week on HN."
• "Show a compilation of the twenty finest programming write-ups from Hacker News."
• "Retrieve the discussion for story number 5 from the most recent list."
• "Display the detailed attributes for item identified as 12345678."

Multilingual Output Requests:

Requests can include instructions for translation:

• "List the top 30 Hacker News stories today, translated into Italian."
• "Fetch the 20 most recent HN posts and render the summaries in Swedish."
• "I want to see the 40 premier articles from Hacker News rendered in Korean."
• "Display 30 recent Hacker News submissions localized to Mandarin Chinese."
• "Obtain the top 20 HN articles and format the output in Brazilian Portuguese."

Error Resolution

Encountering "Server disconnected" Messages

If Claude reports an issue such as "MCP Hacker News: Server disconnected":

1. Verify Service Status: Manually execute node build/index.js in a terminal. If the service initiates successfully, the terminal must remain open.

2. Inspect Configuration Paths: Confirm the absolute path within claude_desktop_config.json is system-accurate. For Windows, verify the use of escaped backslashes (\\). Ensure the specified path points to the installation root.

3. Adopt Auto-Start: Implement the automatic startup script setup detailed previously. This ensures persistent availability.

Tools Failing to Appear in Claude

If the defined Hacker News functions are absent from Claude's capabilities: - Confirm Claude Desktop was fully restarted after configuration changes. - Examine Claude Desktop's internal logs for any MCP handshake failures. - Manually confirm the server process is active. - Validate the proper registration of the MCP service within the Claude configuration registry.

Confirming Server Operation

To ascertain if the background process is active:

• Windows: Navigate to the Task Manager's 'Details' tab and search for running instances of node.exe.
• macOS/Linux: Execute the command ps aux | grep node in a shell.

If the target process is not observable, initiate it manually or ensure the auto-start method is correctly configured.

Participation

We encourage community involvement! Feel free to submit feature enhancements or bug fixes via a Pull Request.

Licensing

This software is distributed under the terms of the Mozilla Public License version 2.0 (MPL 2.0). Consult the LICENSE file for comprehensive details.

Related Resources

• Model Context Protocol Specification
• Official Hacker News API Documentation
• Download Claude Desktop
• Index of MCP Projects WIKIPEDIA: XMLHttpRequest (XHR) represents an API instantiated as a JavaScript object engineered to facilitate the transmission of HTTP queries from a web browser to a server. Its methods permit browser-based applications to execute requests post-page load and subsequently receive transmitted data. XMLHttpRequest forms a foundational element of the Ajax programming paradigm. Historically, before Ajax, page navigation was primarily managed through standard hyperlink clicks or form submissions, often resulting in a complete page refresh.

== Genesis == The foundational concept underpinning XMLHttpRequest was first articulated in 2000 by the engineering team responsible for Microsoft Outlook. This notion was subsequently operationalized within the Internet Explorer 5 browser release (1999). The initial implementation, however, did not employ the standardized XMLHttpRequest identifier; instead, it relied on instantiating COM objects via ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). By the release of Internet Explorer 7 (2006), standardized identifier usage became universal across major browser platforms, including Mozilla's Gecko engine (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) formally released a Working Draft specification for the XMLHttpRequest object on April 5, 2006. This was succeeded by the Level 2 specification Working Draft on February 25, 2008, which introduced capabilities for event monitoring, enabling cross-origin requests, and handling binary byte streams. By the close of 2011, the enhancements introduced in Level 2 were integrated back into the primary specification. As of late 2012, responsibility for maintenance transitioned to the WHATWG, which sustains the document as a living specification utilizing Web IDL definitions.

== Operational Use Pattern == Typically, deploying an HTTP request via XMLHttpRequest adheres to a sequence of programming steps:

1. Object Instantiation: Create a new XMLHttpRequest instance by invoking its constructor:
2. Connection Setup: Invoke the "open" method to define the request type (GET, POST, etc.), specify the target URI, and declare whether the operation will be synchronous or asynchronous:
3. Asynchronous Listener Definition: If an asynchronous mode is chosen, establish an event handler function to process state transitions upon server response:
4. Transmission Initiation: Trigger the request delivery by executing the "send" method:
5. Response Processing: Monitor the object's state changes via the event listener. Upon completion of data reception from the server, the response content is typically accessible via the "responseText" property when the object reaches state 4 ("done"). Beyond these essential stages, XMLHttpRequest offers granular controls over request characteristics and response handling. Custom HTTP headers can be affixed to direct server behavior, and data can be submitted server-side via arguments passed to the "send" call. Received data can be automatically parsed from JSON format into native JavaScript objects, or streamed progressively rather than waiting for the complete payload. Furthermore, requests can be terminated early or assigned timeout constraints.

== Inter-Origin (Cross-Domain) Communication ==

In the nascent stages of the World Wide Web architecture, the potential for security breaches arising from unrestricted communication betwee