vishgupt/hkn-mcp-server

Hacker News MCP Server

A Spring Boot-based MCP (Model-Controller-Provider) server that provides a RESTful API interface to the Hacker News API. This server is designed to work seamlessly with MCP clients like Windsurf.

Features

• RESTful API endpoints for Hacker News content
• Caching support using Caffeine
• Non-blocking WebClient implementation
• Comprehensive test coverage
• Easy integration with MCP clients

Prerequisites

• Java 17 or higher
• Gradle 8.5 or higher (included via Gradle Wrapper)

Building the Project

1. Clone the repository:

   git clone <repository-url>
   cd hkn-mcp-server
   

2. Build the project:

   ./gradlew build
   

3. Run the tests:

   ./gradlew test
   

4. Run the application:

   ./gradlew bootRun
   

The server will start on port 8080 by default.

API Endpoints

Get Item by ID

GET /api/v1/news/item/{id}

Retrieves a specific Hacker News item by its ID.

Get Top Stories

GET /api/v1/news/top?limit={limit}

Retrieves the top stories. Default limit is 30.

Get New Stories

GET /api/v1/news/new?limit={limit}

Retrieves the newest stories. Default limit is 30.

Get Best Stories

GET /api/v1/news/best?limit={limit}

Retrieves the best stories. Default limit is 30.

Using with MCP Clients

Windsurf Integration

1. Configure your Windsurf client to point to this MCP server:

   {
     "mcp": {
       "server": "http://localhost:8080"
     }
   }
   

2. The MCP server exposes the following resource types:

   • hn_item: Individual Hacker News items (stories, comments, etc.)
   • hn_top: Top stories feed
   • hn_new: New stories feed
   • hn_best: Best stories feed

3. Example Windsurf queries:

   // Get a specific item
   GET mcp://hn_item/12345
   
   // Get top stories
   GET mcp://hn_top?limit=10
   
   // Get new stories
   GET mcp://hn_new?limit=20
   
   // Get best stories
   GET mcp://hn_best?limit=15
   

Caching

The server implements caching using Caffeine with the following configuration:

• Maximum cache size: 1000 entries
• Cache expiry: 5 minutes after write
• Separate caches for items and story lists

Development

Project Structure

src/
├── main/
│   ├── java/
│   │   └── com/mount/rainier/hkn/mcp/
│   │       ├── config/
│   │       ├── controller/
│   │       ├── model/
│   │       └── service/
│   └── resources/
└── test/
    └── java/
        └── com/mount/rainier/hkn/mcp/
            ├── config/
            ├── controller/
            ├── model/
            └── service/

Running Tests

# Run all tests
./gradlew test

# Run specific test class
./gradlew test --tests "com.mount.rainier.hkn.mcp.service.HackerNewsServiceTest"

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.