# ChatGPT Book MCP 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:
```bash
npm install
```

### 3. Set Up Environment Variables
Inside the `mcp-server` directory, create a `.env` file (you can copy `.env.example` as a template):
```bash
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:
```env
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:
```bash
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:
```bash
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.