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

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

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