Write a work

A work has two parts: source code and a manifest describing its input, entry point, permissions, and data scope. The examples below illustrate the interface; deploy them only as part of an authorized build or change.

Write the handler#

Export one default async function. Littleworks supplies input, db, shopify, secrets, http, auth, cache, context, and log. cache.purge(work) clears a cached work’s responses after a write. Return a JSON-compatible value or Response.json(body, { status }).

export default async ({ input, db }) => {
  const notes = db.collection("notes");

  const note = await notes.create({
    message: input.message,
    status: "new",
  });

  return { id: note.id };
};

This example stores a note and returns its ID. It has no public endpoint and does not use Shopify. The manifest validates the message before the handler runs.

Describe the work#

{
  "name": "notes.save",
  "title": "Save a note",
  "feature": "notes",
  "trigger": {
    "type": "callable"
  },
  "permissions": {
    "shopify": false
  },
  "inputSchema": {
    "type": "object",
    "properties": {
      "message": {
        "type": "string",
        "minLength": 1,
        "maxLength": 1000
      }
    },
    "required": [
      "message"
    ],
    "additionalProperties": false
  }
}

Deploy, test, publish#

A work is a draft, published or paused. It keeps every version you deploy, and exactly one version is current. The rule that ties it together: draft things run the newest version; published things run the current version.

Call deploy_function with { manifest, source }. Pass the full manifest object and handler source string. Every deployment saves a new immutable version. On a draft it becomes current immediately. On a published or paused work it is saved as a pending version and the current version keeps serving; the response says which version is current.

{
  "name": "notes.save",
  "input": {
    "message": "A test note"
  },
  "idempotencyKey": "notes-save-test-001"
}

invoke_function runs a draft’s newest version as a test run. On a published work it runs the current version for real; pass version to test the pending version or any other one. The response includes test and the version that ran. Choose a new idempotency key for each intentional invocation. Reusing a key prevents replay with a conflict response; it does not return the original result. Use read_collection to inspect the note and list_runs to find the execution.

Publish, change and roll back#

publish_function with { name, version? } makes a version current and the work published, when the merchant’s instructions authorize it. version defaults to the newest. Before publishing, tell the merchant how many test records remain and ask whether to delete them with delete_test_records; leftover test records can conflict with real saves under a uniqueness rule.

To change a published work, deploy again: the new version waits as pending while customers keep using the current one. Test it by passing its version, then publish it. Publishing an earlier version is a rollback. Publishing a paused work also resumes it; set_function_state pauses and resumes a published work without changing its current version. Drafts cannot be paused, because they take no real traffic.

Keep the source self-contained#

MCP accepts JavaScript ES modules without imports or TypeScript syntax. It does not install dependencies or run a hosted build. The CLI can bundle compatible source locally before deployment. Packages cannot bypass the runtime’s network or capability restrictions.

The context contains storeId, shop, runId, test (true for test runs), and mode. Credentials and provider database bindings are never passed to your code. See Limits and security.