# Shop Buddy

> A hosted control plane that lets any AI coding agent change a Shopify storefront safely. Every edit lands on an unpublished staging theme; the platform validates with Shopify Theme Check, captures before/after screenshots with a plain-language summary of what changed, and the store owner approves with one tap (or opts in to trusted publishing for low-risk changes). Rollback is one tap. Built for brand owners and their teams, and the agencies that serve them.

## Connect (agents: do this first)

- MCP server, streamable HTTP with OAuth 2.1 (dynamic client registration supported) or an API key: https://getshopbuddy.vercel.app/api/mcp
- No account is needed up front: the OAuth tab creates one. Humans: https://getshopbuddy.vercel.app/install
- Claude Code: `claude mcp add --transport http shopbuddy https://getshopbuddy.vercel.app/api/mcp`
- Codex: `codex mcp add shopbuddy --url https://getshopbuddy.vercel.app/api/mcp`
- Cursor / VS Code: one-click buttons on /install
- OAuth discovery: /.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server

## Tools

- Stores: shopbuddy_list_stores, shopbuddy_connect_demo_store
- Change requests: shopbuddy_start_change, shopbuddy_status, shopbuddy_set_preview_pages, shopbuddy_close_change
- Files (server-side working copy of the staging theme): shopbuddy_list_files, shopbuddy_read_file, shopbuddy_search_files, shopbuddy_write_file, shopbuddy_delete_file
- Quality: shopbuddy_validate (Theme Check), shopbuddy_push_preview (uploads to the staging theme, screenshots before/after), shopbuddy_review (visual diff summary)
- Publishing: shopbuddy_submit, shopbuddy_request_publish (returns a one-tap approval link for the owner), shopbuddy_publish and shopbuddy_rollback (only when the store owner has enabled trusted publishing; otherwise denied with a reason)

## Rules the server enforces

- The live theme is never edited directly; every change is a duplicate → edit → validate → preview → approve → publish.
- Publishing requires a human tap unless trusted publishing is on for that store, and even then only within its risk, directory and file-count limits.
- Every action is logged and tied to a user and a store. Rollback republishes the previous theme.
- Store credentials are entered by humans in the browser, never through the agent.

## Typical flow

1. shopbuddy_list_stores (if empty, tell the human to connect a store at /app/stores/connect)
2. shopbuddy_start_change with the store and the request in the human's words
3. read/search/write files, shopbuddy_validate, fix issues
4. shopbuddy_push_preview, then shopbuddy_review for the visual summary
5. shopbuddy_submit, then shopbuddy_request_publish and show the human the link
6. Only if the human asked to publish and trusted publishing is on: shopbuddy_publish

## For store owners (no coding tools)

- Use it from Claude or ChatGPT: add the connector (steps at https://getshopbuddy.vercel.app/install), then ask in plain English, e.g. "Change my announcement bar to say free shipping over $75". You get a preview link, before/after screenshots, and a one-tap publish link. Your live theme is never edited directly.
- Fixing a storefront error: paste the error line (e.g. "Liquid error (sections/header line 515): Could not find asset snippets/icon-caret.liquid") to the assistant; the file and line are in the message and the fix is made on a private copy.
- Free Liquid error decoder (no signup, runs in the browser): https://getshopbuddy.vercel.app/fix/liquid-error, with one page per error such as /fix/could-not-find-asset and /fix/translation-missing
- How-tos with the manual steps and the one-tap way: https://getshopbuddy.vercel.app/how/change-announcement-bar-text, https://getshopbuddy.vercel.app/how/remove-app-code-after-uninstall
- How it stays safe, and the FAQ: https://getshopbuddy.vercel.app/

## For humans

- Install: https://getshopbuddy.vercel.app/install
- Source and docs: https://github.com/tmill313/shopbuddy