How do I use BookStore MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@BookStore MCP find books about programming under $40" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

📚 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

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
  }
);

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

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! 📚🚀

BookStore MCP