@cloudcart/storefront-mcp

An MCP server for the CloudCart Storefront GraphQL API — the headless API Nitrogen storefronts, the mobile app and other clients are built on.

It is a developer's assistant, not a shop's. It runs on your machine, reads the schema, and never talks to a store: no access token, no network, nothing that could touch live data.

Its companion is @cloudcart/dev-mcp, which covers the Admin API. The two APIs differ in more than scope — the Admin API uses plain numeric ids, the Storefront API uses gid://cloudcart/… — so keep them apart.

Tools

There is deliberately no semantic search. The surface is small enough to look up by name — data/storefront.json holds every type, query and mutation — and learn_cloudcart_storefront names the operation for each step; an embedding index would add size and a cold start to solve a problem this API does not have.

Related MCP server: GraphQL Schema Explorer

What the validator notes beyond schema errors

Things that pass validation and still go wrong:

• a numeric cart id — carts are addressed by their key, and a row number resolves to nothing

• reading delivery before there is an address — couriers price against a destination, so the list is empty

• reading paymentMethods before delivery is chosen — the courier decides part of what is allowed

• selecting amount without formatted — fine for logic, but a buyer is shown the amount as the store writes money

• a paged product list or search without its facets (filters, productFilters) or without totalCount — the API already computed them

• a metafield asked for without its namespace — the store has no app-reserved namespace, so a key alone finds nothing

It also answers names borrowed from other storefront APIs — productByHandle, checkoutCreate, cartDeliveryAddressesAdd, cartGiftCardCodesUpdate, customerAccessTokenCreate — each coming back with the CloudCart equivalent and the reason it differs. Most of the vocabulary is deliberately familiar; these are the places it is not.

Install

npm install
npm run build

data/storefront.json is part of the package: building needs no schema.

Regenerate the schema

generate-schema reads the SDL from the folder in SF_SCHEMA_DIR. Give it the sf/schema files of the commit production runs, never a working copy: a developer's queries go to production, and a type that exists only on a branch would validate here and fail there. Export them from cc-builder:

mkdir -p /tmp/sf-deployed
git -C /path/to/cc-builder archive <deployed commit> sf/schema | tar -x -C /tmp/sf-deployed
SF_SCHEMA_DIR=/tmp/sf-deployed/sf/schema npm run generate-schema

The schema is assembled from those files rather than fetched from a running store. They are what the server itself builds from — no store, no token, no network.

Use it

The CloudCart AI Toolkit plugin registers it. To add it to an MCP host yourself:

{
  "mcpServers": {
    "cloudcart-storefront-mcp": {
      "command": "npx",
      "args": ["-y", "@cloudcart/storefront-mcp@latest"]
    }
  }
}

From a local build, the command is node with /absolute/path/to/storefront-mcp/dist/index.js.

After a schema change is deployed

Export the deployed commit's sf/schema as above, then:

SF_SCHEMA_DIR=/tmp/sf-deployed/sf/schema npm run generate-schema && npm run build

The shipped schema comes from that step, so run it after every deploy that changes sf/schema.

Release

1. Regenerate the schema from the deployed commit (above), npm run build, and check the three tools.

2. Bump version in package.json (the server reads it from there), commit, push main; CI builds and checks the tools on Node 20, 22 and 24.

3. Publish by hand, from a clean clone of that commit: npm ci, npm run build, npm publish --access public with an npm login that may write @cloudcart/storefront-mcp (the account confirms with its security key). Then gh release create vX.Y.Z for the notes; it publishes nothing.

Layout

scripts/generate-schema.ts   SDL in the repo → data/storefront.json
src/prompts/storefront.ts    what an assistant must know before writing anything
src/app-resources.ts         which fields depend on a merchant's installed apps
src/tools/                   the three tools
src/schema/loader.ts         reads and caches the introspection JSON
.github/workflows/           CI on every push