# HackerNews MCP Server

A Model Context Protocol (MCP) server that provides comprehensive access to the HackerNews API. This server enables AI assistants and other MCP clients to search, retrieve, and interact with HackerNews content including stories, comments, polls, users, and more.

## Features

This MCP server exposes 15 tools covering all available HackerNews API endpoints:

### Search & Discovery Tools
- **search-posts** - Search posts by relevance (sorted by relevance, points, then comments)
- **search-posts-by-date** - Search posts sorted by date (most recent first)
- **search-by-url** - Find posts linking to a specific URL
- **search-by-time-range** - Search posts within a specific time range

### Content Retrieval Tools
- **get-front-page** - Get all stories currently on the HackerNews front page
- **get-latest-stories** - Get the most recent stories
- **get-latest-comments** - Get the most recent comments
- **get-show-hn** - Get "Show HN" posts (user projects)
- **get-ask-hn** - Get "Ask HN" posts (questions)
- **get-polls** - Get latest polls
- **get-top-stories** - Get stories with minimum points threshold

### Item & User Tools
- **get-item** - Get a specific item (story, comment, poll) by ID
- **get-user** - Get user information and karma
- **get-posts-by-author** - Get all posts by a specific author
- **get-story-comments** - Get all comments for a specific story

## Installation

### Prerequisites
- Node.js 18 or higher
- npm or yarn

### Setup

1. Clone this repository:
```bash
git clone <repository-url>
cd hn-mcp-server-vibe
```

2. Install dependencies:
```bash
npm install
```

3. Build the server:
```bash
npm run build
```

## Usage

### Running the Server Directly

You can run the server directly with Node.js:

```bash
npm start
```

Or during development:
```bash
npm run dev
```

### Configuring with Claude Desktop

To use this server with Claude Desktop, add the following configuration to your Claude Desktop config file:

**On macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**On Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "hackernews": {
      "command": "node",
      "args": ["/absolute/path/to/hn-mcp-server-vibe/build/index.js"]
    }
  }
}
```

Replace `/absolute/path/to/hn-mcp-server-vibe` with the actual path to your installation.

### Configuring with Other MCP Clients

For other MCP clients that support stdio transport, configure them to spawn:
```bash
node /path/to/hn-mcp-server-vibe/build/index.js
```

## API Examples

### Search for Posts
```javascript
// Search for AI-related stories
{
  "tool": "search-posts",
  "arguments": {
    "query": "artificial intelligence",
    "tags": "story",
    "page": 0,
    "hitsPerPage": 20
  }
}
```

### Get Front Page Stories
```javascript
{
  "tool": "get-front-page",
  "arguments": {
    "hitsPerPage": 30
  }
}
```

### Get User Information
```javascript
{
  "tool": "get-user",
  "arguments": {
    "username": "pg"
  }
}
```

### Get Top Stories
```javascript
// Get stories with at least 500 points
{
  "tool": "get-top-stories",
  "arguments": {
    "minPoints": 500,
    "hitsPerPage": 10
  }
}
```

### Search by Time Range
```javascript
// Get stories from the last 24 hours
{
  "tool": "search-by-time-range",
  "arguments": {
    "tags": "story",
    "startTime": 1728691200,  // Unix timestamp
    "endTime": 1728777600,     // Unix timestamp
    "hitsPerPage": 20
  }
}
```

## Available Tags

When using search tools, you can filter by the following tags:
- `story` - Regular stories
- `comment` - Comments
- `poll` - Polls
- `pollopt` - Poll options
- `show_hn` - Show HN posts
- `ask_hn` - Ask HN posts
- `front_page` - Currently on front page
- `author_USERNAME` - Posts by specific author (e.g., `author_pg`)
- `story_ID` - Comments for specific story (e.g., `story_1234`)

Tags can be combined with commas (AND) or parentheses for OR: `author_pg,(story,poll)`

## Available Numeric Filters

For advanced filtering:
- `created_at_i` - Creation timestamp (Unix seconds)
- `points` - Number of points/upvotes
- `num_comments` - Number of comments

Operators: `<`, `<=`, `=`, `>`, `>=`

Examples:
- `points>100` - More than 100 points
- `created_at_i>1672531200` - After specific date
- `points>=50,num_comments>10` - Multiple conditions

## Response Format

All tools return structured data with:
- **content** - Text representation of the response
- **structuredContent** - Parsed JSON object for programmatic access

Search results include:
- `hits` - Array of matching items
- `nbHits` - Total number of matches
- `nbPages` - Total number of pages
- `page` - Current page number
- `hitsPerPage` - Results per page

## Rate Limits

The HackerNews API limits requests to **10,000 per hour per IP address**. This server does not implement additional rate limiting, so clients should be mindful of this constraint.

## Development

### Project Structure
```
hn-mcp-server-vibe/
├── src/
│   └── index.ts          # Main server implementation
├── build/                 # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md
```

### Building
```bash
npm run build
```

### Running in Development
```bash
npm run dev
```

## API Reference

Full HackerNews API documentation: https://hn.algolia.com/api

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## Troubleshooting

### Server not connecting
- Ensure the build directory exists and contains compiled JavaScript
- Check that Node.js version is 18 or higher
- Verify the absolute path in your MCP client configuration

### No results returned
- Check your search query and filters
- Verify the API is accessible: https://hn.algolia.com/api
- Check rate limits haven't been exceeded

### TypeScript errors
- Run `npm install` to ensure all dependencies are installed
- Run `npm run build` to compile TypeScript

## Support

For issues specific to this MCP server, please open an issue on the repository.

For questions about the Model Context Protocol, see: https://modelcontextprotocol.io

For questions about the HackerNews API, see: https://hn.algolia.com/api