Content
# Hacker News MCP Server for Netlify
This is a Model Context Protocol (MCP) server that integrates with the official Hacker News API, designed to be deployed to Netlify. The MCP server exposes tools and resources that enable AI assistants to access and interact with Hacker News content through the Model Context Protocol.
This project also includes a FastAPI client that provides a REST API for interacting with the MCP server, making it easy to test and integrate with other applications.
## Features
### MCP Server
- Serverless MCP server implementation integrating with the Hacker News API
- Deployed on Netlify
- Includes tools to fetch top, new, best, Ask HN, Show HN, and job stories
- Provides tools to get specific posts, comments, and user information
- Includes resources with documentation on using the Hacker News API
### MCP Client
- FastAPI REST API for interacting with the MCP server
- Interactive API documentation (Swagger UI)
- Easy testing and integration
- Python script for automated testing
## Getting Started
### Local Development
1. Clone this repository
2. Install dependencies:
```
npm install
```
3. Start the development server:
```
npm run dev
```
The MCP server will be available locally at http://localhost:8888/mcp
### Testing Your MCP Server
You can test your MCP server using either the MCP Inspector or directly with curl commands.
#### Using MCP Inspector
While the development server is running, you can test your MCP server using the MCP inspector:
```
npx @modelcontextprotocol/inspector npx mcp-remote@next http://localhost:8888/mcp
```
After deployment, you can test your deployed version:
```
npx @modelcontextprotocol/inspector npx mcp-remote@next https://your-site-name.netlify.app/mcp
```
Then open http://localhost:6274/ in your browser to interact with the MCP inspector.
#### Using curl
You can also test the MCP server directly using curl commands:
1. Initialize the MCP server:
```
curl -X POST http://localhost:8888/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"mcp/init","params":{},"id":"1"}'
```
2. List available tools:
```
curl -X POST http://localhost:8888/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"mcp/listTools","params":{},"id":"2"}'
```
3. Call a tool to get top Hacker News stories:
```
curl -X POST http://localhost:8888/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"mcp/callTool","params":{"name":"hn-get-top-stories","args":{"limit":5}},"id":"3"}'
```
Call a tool to get a specific Hacker News item:
```
curl -X POST http://localhost:8888/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"mcp/callTool","params":{"name":"hn-get-item","args":{"id":8863}},"id":"3"}'
```
4. List available resources:
```
curl -X POST http://localhost:8888/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"mcp/listResources","params":{},"id":"4"}'
```
5. Read a resource about the Hacker News API:
```
curl -X POST http://localhost:8888/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"mcp/readResource","params":{"uri":"docs://hacker-news-api-overview"},"id":"5"}'
```
## Deployment
### Deploying to Netlify
1. Push this repository to GitHub
2. Connect your repository to Netlify
3. Configure the build settings:
- Build command: leave empty (no build required)
- Publish directory: `public`
After deployment, your MCP server will be available at `https://your-site-name.netlify.app/mcp`
### Using with Claude Desktop
To use this Hacker News MCP server with Claude Desktop:
1. Go to Claude Desktop settings
2. Enable the MCP Server configuration
3. Edit the configuration file:
```json
{
"mcpServers": {
"hacker-news": {
"command": "npx",
"args": [
"mcp-remote@next",
"https://your-site-name.netlify.app/mcp"
]
}
}
}
```
4. Restart Claude Desktop
Once configured, you can ask Claude to interact with Hacker News content, for example:
- "Show me the top 5 stories from Hacker News right now"
- "Get me the details of a specific Hacker News post"
- "Search for Ask HN posts about programming"
- "Find information about a specific Hacker News user"
## Using the MCP Client
The MCP client provides a REST API interface for interacting with the MCP server. It's built with FastAPI and offers a clean, modern API with automatic documentation.
### Starting the Client
```bash
cd mcp-client
pip install -r requirements.txt
uvicorn main:app --reload
```
This will start the FastAPI server at http://localhost:8001. You can access the API documentation at http://localhost:8001/docs.
### Managing the MCP Server and FastAPI Client
The template includes several scripts to manage both the MCP server and FastAPI client:
```bash
cd mcp-client
./start.sh # Start both services in the background
./stop.sh # Stop both services gracefully
./check_status.sh # Check if services are running and view logs
./test_client.py # Test the FastAPI client endpoints
```
These scripts ensure processes keep running in the background even after you close your terminal, properly manage log files, and provide clear status information.
### Testing the Client
You can test the client using the provided test script:
```bash
cd mcp-client
./test_client.py
```
This will run a series of tests against the API endpoints and display the results.
### API Endpoints
- `GET /server` - Get server information
- `GET /tools` - List available tools
- `POST /tools/call` - Call a tool
- `GET /resources` - List available resources
- `POST /resources/read` - Read a resource
For more details, refer to the [MCP Client README](./mcp-client/README.md).
## Hacker News API Tools
This MCP server provides the following tools for interacting with the Hacker News API:
1. `hn-get-top-stories`: Fetches the current top stories from Hacker News
- Parameters: `limit` (optional, number of stories to return, default: 10, max: 500)
2. `hn-get-new-stories`: Fetches the newest stories from Hacker News
- Parameters: `limit` (optional, number of stories to return, default: 10, max: 500)
3. `hn-get-best-stories`: Fetches the best stories from Hacker News
- Parameters: `limit` (optional, number of stories to return, default: 10, max: 500)
4. `hn-get-ask-stories`: Fetches Ask HN stories from Hacker News
- Parameters: `limit` (optional, number of stories to return, default: 10, max: 200)
5. `hn-get-show-stories`: Fetches Show HN stories from Hacker News
- Parameters: `limit` (optional, number of stories to return, default: 10, max: 200)
6. `hn-get-job-stories`: Fetches job stories from Hacker News
- Parameters: `limit` (optional, number of stories to return, default: 10, max: 200)
7. `hn-get-item`: Fetches a specific item (story, comment, job, poll, etc.) from Hacker News by ID
- Parameters: `id` (required, the ID of the item to fetch)
8. `hn-get-user`: Fetches information about a specific user from Hacker News by username
- Parameters: `id` (required, the username of the user to fetch)
## Documentation Resources
The MCP server provides the following documentation resources:
1. `docs://hacker-news-api-overview`: Overview of the Hacker News API and the tools available in this MCP server
2. `docs://hacker-news-item-types`: Information about the different types of items in the Hacker News API and their properties
3. `docs://hacker-news-usage-examples`: Examples of how to use the Hacker News MCP tools with sample requests and responses
## Extending
### Extending the MCP Server
You can extend this MCP server by adding more tools and resources to the `getServer` function in `netlify/functions/mcp-server.js`. Follow the existing examples and refer to the [Model Context Protocol documentation](https://modelcontextprotocol.io/) for more information.
### Extending the MCP Client
To add new endpoints to the MCP client, edit the `main.py` file in the `mcp-client` directory. The client is built with FastAPI, which makes it easy to add new routes and functionality.
## Learn More
- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [Netlify Functions Documentation](https://docs.netlify.com/functions/overview/)
- [Claude Desktop Documentation](https://claude.ai/docs)
- [FastAPI Documentation](https://fastapi.tiangolo.com/)
