# 📚 BookStore MCP - Complete Setup Guide

## 🎯 Project Overview

Full-featured bookstore MCP server với 6 tools và 4 interactive widgets, sử dụng **Fractal MCP SDK** chính thống.

### Features:

- ✅ **6 MCP Tools**: search, detail, cart, checkout, history
- ✅ **4 React Widgets**: với useWidgetProps, useWidgetState, useLayout, useGlobalContext
- ✅ **Zod Validation**: Type-safe input schemas
- ✅ **Structured Content**: Proper widget props
- ✅ **Dark/Light Theme**: Responsive design
- ✅ **In-Memory Database**: 8 sample books

---

## 📦 Step 1: Create Project

```bash
# Create directory
mkdir bookstore-mcp
cd bookstore-mcp

# Initialize npm
npm init -y
```

---

## 📝 Step 2: Create File Structure

```bash
# Create directories
mkdir -p src/ui
mkdir -p src/server
mkdir -p dist/ui
mkdir -p dist/server

# Create files (copy from artifacts)
touch src/server/index.ts
touch src/server/database.ts
touch src/server/types.ts
touch src/ui/BookListWidget.tsx
touch src/ui/BookDetailWidget.tsx
touch src/ui/CartWidget.tsx
touch src/ui/OrderHistoryWidget.tsx
touch package.json
touch tsconfig.json
```

**Sao chép nội dung từ các artifacts vào files tương ứng:**

1. `package.json` - từ artifact "package.json"
2. `tsconfig.json` - từ artifact "tsconfig.json"
3. `src/server/types.ts` - từ artifact "src/server/types.ts"
4. `src/server/database.ts` - từ artifact "src/server/database.ts"
5. `src/server/index.ts` - từ artifact "src/server/index.ts - BookStore MCP Server"
6. `src/ui/BookListWidget.tsx` - từ artifact "src/ui/BookListWidget.tsx"
7. `src/ui/BookDetailWidget.tsx` - từ artifact "src/ui/BookDetailWidget.tsx"
8. `src/ui/CartWidget.tsx` - từ artifact "src/ui/CartWidget.tsx"
9. `src/ui/OrderHistoryWidget.tsx` - từ artifact "src/ui/OrderHistoryWidget.tsx"

---

## 📥 Step 3: Install Dependencies

```bash
# Install production dependencies
npm install @fractal-mcp/oai-hooks@latest @fractal-mcp/oai-server@latest zod

# Install dev dependencies
npm install --save-dev \
  @fractal-mcp/cli@latest \
  @types/node \
  @types/react \
  @types/react-dom \
  react \
  react-dom \
  typescript \
  vite
```

---

## 🏗️ Step 4: Build Project

```bash
# Build React widgets first (creates HTML files)
npm run build:ui

# Build TypeScript server
npm run build:server

# Or build all at once
npm run build
```

- Or if error run

```bash
chmod +x fix-widgets.sh
./fix-widgets.sh
```

**Expected output:**

```
dist/
├── ui/
│   ├── book-list/index.html
│   ├── book-detail/index.html
│   ├── cart/index.html
│   └── order-history/index.html
└── server/
    ├── index.js
    ├── database.js
    └── types.js
```

---

## 🚀 Step 5: Start Server Locally

```bash
npm start
```

**Expected console output:**

```
🚀 Starting BookStore MCP Server...

╔════════════════════════════════════════════════════════════╗
║  📚 BOOKSTORE MCP SERVER                                   ║
║  Status: ✅ Running                                        ║
║  Port: 8000                                                ║
╚════════════════════════════════════════════════════════════╝
```

---

## 🧪 Step 6: Test Local Server

**Terminal 1 (Server):**

```bash
npm start
```

**Terminal 2 (Test):**

```bash
# Test health endpoint
curl http://localhost:8000/health

# Open in browser
open http://localhost:8000
```

Bạn sẽ thấy UI với thông tin server!

---

## 🌐 Step 7: Deploy to Render

### 7.1 Push to GitHub

```bash
# Initialize git
git init
git add .
git commit -m "Initial commit: BookStore MCP"

# Create repo on GitHub, then:
git remote add origin https://github.com/YOUR_USERNAME/bookstore-mcp.git
git branch -M main
git push -u origin main
```

### 7.2 Deploy on Render

1. Truy cập https://render.com
2. Click **"New +"** → **"Web Service"**
3. Connect GitHub repository
4. Settings:

   - **Name:** `bookstore-mcp`
   - **Environment:** `Node`
   - **Build Command:** `npm install && npm run build`
   - **Start Command:** `npm start`
   - **Instance Type:** Free

5. Click **"Create Web Service"**

### 7.3 Get URL

Sau khi deploy xong (3-5 phút):

```
https://bookstore-mcp-xxxx.onrender.com
```

Test: Mở URL trong browser, bạn sẽ thấy server info page!

---

## 🔗 Step 8: Connect to ChatGPT

### Method 1: Direct URL (Recommended)

1. Mở **ChatGPT** → **Settings** (⚙️)
2. Click **"Apps SDK"** (hoặc "Integrations")
3. Click **"Add App"**
4. Nhập URL: `https://bookstore-mcp-xxxx.onrender.com`
5. ChatGPT sẽ auto-discover MCP endpoint
6. Click **"Connect"**

### Method 2: MCP Endpoint

Nếu method 1 không work:

1. URL: `https://bookstore-mcp-xxxx.onrender.com/mcp`
2. Transport: **SSE (Server-Sent Events)**
3. No authentication required

---

## 💬 Step 9: Test in ChatGPT

Sau khi connect thành công, thử các lệnh:

```
1. "Tìm sách về Programming"
2. "Tìm sách TypeScript giá dưới $50"
3. "Cho tôi xem chi tiết sách có ID là 1"
4. "Thêm sách ID 2 vào giỏ hàng"
5. "Thêm 3 cuốn sách ID 3 vào giỏ"
6. "Xem giỏ hàng của tôi"
7. "Thanh toán đơn hàng"
8. "Xem lịch sử đơn hàng"
```

ChatGPT sẽ:

- ✅ Show text response
- ✅ Render interactive widget UI
- ✅ Widget có dark/light theme
- ✅ Data update real-time

---

## 🐛 Troubleshooting

### Issue 1: Build fails

```bash
# Clean và rebuild
npm run clean
npm install
npm run build
```

### Issue 2: Widget không hiển thị

**Check:**

```bash
# Verify widget HTML files exist
ls -la dist/ui/*/index.html

# Should output:
# dist/ui/book-list/index.html
# dist/ui/book-detail/index.html
# dist/ui/cart/index.html
# dist/ui/order-history/index.html
```

**Fix:**

```bash
npm run build:ui
```

### Issue 3: ChatGPT connection failed

**Verify endpoints:**

```bash
curl https://your-app.onrender.com/health
# Should return JSON with status: ok

curl https://your-app.onrender.com/mcp
# Should return SSE stream
```

**Common fixes:**

- Đảm bảo Render service đang running (không sleep)
- Check Render logs for errors
- Verify PORT env variable (Render auto-sets this)

### Issue 4: Module not found errors

```bash
# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install
```

---

## 📊 Architecture

```
┌─────────────┐
│   ChatGPT   │  User asks: "Tìm sách TypeScript"
└──────┬──────┘
       │ calls MCP tool: search-books
       ↓
┌─────────────────────┐
│   MCP Server        │
│   (src/server)      │
│   • Register tools  │
│   • Process request │
│   • Return data     │
└──────┬──────────────┘
       │ returns structuredContent
       ↓
┌─────────────────────┐
│  React Widget UI    │
│  (dist/ui/*.html)   │
│  • useWidgetProps() │
│  • Render UI        │
│  • User interacts   │
└─────────────────────┘
```

---

## 🎨 Customization

### Add new book:

Edit `src/server/database.ts`:

```typescript
{
  id: '9',
  title: 'Your Book Title',
  author: 'Author Name',
  price: 39.99,
  category: 'Programming',
  // ... other fields
}
```

### Add new tool:

Edit `src/server/index.ts`:

```typescript
registerOpenAIWidget(
  server,
  {
    id: "your-tool",
    title: "Your Tool",
    // ... config
  },
  async (args) => {
    // Handler logic
  }
);
```

### Modify widget UI:

Edit `src/ui/*.tsx` files, then:

```bash
npm run build:ui
```

---

## 📚 Resources

- **Fractal MCP SDK:** https://github.com/fractal-mcp/sdk
- **OpenAI Apps SDK:** https://developers.openai.com/apps-sdk/
- **Model Context Protocol:** https://modelcontextprotocol.io
- **Render Docs:** https://render.com/docs

---

## ✅ Success Checklist

- [ ] Project created với đúng structure
- [ ] Dependencies installed
- [ ] Build successful (có dist/ui/\*/index.html)
- [ ] Server chạy local (port 8000)
- [ ] Deployed to Render
- [ ] ChatGPT connected
- [ ] All 6 tools hoạt động
- [ ] Widgets hiển thị đúng
- [ ] Theme switching works

---

## 🎉 Done!

Bạn đã có một **BookStore MCP Server** hoàn chỉnh với:

- ✅ 6 powerful tools
- ✅ 4 beautiful widgets
- ✅ Full Fractal MCP SDK features
- ✅ ChatGPT integration
- ✅ Production-ready code

**Next steps:**

- Add more books to database
- Implement user authentication
- Add payment processing
- Deploy to production domain
- Share with community!

Happy coding! 📚🚀