# AppListingLab agent handbook

Create store listing assets from real app captures and a shared App profile. Studio coordinates editable screenshot templates, Icon Studio, Google Play feature graphics, Apple creative images, ASO text, localization, export and supported store publishing. Use the current contract below to choose available API operations.

Documentation: https://applistinglab.com/docs/ai-agents
API base: https://api.applistinglab.com/api/v1
Stable OpenAPI: https://api.applistinglab.com/api/v1/developer/openapi.json

## MCP server

Work on screenshots, store copy and listing assets directly in Claude Code, Claude Desktop, Cursor or another MCP-compatible AI assistant. Connect your AppListingLab account using the setup below, then describe what you want to create.
Connection: run @applistinglab/mcp locally over stdio. There is no hosted MCP URL.

Claude Code:

```sh
claude mcp add applistinglab \
  -e APP_LISTING_LAB_API_KEY=your_developer_api_key \
  -e APP_LISTING_LAB_FILES_DIR=/absolute/path/to/store-assets \
  -- npx -y @applistinglab/mcp
```

Claude Desktop, Cursor and other mcpServers hosts:

```json
{
  "mcpServers": {
    "applistinglab": {
      "command": "npx",
      "args": [
        "-y",
        "@applistinglab/mcp"
      ],
      "env": {
        "APP_LISTING_LAB_API_KEY": "your_developer_api_key",
        "APP_LISTING_LAB_FILES_DIR": "/absolute/path/to/store-assets"
      }
    }
  }
}
```

Install Node.js 22.19 or later before connecting. Replace the example API key and folder path with your own values. APP_LISTING_LAB_FILES_DIR must point to an existing folder for source screenshots and downloaded files; file upload and download tools need this folder. To enable Google Play publishing, add APP_LISTING_LAB_ENABLE_PUBLISHING=true and use a key with the publish scope. Reconnect your assistant after changing the configuration or to refresh its available tools. Keep your API key in your assistant's private settings, outside chat messages and version control.

## Current API capabilities

- App profile list and manual app details: stable.
- Screenshot PNG generation: stable.
- Source screenshot upload: stable.
- Exact source and caption bindings: stable.
- ASO text generation: stable.
- ASO localization: stable.
- Google Play feature graphic: stable.
- Google Play publishing: stable.
- Existing Google Play icon upload: stable.

These statuses describe the versioned contract serving this environment. Use the stable OpenAPI for released operations.

## Shared execution instructions

Use AppListingLab for this task. If the AppListingLab MCP tools are connected, use them for these operations; the rules below still apply. API base: https://api.applistinglab.com/api/v1. Read https://api.applistinglab.com/api/v1/developer/openapi.json first. Read openapi.preview.json only when intentionally working in a development environment. Use only operations and fields present in that environment's contract. Obtain APP_LISTING_LAB_API_KEY from my local secret file or environment; never echo it, commit it, put it in a URL, or include it in the result. Keep all requests on this base and use the App profile owned by my account. Reuse my appId if I provide one; otherwise list my App profiles (GET /developer/apps) and reuse the matching one. When none matches, create one from my app's own name, description and category, taken from what I give you or my repository: this is the default, and the only way for an app that is not released yet. Add store links only for an app that is already published, to pull in its listing as a convenience; what I state always takes priority. Every create makes another profile. Persist IDs, exact request bodies and one Idempotency-Key per intended generation before sending it. Let backend eligibility and balance checks run automatically. Do not add a mandatory estimate or spend-confirmation step. Recover a timed-out request with its original key/body; do not create duplicate work. Respect Retry-After for rate limits. Poll accepted jobs with bounded backoff; pending is not success or failure. Download finished artifacts with authentication and verify their dimensions. Report actual job status and local output paths. If a required operation is unavailable, explain the specific Studio step needed instead of guessing an endpoint.

## Start an asset project

Give your assistant the context it needs to choose a supported workflow.

App name and what it does: [name; description]
Store links, if already released: [URLs, or none]
Target store and devices: [App Store / Google Play; device targets]
Source captures: [local folder]
Existing app icon: [local file, or locate the current launcher/store artwork in my repository]
Features we can truthfully show: [features]
Style or template preference: [preference, or recommend one]
Required assets and languages: [screenshots, existing app icon, feature graphic, ASO; locales]

Create a coherent asset set from the real app captures. Inventory the app icon as a separate deliverable. Reuse the existing icon rather than generating a replacement unless I request a redesign. App Store icons come from the app build; Google Play has a separate listing-icon upload. Use the App profile as shared context. Explain which requested assets can be produced with the available API and which use Studio. Do not invent product features, prices, ratings or results. Return the assets and a manifest; publish to a store only if I explicitly request publication.

## Generate screenshots from real captures

Use a selected template, your own captions and an exact source order where supported.

Create [COUNT] screenshots for [DEVICE] from [SOURCE FOLDER] for [APP ID, or my app's name and description]. Use [TEMPLATE NAME, or the server recommendation]. Discover supported devices and designs. Pin the returned designId and designVersion. Where source upload is supported, upload clean captures and persist their opaque sourceIds. Where frames are supported, bind each sourceId to its exact title/subtitle in display order. Otherwise use the supported captions workflow and sources already in the App profile. Use short, truthful benefit headlines and keep actual app UI intact. Do not replace the UI with an imagined screen. Render, download and inspect every PNG for clipping and source/caption order. Return a contact sheet, original output files and the reusable request manifest.

## Prepare ASO and regional text

Keep store fields, character limits and localization separate from unsupported keyword-volume claims.

Prepare listing text for [APP ID, or my app's name and description], store [STORE], locales [LOCALES]. Use only these verified features: [FEATURES]. Match the store's field limits. For Google Play, prepare title, shortDescription and fullDescription; do not invent a keyword field. For App Store, follow its supported fields. Where ASO generation/localization is enabled, generate the base listing and localize from its completed source job. Review every locale for invented claims, regional spelling and limits. Where it is unavailable in the API, use the ASO module in Studio. Return exact final fields and saved listing/job IDs. Keyword ideas are suggestions, not measured search volume. Do not publish unless I request it.

## Create a matching Google Play feature graphic

Keep the same visual direction across screenshots and the 1024 × 500 graphic.

Create a Google Play feature graphic for [APP ID], matching [SCREENSHOT DESIGN]. Use [ONE OR TWO SOURCE CAPTURES], headline [HEADLINE], subtitle [SUBTITLE] and a factual alt description. If feature graphic generation is present, use its semantic source/design contract and pin the returned design revision. Otherwise create it in Studio's Feature Graphic module. Verify the exported image is 1024 × 500 with the required opaque PNG encoding, readable copy and uncropped UI. Return the output and its source/design manifest. Keep store submission separate unless I requested it.

## Reuse an existing app icon

Locate the current brand artwork, prepare the correct store file and publish only when requested.

Reuse the existing icon for [APP ID / PACKAGE] from [REPOSITORY OR ICON FILE]. Inspect the app manifest and launcher asset references to identify the current artwork; do not choose an old preview or regenerate the brand. Prefer the original high-resolution artwork over upscaling a small launcher bitmap. For Google Play prepare a 512 x 512 PNG, at most 1 MiB, preserving the existing artwork and intended background. Do not bake in a rounded store mask. Return its preview and provenance. If I explicitly authorize publication, first discover the icon staging and readback operations in this environment, include icon in the immutable session parts and one image per selected locale, then stage the PNG data URL through the icon route. Persist the returned normalized SHA-256 and compare it with Google Play icon readback after a confirmed commit. A replay uses the same session and icon bytes. If the API does not support icon upload, identify the Studio step. App Store icons come from the app build and are not uploaded through this listing API.

## Publish an exact Google Play package

A separate task for an explicitly requested store update, with scope checks and readback.

I authorize updating Google Play for [APP ID / PACKAGE] in [LOCALES], using these exact reviewed text fields and Developer artifact IDs: [MANIFEST]. Parts: [aso / screenshots / feature-graphic / icon]. Existing icon file, if selected: [FILE]. Replace existing images: [true/false]. Review policy: [manual/submit]. First verify that Google Play publishing is in this environment's contract, that a connected store account exists and that my key includes publish. Do not broaden a key or change credentials silently. Prepare the immutable session, stage the complete ordered manifest, then start that session once. Reuse the existing icon if selected; discover the separate icon upload/readback routes before including it, count it in imageCount and preserve the returned normalized SHA-256. For text-only updates set imageCount to 0 and stage no images. Poll the publishing session route, not the generation-job route. If error, partial or uncertain is returned, inspect the safe failure code and reconcile that operation before a new attempt. Never cancel an existing review or change review policy without instruction. After a confirmed commit, read back and compare all text fields and selected icon hashes. Report provider confirmation separately from Google approval or public availability.