fguillen/TinyHNewsMCP

TinyHNews MCP Server

A Model Context Protocol (MCP) server that wraps the TinyHNews gem to provide Hacker News top stories functionality to AI assistants.

Overview

This MCP server exposes a single tool top_stories that fetches top stories from Hacker News with configurable parameters for customizing the output.

Features

• Fetch configurable number of top stories from Hacker News
• Control comment depth and limits
• Option for concise output (titles and metadata only)
• Configurable article content length
• Built using fast-mcp gem for robust MCP implementation

Installation

1. Clone this repository
2. Install dependencies:

   bundle install
   

Usage

With Claude Desktop

Add the following to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "tiny-hnews": {
      "command": "ruby",
      "args": ["/path/to/TinyHNewsMCP/server.rb"]
    }
  }
}

With VSCode

Add the following to your VSCode settings to configure the MCP server:

Method 1: Via settings.json Open your VSCode settings.json file and add:

{
  "mcp.servers": {
    "tiny-hnews": {
      "command": "ruby",
      "args": ["/path/to/TinyHNewsMCP/server.rb"]
    }
  }
}

Method 2: Via MCP extension settings

1. Install the MCP extension for VSCode
2. Go to Settings > Extensions > MCP
3. Add a new server with:
   • Name: tiny-hnews
   • Command: ruby
   • Args: ["/path/to/TinyHNewsMCP/server.rb"]

Testing with MCP Inspector

You can test the server using the official MCP inspector:

npx @modelcontextprotocol/inspector server.rb

Examples of prompts

Here are some example prompts you can use with the TinyHNews MCP server:

Basic Usage

• "Show me the top 5 Hacker News stories"
• "Get the latest Hacker News stories"
• "What are the trending stories on Hacker News today?"

Customized Requests

• "Get the top 10 Hacker News stories with full article content"
• "Show me 3 top stories but only titles and basic info (concise mode)"
• "Fetch 8 top stories with deeper comments (depth 4) and more comments per story"

Specific Parameters

• "Get top stories with only 20 lines of article content each"
• "Show me top stories with minimal comments (limit 5 per story)"
• "Fetch stories with maximum comment depth and show 200 lines of each article"

Analysis Requests

• "Summarize the top 5 Hacker News stories for me"
• "What are the main topics trending on Hacker News today?"
• "Compare the top 3 stories and tell me which seems most interesting"
• "Find any AI or technology related stories in the top 10"

Tool: top_stories

Fetches top stories from Hacker News with the following configurable parameters:

Parameters

• number (optional, integer, default: 5): Number of top stories to fetch
• depth (optional, integer, default: 2): Depth of comments to fetch
• limit (optional, integer, default: 10): Limit number of comments per story
• concise (optional, boolean, default: false): Only show titles and metadata
• lines (optional, integer, default: 50): Number of lines of the article to show

Example Usage

{
  "name": "top_stories",
  "arguments": {
    "number": 10,
    "depth": 3,
    "limit": 20,
    "concise": false,
    "lines": 100
  }
}

Response Format

The tool returns a JSON object with:

• success: Boolean indicating if the request was successful
• count: Number of stories returned
• stories: Array of story objects

Each story object contains:

• id: Story ID
• title: Story title
• by: Author username
• score: Story score
• time: Publication time (formatted)
• url: Story URL
• descendants: Number of comments
• article: Article content (if not concise mode)
• comments: Array of comment texts (if not concise mode)

Dependencies

• Ruby 3.2+
• fast-mcp gem
• tiny_hnews gem

License

MIT License