Hn Server

🚀 Hacker News MCP Server

A Model Context Protocol (MCP) server that provides tools to fetch stories from Hacker News. This server parses the HTML content of news.ycombinator.com and offers structured data for different types of stories (Top, New, Ask, Show, Jobs).

🚀 Quick Start

The Hacker News MCP Server is a powerful tool for retrieving structured data from Hacker News. It offers a range of features and can be easily integrated into your projects.

✨ Features

• Fetch different types of stories (Top, New, Ask, Show, Jobs).
• Obtain structured data including title, URL, points, author, timestamp, and comment count.
• Configurable limit on the number of stories to return.
• Clear 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 it to your MCP settings configuration file (the specific location depends on your system):

For the VSCode Claude extension:

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

💻 Usage Examples

Basic Usage

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

Tool: get_stories

Parameters:

• type (string): The type of stories to fetch.
  • Available values: 'top', 'new', 'ask', 'show', 'jobs'.
  • Default value: 'top'.
• limit (number): The number of stories to return.
  • Range: 1 - 30.
  • Default value: 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
  },
  // ... More stories
]

📚 Documentation

Integration with Claude

To use this MCP server with Claude, you need to:

1. Install the Claude desktop app or the 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:

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

🔧 Technical Details

Error Handling

The server includes robust error handling, covering:

• Invalid story types.
• Network failures.
• HTML parsing errors.
• Invalid parameter values.

Errors are returned with appropriate error codes and descriptive messages.

📄 License

This project is under the MIT License - feel free to use it in your projects.

🤝 Contribution

Contributions are welcome! Please feel free to submit a Pull Request.