appdeploy

Files (5)

• LICENSE.txt
• SKILL.md
• openai.yaml · agents/
• appdeploy-small.svg · assets/
• appdeploy.png · assets/

SKILL.md (first lines)

# AppDeploy Skill

Deploy web apps to AppDeploy via HTTP API.

## Setup (First Time Only)

1. **Check for existing API key:**
   - Look for a `.appdeploy` file in the project root
   - If it exists and contains a valid `api_key`, skip to Usage

2. **If no API key exists, register and get one:**
   ```bash
   curl -X POST https://api-v2.appdeploy.ai/mcp/api-key \
     -H "Content-Type: application/json" \
     -d '{"client_name": "codex"}'
   ```

   Response:
   ```json
   {
     "api_key": "ak_...",
     "user_id": "agent-codex-a1b2c3d4",
     "created_at": 1234567890,
     "message": "Save this key securely - it cannot be retrieved later"
   }
   ```

3. **Save credentials to `.appdeploy`:**
   ```json
   {
     "api_key": "ak_...",
     "endpoint": "https://api-v2.appdeploy.ai/mcp"
   }
   ```

   Add `.appdeploy` to `.gitignore` if not already present.

## Usage

Make JSON-RPC calls to the MCP endpoint:

```bash
curl -X POST {endpoint} \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "{tool_name}",
      "arguments": { ... }
    }
  }'
```

## Workflow

1. **First, get deployment instructions:**
   Call `get_deploy_instructions` to understand constraints and requirements.

2. **Get the app template:**
   Call `get_app_template` with your chosen `app_type` and `frontend_template`. Returns starter files, deploy contract, and next steps.

3. **Get SDK reference for needed features:**
   Call `get_appdeploy_sdk_reference` once per top-level SDK feature before writing SDK code. See the SDK Features section for the catalog, scenario guidance, and dependency rules.

4. **Deploy the app:**
   Call `deploy_app` with your app files. For new apps, set `app_id` to `null`.
   Binary assets (images, fonts, media) go through `upload_assets` first - name each binary part by its app-relative source path (for react-vite: `public/<file>`, served at `/<file>`), then call `deploy_app` with the `upload_id` only.

5. **Check deployment status:**
   Call `get_app_status` to check if the build succeeded.

6. **View/manage your apps:**
   Use `get_apps` to list your deployed apps.

## SDK Features

Available features: api (HTTP transport and router basics), realtime (WebSocket live updates and subscriptions), auth (user accounts, middleware, and scopes), notifications (push notifications, topics, and enable/subscribe UX), invites (invite code lifecycle and client invite URL helpers), database (CRUD key-value tables), storage (file uploads, downloads, and signed URLs), secrets (encrypted app-scoped backend secrets), ai.generate (single LLM text or multimodal generation), ai.extract (schema-based structured extraction), ai.ocr (image OCR and transcription), ai.classify (fixed-label text or image classification), ai.scrape (AI-friendly web page scraper), ai.run (bounded generate-to-tool loops), ai.image (image generation), cron (scheduled jobs).

Choose features by scenario: Use api for standard backend HTTP routes and transport basics; realtime for live cross-client sync and subscriptions; auth for sign-in, user identity, and protected app state; notifications for push delivery and enable/subscribe UX; invites for share links, join codes, and invite lifecycle flows; database for persisted CRUD records; storage for file uploads/downloads and signed URLs; secrets for backend-only credentials or API keys; ai.generate for single generation calls; ai.extract for schema-based structured extraction; ai.ocr for OCR/transcription from images; ai.classify for fixed-label classification; ai.scrape for AI-friendly web page extraction; ai.run for bounded multi-step AI tool loops; ai.image for image generation; cron for scheduled jobs.

Dependency expansion: realtime -> realtime + api + database; auth -> auth + api; notifications -> notifications + api + auth; invites -> invites + api; database -> database + api; storage -> storage + api; secrets -> secrets + api; ai.generate -> ai.generate + api; ai.extract -> ai.extract + api; ai.ocr -> ai.ocr + api; ai.classify -> ai.classify + api; ai.scrape -> ai.scrape + api; ai.run -> ai.run + api; ai.image -> ai.image + api.

## Available Tools

### get_deploy_instructions

Use this first when the user wants to deploy, publish, or update a website or web app and get a public URL. You must call this tool before starting to design or generate any code. This tool returns instructions only and does not deploy anything.

**Parameters:**
  - `model`: any (optional) - Optional model name if known, for example 'gpt-5.5'. Omit or use null when unknown.
  - `intent`: any (optional) - Optional intent of this deployment. User-initiated examples: 'initial app deploy', 'bugfix - ui is too noisy'. Agent-initiated examples: 'agent fixing deployment error', 'agent retry after lint failure'. If no specific intent was given use 'app deploy'.
  - `description`: any (optional) - Optional one-line summary of the user prompt or agent task.

### get_app_template

Call get_deploy_instructions first. Then call this once you've decided app_type and frontend_template. Returns starter files, deploy contract, and next steps for a new app. The returned files are the baseline that deploy_app will diff against. Next, call get_appdeploy_sdk_reference once per top-level feature for SDK types, rules, and code reference. Do not separately request dependency features returned by a higher-level feature.

**Parameters:**
  - `app_type`: string (required) - 'frontend-only' (static/client-side apps; can use client-side auth), 'frontend+backend' (adds database, storage, server-side auth, and any other backend-required functionality.)
  - `frontend_template`: string (required) - 'html-static' (simple sites), 'react-vite' (SPAs, interactive apps, games), 'nextjs-static' (multi-page sites)
  - `features`: array (required) - SDK features to compose into the starter app (use [] when no SDK features are needed). See the SDK Features section. For frontend+backend apps, backend files are composed from these features.

### get_appdeploy_sdk_reference

Returns types, rules, and examples for one requested SDK feature plus its dependencies. Treat this as the implementation contract for that feature and review it before writing files that use it. Call get_appdeploy_sdk_reference once per top-level SDK feature, using the singular feature field with exactly one enum value. Request one top-level SDK feature per call. Do not separately request dependency features; request the highest-level feature and use the dependencies returned with it. See the SDK Features section.

**Parameters:**
  - `feature`: string (required) - Single SDK feature to get docs for. Pass exactly one enum value in the singular feature field. See the SDK Features section. Call get_appdeploy_sdk_reference once per top-level SDK feature, using the singular feature field with exactly one enum value. Request one top-level SDK feature per call. Do not separately request dependency features; request the highest-level feature and use the dependencies returned with it. See the SDK Features section.

### upload_assets

Use this before deploy_app whenever you need to send binary assets/resources or many files. Prefer this whenever the source of truth already exists as local files or a local project tree, especially for multiple files or whole-file replacements. This is the required path for images, backgrounds, icons, fonts, PDFs, media, archives, and other file assets you want deployed. Prepare local files and the upload manifest first. Call upload_assets only when you can upload immediately. If the upload_url expires before use or the upload fails because it expired, call upload_assets again to get a fresh upload_url and upload_id. PUT multipart/form-data to the returned upload_url: a 'payload' part (JSON manifest with text file changes/diffs and deletePaths) plus binary files named by app-relative path. The upload manifest carries all text changes and diffs plus deletePaths. After upload succeeds, call deploy_app with upload_id only. Do not also send files[] or deletePaths[]; those changes belong in the upload manifest. Never base64-encode binary assets into deploy_app.

**Parameters:**
No parameters required.

From AppDeploy-AI/skills, MIT.

More from AppDeploy-AI/skills