shopify-axi

Shopify Dev MCP for agents, built to the AXI conventions.

Wraps @shopify/dev-mcp with TOON output, a cached conversation, file-based validation, and exit codes you can gate on.

Why

The Dev MCP server is built for a chat client, not a shell. shopify-axi closes the gaps:

Dev MCP as shipped	shopify-axi
learn_shopify_api is a "mandatory first step" that mints a conversationId, costing a tool call and ~3.6k characters of preamble before any real work	Mints and caches the conversation locally, so docs and validate work on the first call
search_docs_chunks returns a raw JSON array with unbounded content blobs	TOON rows with score, title, domain, url, and content truncated to 600 chars with a --full escape hatch
Validation takes inline code blocks	Takes file paths or stdin, the form code actually exists in
Validation reports pass and fail as prose	status, passed, failed, one row per file, prose kept only for failures - and exit code 1 when anything fails
--api and --version repeated on every call	Pinned by learn and reused, overridable per command

Install

npm install -g shopify-axi

Or run it with no install at all: npx -y shopify-axi.

Install the skill so agents reach for it on their own:

npx skills add ./skills/shopify-axi -g

Optional ambient context in every agent session:

shopify-axi setup hooks

Usage

shopify-axi                                    # home: pinned API, version, next steps
shopify-axi apis                               # all 21 API surfaces, grouped
shopify-axi learn admin                        # load an API's instructions and pin it
shopify-axi docs "set a metafield on a product"
shopify-axi docs "cart lines add" --api storefront-graphql -n 3 --full
shopify-axi docs "metaobject definition" --fields    # add score and domain columns
shopify-axi validate graphql query.graphql --api admin
cat op.graphql | shopify-axi validate graphql -
shopify-axi validate theme . --file sections/hero.liquid
shopify-axi validate component src/Card.tsx --api polaris-app-home
shopify-axi validate theme . --file sections/hero.liquid --full   # untruncated errors
shopify-axi update --check

validate exits 1 on any failing block, so it drops straight into a pre-commit hook or CI step:

shopify-axi validate theme . --file sections/hero.liquid || exit 1

AXI compliance

$ npx -y axi-axi validate "npx -y shopify-axi" --dir .
summary: 11 pass, 0 fail, 0 warn, 1 skip, 4 advisory (spec axi/1.0-2026-07)

The one skip is V12, which runs an npm run skill:check freshness gate. skills/shopify-axi/SKILL.md is a hand-written discovery stub that points at --help rather than restating it, so there is nothing to keep fresh.

Exit codes follow the spec: 0 success, 1 error or failing validation, 2 usage error.

Environment

Variable	Effect
SHOPIFY_DEV_MCP_CMD	Override how the Dev MCP server is launched
SHOPIFY_AXI_MODEL	Model name reported to Shopify telemetry (default none)
XDG_CACHE_HOME	Where the pinned session is cached (default ~/.cache/shopify-axi)

Development

npm install
npm test
npm run build
npm run dev -- docs "how do I create a discount"

License

MIT