Skip to main content
Glama

πŸ“š 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:

  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

# 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

  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

  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

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

npm run build:ui

πŸ“š Resources


βœ… 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! πŸ“šπŸš€

-
security - not tested
F
license - not found
-
quality - not tested

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/truongducthuan/bookstore-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server