Skip to content
littleworksdocs

Explore the documentation

Meet LittleworksA little backend for what you’re building on Shopify.Littleworks or your own appWhat it takes to give a Shopify feature a backend: with Littleworks, or with a custom app you build and run yourself.Connect to LittleworksChoose the CLI, a plugin, or a remote MCP connection.CLIConnect from your terminal with Shopify approval and no manual tokens.Claude pluginThe Littleworks MCP connection and agent guidance in one package.OpenAI pluginThe Littleworks MCP connection and agent guidance in one package.MCP with OAuthConnect a compatible client directly, without a marketplace plugin.Build with an agentThe operating guide for agents building on Shopify with Littleworks.Write a workA JavaScript handler, a small manifest, and a version you test and then publish.Keep secretsEncrypted credentials, shared across your store’s works.Call external servicesMake public HTTPS API requests from a work using http.fetch().Store dataDocument collections with a small API, scoped automatically to the work that uses them.Call ShopifyCall Shopify’s Admin and Storefront GraphQL APIs with credentials held by Littleworks.Store filesKeep uploads such as artwork and photos in the merchant’s Shopify Files, uploaded by the browser straight to Shopify.Expose an endpointConnect an existing frontend to a work through a small JSON API.Customer access and invitationsRequire a signed-in shopper or a narrow, expiring invitation before a work runs.RecipesUseful things to build for your store, with the backend already taken care of.Product reviewsCollect customer reviews, verify purchases, and publish approved content directly into your Shopify theme.Customer wishlistsGive signed-in customers a persistent list of products they can revisit across devices.Customer quote requestsCollect a customer’s products, quantities, and requirements without turning a request into an order.Back-in-stock alertsCollect confirmed signups on sold-out variants, email them through your own provider when stock returns, and see every signup and send in your admin.Transactional emailSend email from your works through your own provider, never twice for the same thing, and see what was sent and what failed.Build a merchant pageDescribe your records and what merchants do with them; Littleworks renders a native Shopify admin page.Run works on their ownRun a work when something happens in the store, on a schedule, or from a Shopify Flow workflow.Run background jobsQueue runs for later or in the background: fan out to thousands of customers, import in pages, follow up days later, and retry what fails.MCP tool referenceTools to inspect, deploy, run, and organize the backend for a connected store.Usage and allowancesSee what your works use, how much capacity remains, and when allowances reset.Inspect and troubleshootFind the relevant run, understand the failure, and make the next change deliberately.Limits and securityThe current runtime boundaries, data isolation model, and execution allowances.
Shopify admin
Browse documentation
Start here
Markdown

Build with an agent

The operating guide for agents building on Shopify with Littleworks.

Assess the fit before connecting

Littleworks provides sandboxed JavaScript, scoped document storage, and a Shopify GraphQL client. A merchant may connect before they know what they want to build. Treat connection and documentation reading as setup, not a request to build anything. Before building or changing anything, confirm the runtime limits fit the requested backend requirements.

Works can call public HTTPS APIs, including an email provider chosen by the merchant, using store secrets. Read Secrets and External requests before adding an integration. Uploads such as artwork or photos go to the merchant’s Shopify Files; see Store files. Littleworks has no theme tools. For the “when this happens” or “every morning” half of a build, use automations: event, schedule and Shopify Flow triggers.

Shopify’s own tools make theme changes: the Shopify connector in Claude, the Shopify plugin in ChatGPT, or, in a coding agent, the Shopify CLI with Shopify’s agent skill from the Shopify AI Toolkit. When what the merchant is building needs theme changes and these are not available, recommend adding them from Shopify’s official install steps rather than installing them, and leave the choice to the merchant; without them, hand over the theme code instead. Littleworks never changes themes itself: theme changes are made with Shopify’s tools under the merchant’s own Shopify sign-in, with the merchant’s go-ahead, in an unpublished theme the merchant publishes.

Connect to the right store

For a concrete build, read the relevant recipe: reviews, wishlists, quote requests, back-in-stock alerts, or transactional email. Adapt it to the merchant’s requested scope. Recipes describe builds to implement, not features already installed in their store. Verify both Shopify and Littleworks connections target the intended store before combining tools.

Filter the Works table by its existing Data group (manifest.feature) to find related works. Group membership cannot be edited here; it determines which works share stored data.

Before handing off a build, delete temporary diagnostics, probes, or one-off setup works you created when they are no longer needed. Call delete_function once per work with its currentVersion from list_functions; it stops the work, so no separate pause is needed. Report how many test records remain (testCount from list_collections) and ask the merchant whether to delete them with delete_test_records. Keep required repair/recovery works and explain their purpose. Preserve unrelated works and data; deletion retains stored documents and historical runs/versions. A new work deployed under a deleted work’s name continues its version numbers.

For theme UI, build reusable, merchant-configurable components: theme blocks where supported, or sections and section blocks that fit the existing theme. Include schema settings and presets so merchants can edit content and presentation in the theme editor. Keep purchase verification and other authorization rules in works, independent of those settings.

Use the merchant’s existing connection or ask them to follow Connect your agent. The shared endpoint is https://littleworks.app/mcp. OAuth selects one store and binds the connection to it. Check the store returned by get_context. Do not request Shopify access tokens or replace other MCP configurations.

The server uses Streamable HTTP MCP and OAuth authorization code flow with S256 PKCE. It advertises authorization metadata and supports dynamic client registration. The merchant approves inside Shopify. One grant covers the whole store.

Inspect before changing anything

  1. Before building or making changes for a store, call get_context for the store, verified Shopify scopes, programming interface, and limits. For missing Shopify access, explain the minimum scopes needed and send the merchant to shopify.permissions.manageUrl. They approve in Shopify; call get_context again afterward. See Shopify permissions.
  2. Call list_functions to inspect existing works: their status (draft, published or paused), currentVersion, and newestVersion when a newer version is pending.
  3. Call get_function before changing an existing work. Preserve its feature and read its source.
  4. Stay within the merchant’s requested scope and approvals. If no further request has been given, report readiness and wait.

Deploy, test, publish

Draft things run the newest version; published things run the current version. A run is real only when it runs the current version of a published work. Every other run is a test run. See Write a work for the details.

  1. Write self-contained JavaScript and an explicit manifest. See Write a work.
  2. Deploy with deploy_function. A new work is a draft and the new version is current. On a published work the new version is pending: the current version keeps serving until it is published.
  3. Test with invoke_function and a fresh idempotency key. A draft runs its newest version. For a published work, pass the pending version as version: invoking it without one is a real run. Test HTTP works at their previewUrl and page works on the draft page.
  4. Test runs use the store’s real documents and secrets, and Shopify and external requests have real effects. Test against records your test created: updates and deletes of existing records are real.
  5. Inspect failures with get_run. Check for partial effects before retrying a mutation.
  6. Do not delete test records automatically. After testing, tell the merchant how many test records exist (testCount from list_collections) and ask whether to delete them, mentioning when a uniqueness rule means leftover test records could conflict with real saves. If they agree, delete_test_records removes every document a test run created, including setup data, so create real setup data with a real run of a published work, or keep it out of cleanup deliberately and say so. delete_record removes one record at its current revision.
  7. Publish only within the merchant’s instructions and approvals: publish_function for a work, publish_view for a page and the works it uses.
  8. Verify the required integration, including any frontend work outside Littleworks, before reporting the requested build or change complete.
  9. Hand off direct links to the view and any preview URL, name the related Data group, and explain where to inspect Runs and Usage. State what is published, which test records remain, and any remaining launch step such as publishing a theme.

Read these docs as Markdown

Every guide has a Markdown link. llms.txt provides the documentation index; llms-full.txt contains all guides in one response. Both are public and contain no store data. The connected store’s get_context is the source for its current capabilities.

See the MCP tool reference for exact tool arguments.