# HackerNews MCP Server Examples
This directory contains examples showing how to use the HackerNews MCP Server in different scenarios.
## Table of Contents
- [Basic Search](#basic-search)
- [Advanced Filtering](#advanced-filtering)
- [Story Details](#story-details)
- [User Profiles](#user-profiles)
- [Integration Examples](#integration-examples)
## Basic Search
### Search for AI-related stories
```typescript
// In Claude Desktop or VS Code with Copilot Chat
"Find recent stories about artificial intelligence on Hacker News"
```
**Expected Response:**
Returns stories matching "artificial intelligence" sorted by relevance, including title, URL, points, comments count, and author.
### Get front page stories
```typescript
"Show me the current Hacker News front page"
```
**Expected Response:**
Returns the top 30 stories currently on HN's front page.
## Advanced Filtering
### Search with point threshold
```typescript
"Find AI stories with at least 100 points"
```
**MCP Tool Call:**
```json
{
"method": "tools/call",
"params": {
"name": "search_stories",
"arguments": {
"query": "AI",
"numericFilters": "points>=100",
"hitsPerPage": 20
}
}
}
```
### Search by date range
```typescript
"Find TypeScript stories from the last week"
```
**MCP Tool Call:**
```json
{
"method": "tools/call",
"params": {
"name": "search_by_date",
"arguments": {
"query": "TypeScript",
"numericFilters": "created_at_i>1698796800",
"hitsPerPage": 20
}
}
}
```
## Story Details
### Get full story with comments
```typescript
"Get the full story and comments for the 'Ask HN: Who is hiring?' post"
```
**MCP Tool Call:**
```json
{
"method": "tools/call",
"params": {
"name": "get_story",
"arguments": {
"id": 8863
}
}
}
```
**Expected Response:**
Complete story object with nested comment tree, including:
- Story metadata (title, URL, points, etc.)
- All top-level comments
- Nested replies up to full depth
- Comment scores and timestamps
## User Profiles
### Get user information
```typescript
"Tell me about the HN user 'pg'"
```
**MCP Tool Call:**
```json
{
"method": "tools/call",
"params": {
"name": "get_user",
"arguments": {
"username": "pg"
}
}
}
```
**Expected Response:**
```json
{
"id": "pg",
"delay": 0,
"created": 1160418092,
"karma": 45572,
"about": "I run <a href=\"https://ycombinator.com\"...",
"submitted": [8863, 8862, ...]
}
```
## Integration Examples
### VS Code Setup
1. **Install the server:**
```bash
npm install -g hn-mcp-server
```
2. **Configure in VS Code:**
```json
{
"hackernews": {
"command": "hn-mcp-server",
"env": {
"DEBUG": "1"
}
}
}
```
3. **Use in Copilot Chat:**
```
@workspace What MCP tools are available?
Show me top AI stories from HN
```
### Claude Desktop Setup
**claude_desktop_config.json:**
```json
{
"mcpServers": {
"hackernews": {
"command": "hn-mcp-server"
}
}
}
```
### Programmatic Usage
```javascript
// Using the test server script
const { spawn } = require('child_process');
const server = spawn('node', ['dist/index.js'], {
stdio: ['pipe', 'pipe', 'pipe']
});
// Send MCP initialize request
const initRequest = {
jsonrpc: '2.0',
id: 1,
method: 'initialize',
params: {
protocolVersion: '2024-11-05',
capabilities: {},
clientInfo: {
name: 'example-client',
version: '1.0.0'
}
}
};
server.stdin.write(JSON.stringify(initRequest) + '\n');
```
## Error Handling Examples
### Rate Limiting
When API limits are approached:
```json
{
"jsonrpc": "2.0",
"id": 123,
"error": {
"code": -32000,
"message": "Rate limit exceeded. 9500/10000 requests used this hour.",
"data": {
"retryAfter": 3600,
"limit": 10000,
"remaining": 500
}
}
}
```
### Invalid Parameters
```json
{
"jsonrpc": "2.0",
"id": 124,
"error": {
"code": -32602,
"message": "Invalid parameters: 'id' must be a number",
"data": {
"expected": "number",
"received": "string",
"field": "id"
}
}
}
```
## Performance Tips
1. **Use specific queries** - More specific searches return faster
2. **Limit results** - Use `hitsPerPage` to control response size
3. **Cache results** - Consider caching for frequently accessed data
4. **Batch requests** - Group related queries when possible
## Troubleshooting
### Common Issues
1. **No tools available**: Check VS Code/Copilot extension versions
2. **Connection errors**: Verify Node.js 20+ and correct path
3. **Rate limiting**: Wait for hourly reset or reduce request frequency
4. **Empty results**: Try broader search terms or check query syntax
### Debug Mode
Enable debug logging:
```bash
DEBUG=1 hn-mcp-server
```
This provides detailed logs for troubleshooting.
