BookStore

You can run a BookStore MCP Server that exposes six tools and four interactive widgets to let users search for books, view details, manage a cart, and complete checkouts. It runs with the Fractal MCP SDK, provides real-time widget interactions, and can be connected to ChatGPT for a streamlined conversational experience with live UI components.

How to use

You will interact with the BookStore MCP Server through an MCP client or ChatGPT integration. The server exposes tools that handle book search, detail viewing, cart management, checkout, and order history. When connected, you can search for books, view a book’s details, add items to your cart, proceed to checkout, and review past orders. The user interface is provided by four React widgets that render within an interactive panel and support dark/light themes for accessibility.

How to install

Prerequisites you need before installing:
- Node.js and npm installed on your system
- A bash-compatible shell
- Access to a terminal or command prompt
- Optional: Git for deployment workflows

Follow these steps to set up the BookStore MCP Server locally:
1. Create a project directory and initialize npm
2. Create the required file structure for server and UI code
3. Install production and development dependencies
4. Build the UI and server components
5. Start the server locally and verify it runs on port 8000

# Step 1: Create project directory
mkdir bookstore-mcp
cd bookstore-mcp

# Step 2: Initialize npm
npm init -y

# Step 3: Create file structure
mkdir -p src/ui
mkdir -p src/server
mkdir -p dist/ui
mkdir -p dist/server

# Step 4: Install dependencies (production and dev)
npm install @fractal-mcp/oai-hooks@latest @fractal-mcp/oai-server@latest zod
npm install --save-dev \
  @fractal-mcp/cli@latest \
  @types/node \
  @types/react \
  @types/react-dom \
  react \
  react-dom \
  typescript \
  vite

# Step 5: Build project
npm run build:ui
npm run build:server
npm run build

# Step 6: Start locally
npm start

Deployment and future usage notes

After you have a local setup, you can deploy the MCP server to a hosting service. This guide describes how to push to GitHub and deploy with a hosting provider that supports Node-based MCP servers. Once deployed, you can connect via the provided MCP endpoint to enable scripting via ChatGPT or another MCP client.

# Example deployment workflow
# Initialize a git repository
git init
git add .
git commit -m "Initial commit: BookStore MCP"

# Create a repository on your hosting platform and push
git remote add origin https://github.com/YOUR_USERNAME/bookstore-mcp.git
git branch -M main
git push -u origin main

# Run the deployment steps on the hosting service according to its UI

Troubleshooting and notes

If you encounter issues during build or run, perform a clean rebuild and verify the generated dist files exist for the UI and server. Common problems include missing widget HTML files or build failures that prevent the server from starting.

# Troubleshooting helper commands
npm run clean
npm install
npm run build

# If widget HTMLs are missing after build
ls -la dist/ui/*/index.html

Available tools

search

Search for books by title, author, or keywords and return matching results.

detail

Fetch detailed information for a specific book by its ID, including title, author, price, and description.

cart

Add, view, and manage items in the shopping cart before checkout.

checkout

Process the current cart contents to place an order and generate a receipt.

history

Retrieve a historical list of past orders for the current user.