On-Demand-Books
Find personalized puzzle books by first name from a 100,000+ title Shopify catalog.
Open source Repository Open in the app JSON README (API)
About
Find personalized puzzle books by first name from a 100,000+ title Shopify catalog.
Details
- Kind
- MCP servers
- Topic
- E-commerce & business
- Publisher
- gmlewis
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.2.0
- Last push
- 2026-07-08T17:29:02Z
- Repository state
- ativo
- Language
- Rust
- License
- Apache-2.0
- Added
- 2026-08-29 03:02:51
- Updated
- 2026-08-29 03:02:51
- Origin id
io.github.gmlewis/on-demand-books
README
# on-demand-books MCP Server
An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that
helps AI agents find the perfect personalized puzzle book gift from a catalog of
**100,853 customized books** available on the
[On-Demand-Books Shopify store](https://on-demand-books.com).
Add this server to any MCP-compatible AI agent (Claude Desktop, opencode, etc.)
and your agent will be able to search for books by the recipient's first name
and hand the buyer a direct Shopify purchase link.
## Demo
## Tools provided
| Tool | Purpose |
| --------------- | ----------------------------------------------------------------------- |
| `search_books` | Search the 100k+ personalized catalog by first name. Returns up to 9 matching books (mazes, name-sudokus, word searches across 3 difficulty levels) with direct Shopify purchase URLs, cover images, and ISBNs. Distinguishes exact matches from similar-name matches. |
| `suggest_names` | Suggest popular first names for which books are available, optionally filtered by a prefix. Use when a buyer is unsure of a spelling or wants gift-recipient ideas. |
| `get_book` | Re-resolve a single book's Shopify purchase URL from its product handle (as returned by `search_books`). |
## Live endpoint
```
https://on-demand-books-dq2yvpdh.fermyon.app/
```
Hosted on [Fermyon Cloud](https://fermyon.com) as a Spin + WebAssembly
component built with the [wasmcp](https://github.com/wasmcp/wasmcp) toolkit.
## Add to your MCP client
### Claude Desktop / Claude Code (`claude_desktop_config.json`)
```json
{
"mcpServers": {
"on-demand-books": {
"url": "https://on-demand-books-dq2yvpdh.fermyon.app/"
}
}
}
```
### opencode (`opencode.json`)
```json
{
"mcp": {
"on-demand-books": {
"type": "http",
"url": "https://on-demand-books-dq2yvpdh.fermyon.app/"
}
}
}
```
### Other MCP clients
Point any MCP client that supports the **Streamable HTTP** transport at the
live endpoint above. The server follows the MCP 2025-11-25 spec.
## Example agent usage
> **User:** I need a birthday gift for my niece Susan. She likes puzzles.
>
> **Agent** calls `search_books({ "name": "Susan" })` and replies:
>
> Great news — there are 9 personalized puzzle books for Susan, including
> "Fun Mazes for Susan — Easy to Medium" and "Fun Name Sudokus for Susan —
> Hard to Insane". Here's a direct link to the first one:
> https://on-demand-books.com/products/vz5ygw — add it to your cart and
> check out on Shopify.
## Build & run locally
```bash
make setup # Install wasm32-wasip2 target
make build # Output: target/wasm32-wasip2/release/on_demand_books.wasm
wasmcp compose server target/wasm32-wasip2/release/on_demand_books.wasm -o server.wasm --force
spin up --listen 127.0.0.1:8765 # http://127.0.0.1:8765/
```
Smoke test with `curl`:
```bash
curl -X POST http://127.0.0.1:8765 -H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
curl -X POST http://127.0.0.1:8765 -H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
curl -X POST http://127.0.0.1:8765 -H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_books","arguments":{"name":"susan"}}}'
```
## Deploy
```bash
spin deploy
```
## Implementation
This component uses the **capability pattern** from `wasmcp`, implementing just
two methods from the `tools-capability` interface:
- `list_tools()` — declares the three tools above.
- `call_tool()` — dispatches to the right tool handler and returns the result.
The `wasmcp compose` CLI wraps the component with the tools-middleware that
handles MCP protocol translation, request delegation, and response formatting.
Outbound HTTP to the search API uses the WASI HTTP `outgoing-handler` interface
(not raw sockets) so the component runs correctly on Fermyon Cloud.
See `src/lib.rs` for the full implementation.
## Architecture
```
MCP client (Claude / opencode / ...)
│ HTTPS (MCP Streamable HTTP transport)
▼
Fermyon Cloud → server.wasm (composed by wasmcp)
│
├─ transport.wasm (HTTP transport, MCP framing)
├─ tools_middleware.wasm (MCP protocol → tool dispatch)
└─ on_demand_books.wasm ← THIS COMPONENT
│
│ WASI HTTP outgoing-handler
▼
https://on-demand-books-com-kzfxdscz.fermyon.app/search/{name}
│
▼ returns book metadata
https://on-demand-books.com/products/{handle} (Shopify store)
```