📌Overview

Purpose: To provide a server for fetching structured data from Hacker News stories through the Model Context Protocol (MCP).

Overview: The Hacker News MCP Server is designed to parse HTML from Hacker News (news.ycombinator.com) and deliver structured data for various story types such as top, new, ask, show, and jobs. This server simplifies the retrieval of news content for applications and tools using the MCP framework.

Key Features:

• Story Fetching: Allows users to retrieve different types of stories (top, new, ask, show, jobs) according to their needs, enhancing flexibility in content access.

• Structured Data Output: Provides detailed and organized information for each story, including titles, URLs, points, authors, timestamps, and comment counts, making data easily consumable for further processing.

• Configurable Limits and Error Handling: Users can customize the number of stories returned (with a limit of 1-30), and the server features robust error handling for various potential issues, ensuring reliability in data fetching.

---

Hacker News MCP Server

A Model Context Protocol (MCP) server that fetches stories from Hacker News by parsing the HTML content from news.ycombinator.com and providing structured data for different types of stories (top, new, ask, show, jobs).

Features

• Fetch different types of stories: top, new, ask, show, jobs
• Get structured data including titles, URLs, points, authors, timestamps, and comment counts
• Configurable limit on number of stories returned
• Clean error handling and validation

Installation

1. Clone the repository:

git clone https://github.com/pskill9/hn-server
cd hn-server

2. Install dependencies:

npm install

3. Build the server:

npm run build

4. Add to your MCP settings configuration file (location depends on your system):

For VSCode Claude extension:

{
  "mcpServers": {
    "hacker-news": {
      "command": "node",
      "args": ["/path/to/hn-server/build/index.js"]
    }
  }
}

Usage

The server provides a tool called get_stories to fetch stories from Hacker News.

Tool: get_stories

Parameters:

• type (string): Type of stories to fetch
  • Options: top, new, ask, show, jobs
  • Default: top
• limit (number): Number of stories to return
  • Range: 1-30
  • Default: 10

Example usage:

use_mcp_tool with:
server_name: "hacker-news"
tool_name: "get_stories"
arguments: {
  "type": "top",
  "limit": 5
}

Sample output:

[
  {
    "title": "Example Story Title",
    "url": "https://example.com/story",
    "points": 100,
    "author": "username",
    "time": "2024-12-28T00:03:05",
    "commentCount": 50,
    "rank": 1
  }
]

Integrating with Claude

To use this MCP server with Claude:

1. Install the Claude desktop app or VSCode Claude extension.
2. Configure the MCP server in your settings.
3. Use Claude's natural language interface to interact with Hacker News.

Configuration

For the Claude desktop app, add the server configuration to:

// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
// Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "hacker-news": {
      "command": "node",
      "args": ["/path/to/hn-server/build/index.js"]
    }
  }
}

For the VSCode Claude extension, add to:

{
  "mcpServers": {
    "hacker-news": {
      "command": "node",
      "args": ["/path/to/hn-server/build/index.js"]
    }
  }
}

Example Interactions

Once configured, you can use natural language commands like:

• Show me the top 5 stories from Hacker News
• What are the latest Ask HN posts?
• Get me the top Show HN submissions from today

Claude will automatically fetch the appropriate stories.

Story Object Structure

Each story contains:

• title (string): The story title
• url (string, optional): URL of the story (may be internal HN URL for text posts)
• points (number): Number of upvotes
• author (string): Username of the poster
• time (string): Timestamp of when the story was posted
• commentCount (number): Number of comments
• rank (number): Position in the list

Development

The server is built with:

• TypeScript
• Model Context Protocol SDK
• Axios for HTTP requests
• Cheerio for HTML parsing

To modify the server:

1. Edit src/index.ts
2. Rebuild:

npm run build

Error Handling

The server handles errors such as:

• Invalid story types
• Network failures
• HTML parsing errors
• Invalid parameters

Errors return appropriate codes and descriptive messages.

Contributing

Contributions are welcome! Feel free to submit a Pull Request.

License

MIT License. Use freely in your projects.