# Directory Structure
```
├── .gitignore
├── Claude.png
├── LICENSE
├── package-lock.json
├── package.json
├── README.md
├── src
│ └── index.ts
└── tsconfig.json
```
# Files
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
1 | # Dependencies
2 | node_modules/
3 | npm-debug.log*
4 | yarn-debug.log*
5 | yarn-error.log*
6 |
7 | # Build output
8 | build/
9 | dist/
10 | *.tsbuildinfo
11 |
12 | # IDE and editor files
13 | .idea/
14 | .vscode/
15 | *.swp
16 | *.swo
17 | .DS_Store
18 |
19 | # Environment variables
20 | .env
21 | .env.local
22 | .env.*.local
23 |
24 | # Logs
25 | logs/
26 | *.log
27 |
28 | # Test coverage
29 | coverage/
30 |
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Hacker News MCP Server
2 |
3 | A Model Context Protocol (MCP) server that provides tools for fetching stories from Hacker News. This server parses the HTML content from news.ycombinator.com and provides structured data for different types of stories (top, new, ask, show, jobs).
4 |
5 | <a href="https://glama.ai/mcp/servers/oge85xl22f"><img width="380" height="200" src="https://glama.ai/mcp/servers/oge85xl22f/badge" alt="Hacker News MCP server" /></a>
6 |
7 | ## Features
8 |
9 | - Fetch different types of stories (top, new, ask, show, jobs)
10 | - Get structured data including titles, URLs, points, authors, timestamps, and comment counts
11 | - Configurable limit on number of stories returned
12 | - Clean error handling and validation
13 |
14 | ## Installation
15 |
16 | 1. Clone the repository:
17 | ```bash
18 | git clone https://github.com/pskill9/hn-server
19 | cd hn-server
20 | ```
21 |
22 | 2. Install dependencies:
23 | ```bash
24 | npm install
25 | ```
26 |
27 | 3. Build the server:
28 | ```bash
29 | npm run build
30 | ```
31 |
32 | 4. Add to your MCP settings configuration file (location depends on your system):
33 |
34 | For VSCode Claude extension:
35 | ```json
36 | {
37 | "mcpServers": {
38 | "hacker-news": {
39 | "command": "node",
40 | "args": ["/path/to/hn-server/build/index.js"]
41 | }
42 | }
43 | }
44 | ```
45 |
46 | ## Usage
47 |
48 | The server provides a tool called `get_stories` that can be used to fetch stories from Hacker News.
49 |
50 | ### Tool: get_stories
51 |
52 | Parameters:
53 | - `type` (string): Type of stories to fetch
54 | - Options: 'top', 'new', 'ask', 'show', 'jobs'
55 | - Default: 'top'
56 | - `limit` (number): Number of stories to return
57 | - Range: 1-30
58 | - Default: 10
59 |
60 | Example usage:
61 | ```typescript
62 | use_mcp_tool with:
63 | server_name: "hacker-news"
64 | tool_name: "get_stories"
65 | arguments: {
66 | "type": "top",
67 | "limit": 5
68 | }
69 | ```
70 |
71 | Sample output:
72 | ```json
73 | [
74 | {
75 | "title": "Example Story Title",
76 | "url": "https://example.com/story",
77 | "points": 100,
78 | "author": "username",
79 | "time": "2024-12-28T00:03:05",
80 | "commentCount": 50,
81 | "rank": 1
82 | },
83 | // ... more stories
84 | ]
85 | ```
86 |
87 | ## Integrating with Claude
88 |
89 | To use this MCP server with Claude, you'll need to:
90 |
91 | 1. Have the Claude desktop app or VSCode Claude extension installed
92 | 2. Configure the MCP server in your settings
93 | 3. Use Claude's natural language interface to interact with Hacker News
94 |
95 | ### Configuration
96 |
97 | For the Claude desktop app, add the server configuration to:
98 | ```json
99 | // ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
100 | // %APPDATA%\Claude\claude_desktop_config.json (Windows)
101 | {
102 | "mcpServers": {
103 | "hacker-news": {
104 | "command": "node",
105 | "args": ["/path/to/hn-server/build/index.js"]
106 | }
107 | }
108 | }
109 | ```
110 |
111 | For the VSCode Claude extension, add to:
112 | ```json
113 | // VSCode Settings JSON
114 | {
115 | "mcpServers": {
116 | "hacker-news": {
117 | "command": "node",
118 | "args": ["/path/to/hn-server/build/index.js"]
119 | }
120 | }
121 | }
122 | ```
123 |
124 | ### Example Interactions
125 |
126 | Once configured, you can interact with Claude using natural language to fetch Hacker News stories. Examples:
127 |
128 | - "Show me the top 5 stories from Hacker News"
129 | - "What are the latest Ask HN posts?"
130 | - "Get me the top Show HN submissions from today"
131 |
132 | Claude will automatically use the appropriate parameters to fetch the stories you want.
133 |
134 | 
135 |
136 | ### Story Object Structure
137 |
138 | Each story object contains:
139 | - `title` (string): The story title
140 | - `url` (string, optional): URL of the story (may be internal HN URL for text posts)
141 | - `points` (number): Number of upvotes
142 | - `author` (string): Username of the poster
143 | - `time` (string): Timestamp of when the story was posted
144 | - `commentCount` (number): Number of comments
145 | - `rank` (number): Position in the list
146 |
147 | ## Development
148 |
149 | The server is built using:
150 | - TypeScript
151 | - Model Context Protocol SDK
152 | - Axios for HTTP requests
153 | - Cheerio for HTML parsing
154 |
155 | To modify the server:
156 |
157 | 1. Make changes to `src/index.ts`
158 | 2. Rebuild:
159 | ```bash
160 | npm run build
161 | ```
162 |
163 | ## Error Handling
164 |
165 | The server includes robust error handling for:
166 | - Invalid story types
167 | - Network failures
168 | - HTML parsing errors
169 | - Invalid parameter values
170 |
171 | Errors are returned with appropriate error codes and descriptive messages.
172 |
173 | ## Contributing
174 |
175 | Contributions are welcome! Please feel free to submit a Pull Request.
176 |
177 | ## License
178 |
179 | MIT License - feel free to use this in your own projects.
180 |
```
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "compilerOptions": {
3 | "target": "ES2022",
4 | "module": "Node16",
5 | "moduleResolution": "Node16",
6 | "outDir": "./build",
7 | "rootDir": "./src",
8 | "strict": true,
9 | "esModuleInterop": true,
10 | "skipLibCheck": true,
11 | "forceConsistentCasingInFileNames": true
12 | },
13 | "include": ["src/**/*"],
14 | "exclude": ["node_modules"]
15 | }
16 |
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "name": "hn-server",
3 | "version": "0.1.0",
4 | "description": "MCP server for fetching and parsing Hacker News stories",
5 | "type": "module",
6 | "bin": {
7 | "hn-server": "./build/index.js"
8 | },
9 | "files": [
10 | "build"
11 | ],
12 | "scripts": {
13 | "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
14 | "prepare": "npm run build",
15 | "watch": "tsc --watch",
16 | "inspector": "npx @modelcontextprotocol/inspector build/index.js"
17 | },
18 | "dependencies": {
19 | "@modelcontextprotocol/sdk": "0.6.0",
20 | "axios": "^1.7.9",
21 | "cheerio": "^1.0.0"
22 | },
23 | "devDependencies": {
24 | "@types/node": "^20.11.24",
25 | "typescript": "^5.3.3"
26 | },
27 | "keywords": [
28 | "mcp",
29 | "model-context-protocol",
30 | "hacker-news",
31 | "hn",
32 | "news",
33 | "api",
34 | "scraper"
35 | ],
36 | "author": "Manav Kundra",
37 | "license": "MIT",
38 | "repository": {
39 | "type": "git",
40 | "url": "git+https://github.com/pskill9/hn-server.git"
41 | },
42 | "bugs": {
43 | "url": "https://github.com/pskill9/hn-server/issues"
44 | },
45 | "homepage": "https://github.com/pskill9/hn-server#readme"
46 | }
47 |
```
--------------------------------------------------------------------------------
/src/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | #!/usr/bin/env node
2 | import { Server } from '@modelcontextprotocol/sdk/server/index.js';
3 | import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
4 | import {
5 | CallToolRequestSchema,
6 | ErrorCode,
7 | ListToolsRequestSchema,
8 | McpError,
9 | } from '@modelcontextprotocol/sdk/types.js';
10 | import axios from 'axios';
11 | import * as cheerio from 'cheerio';
12 |
13 | interface Story {
14 | title: string;
15 | url?: string;
16 | points: number;
17 | author: string;
18 | time: string;
19 | commentCount: number;
20 | rank: number;
21 | }
22 |
23 | const isValidStoryType = (type: string): boolean => {
24 | return ['top', 'new', 'ask', 'show', 'jobs'].includes(type);
25 | };
26 |
27 | class HackerNewsServer {
28 | private server: Server;
29 | private baseUrl = 'https://news.ycombinator.com';
30 |
31 | constructor() {
32 | this.server = new Server(
33 | {
34 | name: 'hn-server',
35 | version: '0.1.0',
36 | },
37 | {
38 | capabilities: {
39 | tools: {},
40 | },
41 | }
42 | );
43 |
44 | this.setupToolHandlers();
45 |
46 | // Error handling
47 | this.server.onerror = (error) => console.error('[MCP Error]', error);
48 | process.on('SIGINT', async () => {
49 | await this.server.close();
50 | process.exit(0);
51 | });
52 | }
53 |
54 | private async fetchStories(type: string = 'top'): Promise<Story[]> {
55 | try {
56 | const url = type === 'top' ? this.baseUrl : `${this.baseUrl}/${type}`;
57 | const response = await axios.get(url);
58 | const $ = cheerio.load(response.data);
59 | const stories: Story[] = [];
60 |
61 | $('.athing').each((i, elem) => {
62 | const titleRow = $(elem);
63 | const metadataRow = titleRow.next();
64 |
65 | const rank = parseInt(titleRow.find('.rank').text(), 10);
66 | const titleElement = titleRow.find('.titleline > a').first();
67 | const title = titleElement.text();
68 | const url = titleElement.attr('href');
69 | const sitebit = titleRow.find('.sitebit');
70 |
71 | const points = parseInt(metadataRow.find('.score').text(), 10) || 0;
72 | const author = metadataRow.find('.hnuser').text();
73 | const time = metadataRow.find('.age').attr('title') || '';
74 | const commentText = metadataRow.find('a').last().text();
75 | const commentCount = parseInt(commentText.split(' ')[0]) || 0;
76 |
77 | stories.push({
78 | title,
79 | url: url?.startsWith('item?id=') ? `${this.baseUrl}/${url}` : url,
80 | points,
81 | author,
82 | time,
83 | commentCount,
84 | rank
85 | });
86 | });
87 |
88 | return stories;
89 | } catch (error) {
90 | if (axios.isAxiosError(error)) {
91 | throw new McpError(
92 | ErrorCode.InternalError,
93 | `Failed to fetch stories: ${error.message}`
94 | );
95 | }
96 | throw error;
97 | }
98 | }
99 |
100 | private setupToolHandlers() {
101 | this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
102 | tools: [
103 | {
104 | name: 'get_stories',
105 | description: 'Get stories from Hacker News',
106 | inputSchema: {
107 | type: 'object',
108 | properties: {
109 | type: {
110 | type: 'string',
111 | description: 'Type of stories to fetch (top, new, ask, show, jobs)',
112 | enum: ['top', 'new', 'ask', 'show', 'jobs'],
113 | default: 'top'
114 | },
115 | limit: {
116 | type: 'number',
117 | description: 'Number of stories to return (max 30)',
118 | minimum: 1,
119 | maximum: 30,
120 | default: 10
121 | }
122 | }
123 | }
124 | }
125 | ]
126 | }));
127 |
128 | this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
129 | if (request.params.name !== 'get_stories') {
130 | throw new McpError(
131 | ErrorCode.MethodNotFound,
132 | `Unknown tool: ${request.params.name}`
133 | );
134 | }
135 |
136 | const args = request.params.arguments as { type?: string; limit?: number };
137 | const type = args.type || 'top';
138 | const limit = Math.min(args.limit || 10, 30);
139 |
140 | if (!isValidStoryType(type)) {
141 | throw new McpError(
142 | ErrorCode.InvalidParams,
143 | `Invalid story type: ${type}. Must be one of: top, new, ask, show, jobs`
144 | );
145 | }
146 |
147 | try {
148 | const stories = await this.fetchStories(type);
149 | return {
150 | content: [
151 | {
152 | type: 'text',
153 | text: JSON.stringify(stories.slice(0, limit), null, 2)
154 | }
155 | ]
156 | };
157 | } catch (error) {
158 | if (error instanceof McpError) {
159 | throw error;
160 | }
161 | throw new McpError(
162 | ErrorCode.InternalError,
163 | `Failed to fetch stories: ${error}`
164 | );
165 | }
166 | });
167 | }
168 |
169 | async run() {
170 | const transport = new StdioServerTransport();
171 | await this.server.connect(transport);
172 | console.error('Hacker News MCP server running on stdio');
173 | }
174 | }
175 |
176 | const server = new HackerNewsServer();
177 | server.run().catch(console.error);
178 |
```