{
  "markdown": "# on-demand-books MCP Server\n\nAn [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that\nhelps AI agents find the perfect personalized puzzle book gift from a catalog of\n**100,853 customized books** available on the\n[On-Demand-Books Shopify store](https://on-demand-books.com).\n\nAdd this server to any MCP-compatible AI agent (Claude Desktop, opencode, etc.)\nand your agent will be able to search for books by the recipient's first name\nand hand the buyer a direct Shopify purchase link.\n\n## Demo\n\n![on-demand-books MCP demo](on-demand-books-mcp-demo.gif)\n\n## Tools provided\n\n| Tool            | Purpose                                                                 |\n| --------------- | ----------------------------------------------------------------------- |\n| `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. |\n| `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. |\n| `get_book`      | Re-resolve a single book's Shopify purchase URL from its product handle (as returned by `search_books`). |\n\n## Live endpoint\n\n```\nhttps://on-demand-books-dq2yvpdh.fermyon.app/\n```\n\nHosted on [Fermyon Cloud](https://fermyon.com) as a Spin + WebAssembly\ncomponent built with the [wasmcp](https://github.com/wasmcp/wasmcp) toolkit.\n\n## Add to your MCP client\n\n### Claude Desktop / Claude Code (`claude_desktop_config.json`)\n\n```json\n{\n  \"mcpServers\": {\n    \"on-demand-books\": {\n      \"url\": \"https://on-demand-books-dq2yvpdh.fermyon.app/\"\n    }\n  }\n}\n```\n\n### opencode (`opencode.json`)\n\n```json\n{\n  \"mcp\": {\n    \"on-demand-books\": {\n      \"type\": \"http\",\n      \"url\": \"https://on-demand-books-dq2yvpdh.fermyon.app/\"\n    }\n  }\n}\n```\n\n### Other MCP clients\n\nPoint any MCP client that supports the **Streamable HTTP** transport at the\nlive endpoint above. The server follows the MCP 2025-11-25 spec.\n\n## Example agent usage\n\n> **User:** I need a birthday gift for my niece Susan. She likes puzzles.\n>\n> **Agent** calls `search_books({ \"name\": \"Susan\" })` and replies:\n>\n> Great news — there are 9 personalized puzzle books for Susan, including\n> \"Fun Mazes for Susan — Easy to Medium\" and \"Fun Name Sudokus for Susan —\n> Hard to Insane\". Here's a direct link to the first one:\n> https://on-demand-books.com/products/vz5ygw — add it to your cart and\n> check out on Shopify.\n\n## Build & run locally\n\n```bash\nmake setup  # Install wasm32-wasip2 target\nmake build  # Output: target/wasm32-wasip2/release/on_demand_books.wasm\nwasmcp compose server target/wasm32-wasip2/release/on_demand_books.wasm -o server.wasm --force\nspin up --listen 127.0.0.1:8765   # http://127.0.0.1:8765/\n```\n\nSmoke test with `curl`:\n\n```bash\ncurl -X POST http://127.0.0.1:8765 -H 'content-type: application/json' \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-11-25\",\"capabilities\":{},\"clientInfo\":{\"name\":\"curl\",\"version\":\"1\"}}}'\n\ncurl -X POST http://127.0.0.1:8765 -H 'content-type: application/json' \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\"}'\n\ncurl -X POST http://127.0.0.1:8765 -H 'content-type: application/json' \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"search_books\",\"arguments\":{\"name\":\"susan\"}}}'\n```\n\n## Deploy\n\n```bash\nspin deploy\n```\n\n## Implementation\n\nThis component uses the **capability pattern** from `wasmcp`, implementing just\ntwo methods from the `tools-capability` interface:\n\n- `list_tools()` — declares the three tools above.\n- `call_tool()` — dispatches to the right tool handler and returns the result.\n\nThe `wasmcp compose` CLI wraps the component with the tools-middleware that\nhandles MCP protocol translation, request delegation, and response formatting.\n\nOutbound HTTP to the search API uses the WASI HTTP `outgoing-handler` interface\n(not raw sockets) so the component runs correctly on Fermyon Cloud.\n\nSee `src/lib.rs` for the full implementation.\n\n## Architecture\n\n```\nMCP client (Claude / opencode / ...)\n        │  HTTPS (MCP Streamable HTTP transport)\n        ▼\nFermyon Cloud  →  server.wasm  (composed by wasmcp)\n        │\n        ├─ transport.wasm        (HTTP transport, MCP framing)\n        ├─ tools_middleware.wasm (MCP protocol → tool dispatch)\n        └─ on_demand_books.wasm  ← THIS COMPONENT\n                │\n                │  WASI HTTP outgoing-handler\n                ▼\n        https://on-demand-books-com-kzfxdscz.fermyon.app/search/{name}\n                │\n                ▼  returns book metadata\n        https://on-demand-books.com/products/{handle}  (Shopify store)\n```\n",
  "bytes": 4850,
  "sha": "76b6a580d320649ed074ce195145668b86da5da6816f29d16580c12725c25da7",
  "repo_slug": "gmlewis/on-demand-books-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_gmlewis_on_demand_books_93b8dfdd/readme"
}