Offer Discovery MCP Server

A Model Context Protocol (MCP) server that connects AI agents to a live offers API and returns structured product offers in real time.

---

Table of Contents

• What is MCP?
• Architecture Overview
• Project Structure
• Data Flow
• Transport Modes
• Getting Started
• Available Scripts
• Environment Variables

---

What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI models (like ChatGPT) call external tools and fetch live data — designed specifically for LLM tool use.

ChatGPT ──────── MCP Protocol ────────► MCP Server ────► Offers API
         "call get_offers tool"         (this repo)       (live, 520+ offers)
         ◄──────────────────────────────              ◄──────────
              Returns structured JSON

When a user asks ChatGPT "What home improvement deals are available?", ChatGPT automatically:

1. Recognizes it needs real data
2. Calls our get_offers tool via MCP
3. Receives a structured JSON list of live offers
4. Summarizes and presents them to the user

---

Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                        CLIENT LAYER                                  │
│                                                                      │
│   ChatGPT / AI Agent / MCP Inspector                                │
│   (Sends JSON-RPC tool call requests)                               │
└───────────────────────────┬─────────────────────────────────────────┘
                            │ MCP Protocol (JSON-RPC 2.0)
                            │
              ┌─────────────▼──────────────┐
              │      TRANSPORT LAYER        │
              │                            │
              │  stdio (local/dev)         │  ← src/index.ts
              │  HTTP + SSE (remote/ngrok) │  ← src/server.ts
              └─────────────┬──────────────┘
                            │
              ┌─────────────▼──────────────────────────┐
              │   McpServer  (SDK v1.x high-level API)  │
              │                                         │
              │  registerTool("get_offers", {            │
              │    inputSchema: GetOffersInputZodShape,  │  ← offerSchema.ts
              │    description: "...",                   │
              │  }, handler)                            │
              │                                         │
              │  • Serves  tools/list  automatically   │
              │  • Validates args via Zod automatically │
              │  • Routes  tools/call  to handler       │
              └─────────────┬───────────────────────────┘
                            │ pre-validated GetOffersInput
              ┌─────────────▼──────────────┐
              │       API CLIENT LAYER      │
              │                            │
              │  fetchOffers()             │  ← src/api/offersClient.ts
              │  Live API + mock fallback  │
              └─────────────┬──────────────┘
                            │ axios.get()
              ┌─────────────▼──────────────┐
              │      OFFERS API            │
              │  api.example.com/offers    │
              │  /offers?campaignMappingId │
              │  =ALL   (live offers)      │
              └────────────────────────────┘

---

Project Structure

offer-discovery-mcp/
│
├── src/
│   ├── index.ts                  # Entry point: stdio transport (local dev & MCP Inspector)
│   ├── server.ts                 # Entry point: HTTP/SSE transport (ngrok & remote clients)
│   │
│   ├── schemas/
│   │   └── offerSchema.ts        # Zod schemas: input args + offer output shape
│   │
│   ├── api/
│   │   └── offersClient.ts       # Live API client: calls the offers API, falls back to mock
│   │
│   └── tools/
│       └── getOffers.ts          # Tool handler: validate → fetch → filter → format → respond
│
├── package.json                  # Dependencies + npm scripts
├── tsconfig.json                 # TypeScript: ES2022, NodeNext, strict mode
├── .gitignore
├── README.md                     # ← You are here
└── TESTING.md                    # Step-by-step testing guide

---

Data Flow

Exact journey of a single tool call from ChatGPT to a response:

1. ChatGPT sends:
   { "method": "tools/call", "params": { "name": "get_offers", "arguments": { "category": "furniture", "featured": true } } }

2. src/index.ts (or server.ts) — McpServer receives the tool call
   └── SDK validates args against GetOffersInputZodShape (Zod)
       ├── FAIL → SDK returns validation error to ChatGPT (handler not called)
       └── PASS → calls the registered handler with typed GetOffersInput args

3. src/tools/getOffers.ts :: handleGetOffers(args: GetOffersInput)
   └── calls fetchOffers(args)

4. src/api/offersClient.ts :: fetchOffers()
   ├── axios.get("https://api.example.com/offers?campaignMappingId=ALL")
   │   ├── SUCCESS → live offers returned
   │   └── FAIL    → falls back to MOCK_OFFERS (server stays functional)
   └── Applies in-process filters:
       industry → category (legacy) → offerType → region → network → brand → featured → pagination
       └── Returns: Offer[]

5. src/tools/getOffers.ts :: formatOfferForChatGPT()
   └── Strips raw image URLs + internal IDs
       └── Surfaces: brand, offerType, links, keywords, expiryMsg, disclosure
       └── Wraps in envelope: { totalOffers, appliedFilters, offers: [...] }

6. ChatGPT receives the JSON and presents live offers to the user.

---

Transport Modes

Mode	File	Command	Use When
stdio	src/index.ts	npm run dev	Local MCP Inspector, Claude Desktop
HTTP/SSE	src/server.ts	npm run dev:http	Remote access via ngrok, ChatGPT Agents SDK

Endpoints (HTTP mode)

Endpoint	Method	Purpose
POST /mcp	Streamable HTTP	OpenAI Responses API (recommended)
GET /mcp	Streamable HTTP	SSE streaming for long responses
GET /sse	SSE (legacy)	MCP Inspector
POST /messages	SSE (legacy)	MCP Inspector message routing
GET /health	—	Health check

---

OpenAI Integration

Source: OpenAI Apps SDK — Build your MCP server · MCP concept overview

Recommended Transport: Streamable HTTP

Per official OpenAI docs, Streamable HTTP is the recommended transport for production.

Transport	Status	Use When
stdio	✅ Active	Local MCP Inspector, Claude Desktop
SSE	⚠️ Legacy	Remote testing with MCP Inspector
Streamable HTTP	✅ Recommended	Production (ChatGPT, OpenAI Responses API)

Both transports are implemented in this project. POST /mcp uses Streamable HTTP; GET /sse uses legacy SSE.

Tool Annotations (Required for ChatGPT App Store)

server.registerTool("get_offers", {
  description: "...",
  inputSchema: GetOffersInputZodShape,
  annotations: {
    readOnlyHint: true,      // ✅ reads data only, never writes
    openWorldHint: false,    // ✅ scoped to the offers domain only
    destructiveHint: false,  // ✅ no deletes or irreversible actions
  },
}, handler);

Official References

Resource	Link
OpenAI Apps SDK: Build MCP server	developers.openai.com/apps-sdk/build/mcp-server
MCP concept overview	developers.openai.com/apps-sdk/concepts/mcp-server
TypeScript SDK	github.com/modelcontextprotocol/typescript-sdk
MCP Specification	spec.modelcontextprotocol.io
MCP Inspector	modelcontextprotocol.io/docs/tools/inspector

---

Getting Started

Prerequisites

• Node.js v18+
• npm v9+
• ngrok (only for remote/HTTP mode)

Installation

git clone https://github.com/siddharthkoundal/chatgpt-marketplace-app.git
cd offer-discovery-mcp
npm install

Running Locally (stdio — for MCP Inspector)

npm run dev

Running for Remote Access (HTTP — for ChatGPT / ngrok)

# Terminal 1: Start HTTP server
npm run dev:http
# → 🚀 offer-discovery-mcp v1.0.0 running on port 3000
# → [offer-discovery-mcp] Offers API working! returned live offers.

# Terminal 2: Expose via ngrok
ngrok http 3000
# → Forwarding: https://abc123.ngrok-free.app → localhost:3000

See TESTING.md for detailed testing steps.

---

Available Scripts

Command	Description
npm run dev	Start server with stdio transport (local MCP Inspector)
npm run dev:http	Start server with HTTP/SSE transport (ngrok / remote)
npm run build	Compile TypeScript to dist/
npm start	Run compiled JS from dist/

---

Environment Variables

Create a .env file in the project root (already listed in .gitignore — never commit it):

# Offers API
OFFERS_API_URL=https://api.example.com/offers
OFFERS_API_KEY=your-api-key-here

# Server
PORT=3000

tsx (used by npm run dev and npm run dev:http) loads .env automatically — no extra packages needed.

If OFFERS_API_KEY is missing or empty, the server falls back to the MOCK_OFFERS dataset automatically.