# shopify-axi

Shopify Dev MCP for agents, built to the [AXI](https://axi.md) conventions.

Wraps [`@shopify/dev-mcp`](https://shopify.dev/docs/apps/build/ai-toolkit) 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

```sh
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:

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

Optional ambient context in every agent session:

```sh
shopify-axi setup hooks
```

## Usage

```sh
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:

```sh
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

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

## License

MIT