feat(template): native Storefront MCP catalog search agent tool#408
Merged
Conversation
Prototype an agent search tool backed by Shopify's hosted Storefront MCP server (search_catalog) as an alternative to the GraphQL-backed search_products, so the two can be compared on relevance. - lib/shopify/storefront-mcp.ts: universal JSON-RPC 2.0 client for the store's /api/mcp server (no server-only/next/cache, so the eve runtime can import it). Exports callStorefrontMcp and searchCatalog; handles the structuredContent and text-block response forms and sends the optional meta.ucp-agent.profile only when configured. - agent/tools/search_catalog.ts: eve tool mirroring search_products' output shape, plus a natural-language `intent` hint for native semantic relevance. Results carry a Shopify product GID (no storefront handle). - Registers optional UCP_AGENT_PROFILE_URL in turbo.json globalEnv and documents it in .env.example. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
…tools
Builds on the native Storefront MCP search tool:
- GID→handle bridge (b): fetchProductHandlesByIds in lib/shopify/fetch.ts
resolves Shopify product GIDs to storefront handles via the Storefront
`nodes` query. search_catalog now enriches each result with a handle, so
MCP results feed navigate_user / get_product_details / add_to_cart directly
instead of living in a GID-only silo.
- Native sibling tools (c):
- agent/tools/get_catalog_product.ts — get_product_details by GID via MCP,
returning price/availability/options/variantId plus the resolved handle.
- agent/tools/search_shop_policies_and_faqs.ts — native policy/FAQ Q&A
(net-new capability; no site equivalent).
- storefront-mcp.ts: adds getCatalogProduct + searchShopPoliciesAndFaqs and
their types. Note get_product_details encodes money as major-unit strings
with a sibling currency, unlike search_catalog's minor-unit objects.
Verified live against the dev store: search results carry handles, native
product details map correctly (price, variantId, options), and policy Q&A
returns answers.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Move the MCP client and catalog/product/policy functions out of the non-standard storefront-mcp.ts into storefront.ts (reusing its store-domain const and i18n imports), repoint tool imports, and trim comments to the load-bearing ones. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add the native MCP group (search_catalog, get_catalog_product, search_shop_policies_and_faqs) to the agent anatomy doc — bumping the tool count to 14 and noting the MCP helpers now live in storefront.ts — and add a template-rollout-log entry for the change. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add capability entries and a short "choosing a search tool" rule to instructions.md: prefer search_catalog for descriptive/intent queries and search_products for exact keyword/price-sorted lookups, fall back to search_products on error, and route policy questions to search_shop_policies_and_faqs. Include the MCP tools in the product-card render rule. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Prototypes an agent search tool backed by Shopify's hosted Storefront MCP server (
search_catalog) as an alternative to the GraphQL-backedsearch_products, so the two can be compared on relevance. Both tools ship side-by-side.What's here
lib/shopify/storefront-mcp.ts— a universal JSON-RPC 2.0 client for the store's/api/mcpserver (noserver-only/next/cache, so the eve agent runtime can import it, same asstorefront.ts). ExportscallStorefrontMcp(reusable primitive) andsearchCatalog. Handles both thestructuredContentand text-block response forms, surfacesisError, and sendsmeta.ucp-agent.profileonly when configured.agent/tools/search_catalog.ts— an eve tool (auto-discovered by filename) mirroringsearch_products' output shape (available,image,price,title) for apples-to-apples comparison, plusproductId/hasMoreand a natural-languageintenthint for native semantic relevance.turbo.json+.env.example— registers the optionalUCP_AGENT_PROFILE_URL(Turbo globalEnv + env docs).Verified (live, against the
jtwics-2dev store)search_catalogis enabled on/api/mcpand works without a profile."coat rack"→ the Arco coat rack,available: true, image,price: "528.00 USD", GID.intentquery returns results.tscclean, oxlint clean, nonext/cache/server-only/next/headersin the eve import chain.Caveats (by design, for a prototype)
navigate_user/get_product_details(handle-based) can't chain directly off these results yet. A GID→handle resolve step would make it drop-in.Not included (follow-ups if we adopt)
search_shop_policies_and_faqs(policy Q&A),get_product_details.apps/docs+ atemplate-rollout-logentry once it graduates from prototype.🤖 Generated with Claude Code