Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@BookStore MCPfind 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.jsonSao 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 buildOr if error run
chmod +x fix-widgets.sh
./fix-widgets.shExpected 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 startExpected console output:
π Starting BookStore MCP Server...
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β π BOOKSTORE MCP SERVER β
β Status: β
Running β
β Port: 8000 β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββπ§ͺ Step 6: Test Local Server
Terminal 1 (Server):
npm startTerminal 2 (Test):
# Test health endpoint
curl http://localhost:8000/health
# Open in browser
open http://localhost:8000BαΊ‘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 main7.2 Deploy on Render
Truy cαΊp https://render.com
Click "New +" β "Web Service"
Connect GitHub repository
Settings:
Name:
bookstore-mcpEnvironment:
NodeBuild Command:
npm install && npm run buildStart Command:
npm startInstance Type: Free
Click "Create Web Service"
7.3 Get URL
Sau khi deploy xong (3-5 phΓΊt):
https://bookstore-mcp-xxxx.onrender.comTest: 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.comChatGPT 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/mcpTransport: 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 buildIssue 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.htmlFix:
npm run build:uiIssue 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 streamCommon 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
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! ππ