ChatGPT Book Connector

A clean and simple monorepo containing a TypeScript Model Context Protocol (MCP) server and a local React testing UI.

This connector exposes a search_product tool that allows ChatGPT to search for books. ChatGPT connects to the server using Server-Sent Events (SSE) via the /mcp endpoint. When a search runs, the backend queries Algolia (or uses high-quality local mock data as a fallback), returning rich details for books (image, name, edition, author, purchase/details link, and format options). The React UI allows developers to preview how the book cards and grids will render inside ChatGPT, inspect raw JSON tool outputs, and test search functionality.

Folder Structure

chatgpt-book-mcp/
├── package.json               # Root monorepo configuration (npm workspaces)
├── README.md                  # This documentation file
├── mcp-server/                # Express-based SSE MCP Backend (TypeScript)
│   ├── package.json
│   ├── tsconfig.json
│   ├── src/
│   │   ├── index.ts           # SSE server & API gateway
│   │   ├── algolia.ts         # Algolia Integration & mock search fallback
│   │   └── types.ts           # Shareable book interfaces
│   └── scripts/
│       └── test-tool.ts       # CLI tool for testing the search tool
└── react-ui/                  # React Front-end Dashboard (TypeScript/Vite)
    ├── package.json
    ├── tsconfig.json
    ├── vite.config.ts
    ├── index.html
    └── src/
        ├── main.tsx
        ├── App.tsx            # Interactive developer sandbox dashboard
        ├── index.css          # Sleek modern styling (Vanilla CSS)
        ├── components/        # Beautiful responsive React widgets
        │   ├── SearchBar.tsx
        │   ├── ProductCard.tsx
        │   ├── ProductGrid.tsx
        │   └── RawJsonView.tsx
        └── services/
            └── mcpClient.ts   # Client helper to fetch search results

Quick Start

1. Prerequisites

Ensure you have Node.js (v18 or higher) and npm installed.

2. Install Dependencies

Run the following command in the root of the monorepo:

npm install

3. Set Up Environment Variables

Inside the mcp-server directory, create a .env file (you can copy .env.example as a template):

cp mcp-server/.env.example mcp-server/.env

By default, if no credentials are provided in .env, the server will gracefully fallback to returning high-fidelity Mock Book Data so that you can run and test everything out-of-the-box. To connect your live books database, configure the Algolia credentials:

PORT=3000
ALGOLIA_APP_ID=your_algolia_app_id
ALGOLIA_API_KEY=your_algolia_search_only_api_key
ALGOLIA_INDEX_NAME=your_book_index_name

4. Run Development Servers

Start both the Backend SSE Server (port 3000) and Frontend React Testbed (port 5173) concurrently:

npm run dev

---

Testing the Setup

Method 1: Local React Sandbox Dashboard (Recommended)

Open your browser and navigate to:

http://localhost:5173

• Use the sleek search bar to query books like "Harry Potter", "Clean Code", "JavaScript", or "Design".
• Toggle the JSON Inspect panel to view the exact structure sent back by the backend tool.
• Interact with the responsive Book Grid and view the custom Book Cards with cover art, author names, editions, available formats (e.g. Hardcover, Paperback, E-book), and product links.

Method 2: Command Line Tester (MCP CLI Tool)

You can directly run a query against the MCP server tool from the command line:

npm run test-tool -- "Clean Code"

This runs mcp-server/scripts/test-tool.ts using tsx, sending the query to the tool handler and outputting the formatted JSON-RPC result in your terminal.

---

Integrating with ChatGPT

To register this connector as a custom application in ChatGPT:

1. Deploy the mcp-server to a publicly accessible HTTPS endpoint (or use a local tunnel like ngrok or localtunnel during development: ngrok http 3000).
2. In ChatGPT, go to Explore GPTs -> Create a GPT -> Configure -> Actions -> Add Action (or the corresponding Custom MCP Settings).
3. Provide the SSE endpoint URL. ChatGPT will initiate connection to:

   https://<your-deployed-domain>/mcp
   

4. Once connected, ChatGPT can invoke the search_product tool automatically when users ask questions like "Find books about Javascript" or "Show me editions of Harry Potter".
5. The JSON-RPC response returned by the server will then be formatted by ChatGPT. You can styling-guide ChatGPT using standard system instructions to list details or output the widget values.