📰 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