📚 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

# Create directory mkdir bookstore-mcp cd bookstore-mcp # Initialize npm npm init -y

📝 Step 2: Create File Structure

# 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:

package.json - từ artifact "package.json"
tsconfig.json - từ artifact "tsconfig.json"
src/server/types.ts - từ artifact "src/server/types.ts"
src/server/database.ts - từ artifact "src/server/database.ts"
src/server/index.ts - từ artifact "src/server/index.ts - BookStore MCP Server"
src/ui/BookListWidget.tsx - từ artifact "src/ui/BookListWidget.tsx"
src/ui/BookDetailWidget.tsx - từ artifact "src/ui/BookDetailWidget.tsx"
src/ui/CartWidget.tsx - từ artifact "src/ui/CartWidget.tsx"
src/ui/OrderHistoryWidget.tsx - từ artifact "src/ui/OrderHistoryWidget.tsx"

📥 Step 3: Install Dependencies

# 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

# 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

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

npm start

Expected console output:

🚀 Starting BookStore MCP Server... ╔════════════════════════════════════════════════════════════╗ ║ 📚 BOOKSTORE MCP SERVER ║ ║ Status: ✅ Running ║ ║ Port: 8000 ║ ╚════════════════════════════════════════════════════════════╝

🧪 Step 6: Test Local Server

Terminal 1 (Server):

npm start

Terminal 2 (Test):

# 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

# 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

Truy cập https://render.com
Click "New +" → "Web Service"
Connect GitHub repository
Settings:
- Name: bookstore-mcp
- Environment: Node
- Build Command: npm install && npm run build
- Start Command: npm start
- Instance Type: Free
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)

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

Method 2: MCP Endpoint

Nếu method 1 không work:

URL: https://bookstore-mcp-xxxx.onrender.com/mcp
Transport: SSE (Server-Sent Events)
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

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

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

Check:

# 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:

npm run build:ui

Issue 3: ChatGPT connection failed

Verify endpoints:

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

# 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:

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

Add new tool:

Edit src/server/index.ts:

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

Modify widget UI:

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