What is Mcp News Server

mcp-news-server is a clean and minimal MCP wrapper around the Hacker News API, designed to showcase the Modular Contract Protocol (MCP) structure, typed contracts, and LLM-compatible interfaces using Zod and TypeScript.

Use cases

Use cases include building applications that need to fetch and display Hacker News stories, integrating with other services that require LLM compatibility, and demonstrating the MCP process for educational purposes.

How to use

To use mcp-news-server, you can access its endpoints such as /api/listTopStories to get the top stories, or /api/getStory/{id} to retrieve a specific story. The server is deployed and can be accessed via the live demo link.

Key features

Key features include contract-driven API design with Zod for typed inputs and outputs, composable and self-descriptive structures, OpenAPI integration for LLM function calling, and a modular architecture that separates contracts, resolvers, and handlers.

Where to use

mcp-news-server can be used in fields such as software development, API integration, and data retrieval applications, especially where structured and type-safe interactions with APIs are required.

📰 MCP News Server

A clean, minimal MCP wrapper around the Hacker News API — built to showcase the Modular Contract Protocol (MCP) structure, typed contracts, and LLM-compatible interface.

🌐 Live Demo

🟢 Deployed at: https://mcp-news-server.onrender.com

Try It Now

• GET /api/listTopStories
• GET /api/getStory/8863
• GET /openapi.json

🚀 What is This?

This project demonstrates how to transform an existing REST API into an MCP-compliant server. It wraps the Hacker News API using modular components:

• Contracts defined with zod and zod-openapi for typed and documented inputs/outputs
• Resolvers for business logic
• Handlers for HTTP routing
• OpenAPI integration for LLM function calling

My goal with this wrapper is to learn and demonstrate the full MCP process, and prepare APIs for the MCP marketplace — where tools and agents can discover and use them programmatically.

💡 Why Use MCP Instead of Raw REST Calls?

Traditional REST APIs:

• ❌ No contracts
• ❌ Inconsistent formats
• ❌ Not LLM friendly

MCP APIs:

• ✅ Contract-driven (with Zod)
• ✅ Composable and self-descriptive
• ✅ LLM-ready (via OpenAPI and function schemas)

🔧 Tech Stack

• Node.js + Express
• TypeScript
• Zod + zod-openapi
• Axios
• Deployed on Render

📁 Project Structure

src/
├── contracts/                # Zod + OpenAPI metadata
├── resolvers/                # Business logic
├── handlers/                 # Express routes
├── utils/                    # Hacker News client
├── docs/openapi.ts           # OpenAPI spec generator (zod-openapi)
├── setup/zod-openapi-init.ts # Shared zod setup with OpenAPI support
└── server.ts                 # Main entry point

🗂️ Endpoints

1. GET /api/listTopStories

Returns a list of top Hacker News story IDs.

Example:

curl https://mcp-news-server.onrender.com/api/listTopStories

Response:

[
  38643,
  38642,
  38641
]

2. GET /api/getStory/:id

Returns full story data for a given story ID.

Example:

curl https://mcp-news-server.onrender.com/api/getStory/8863

Response:

{
  "id": 8863,
  "title": "My YC app: Dropbox - Throw away your USB drive",
  "url": "http://www.getdropbox.com/u/2/screencast.html",
  "score": 111,
  "by": "dhouston",
  "time": 1175714200,
  "type": "story"
}

🧠 How LLMs Can Use This

Each MCP endpoint is:

• Strictly typed
• Schema-bound with Zod
• Self-documenting via OpenAPI

This makes it ideal for:

• LLM agents (OpenAI, Claude)
• LangChain tools
• ai-agent-flow pipelines

🤖 Function Calling Example (OpenAI / Claude)

{
  "name": "getStory",
  "description": "Retrieve story details by ID from Hacker News",
  "parameters": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "The numeric ID of the Hacker News story"
      }
    },
    "required": [
      "id"
    ]
  }
}

➡️ Point to:
GET https://mcp-news-server.onrender.com/api/getStory/:id

📄 OpenAPI Schema

curl https://mcp-news-server.onrender.com/openapi.json

This endpoint can be used in:

• Swagger UI
• API clients (Postman, Insomnia)
• LLM frameworks for function discovery

🛠️ Local Setup

git clone https://github.com/rajeshdh/mcp-news-server
cd mcp-news-server
npm install
npm run dev

✨ What You Can Build with This

• A summarizer tool for top HN stories
• A GPT agent that fetches and ranks HN stories
• A fact-checking or news validation agent
• Your own open MCP marketplace entry!

📜 License

MIT