appilot-mcp 0.2.1 → 0.4.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "appilot-mcp",
-  "version": "0.2.1",
-  "description": "Appilot MCP server: read, validate, and fix an Appilot app's content-model configuration against the config health contract. Endpoint-agnostic (cloud or on-premise), scoped-service-token auth, local static gate + optional live DOM soak.",
+  "version": "0.4.0",
+  "description": "Appilot MCP server: provision an Appilot app, scaffold and verify the host integration, then read, validate and fix its content-model configuration against the config health contract. Endpoint-agnostic (cloud or on-premise), scoped-service-token auth, local static gate + optional live DOM soak.",
   "homepage": "https://appilot.space",
   "author": "BetterKnow GmbH",
   "keywords": [
@@ -24,6 +24,7 @@
   "files": [
     "dist",
     "skills",
+    "examples",
     "mcpb",
     ".mcp.json",
     ".codex-plugin",
@@ -66,6 +67,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "start:http": "node dist/index.bundle.js --http",
-    "build:mcpb": "node scripts/build-mcpb.mjs"
+    "build:mcpb": "node scripts/build-mcpb.mjs",
+    "build:marketplace": "node scripts/build-public-marketplace.mjs"
   }
 }

package/skills/app-configurator/SKILL.md

@@ -18,7 +18,9 @@ well-formed configuration; every rule maps to a real failure mode.
 - **Connected (Appilot MCP server available).** `capabilities`, `read_config` and
   `validate_config` read and audit. `entity_template`, `create_entity`,
   `update_entity`, `delete_entity` and `validate_action_plan` author, across all
-  eight entity kinds. `inspect_page` looks at the screen. `export_config` /
+  eight entity kinds. `whoami`, `list_apps`, `list_widget_keys`, `create_app`,
+  `verify_domain`, `scaffold_integration` and `integration_snippet` set an app up
+  from nothing. `inspect_page` looks at the screen. `export_config` /
   `import_config` back up, clone and promote. `soak_selectors` and
   `verify_integration` prove it works on the real page. Prefer this mode. Always
   start with `capabilities` so you configure against what THIS instance supports
@@ -39,25 +41,52 @@ runs in the customer's own repository, where you already are.
 1. **`whoami`.** Which org does this credential reach, and which scopes does it
    hold? A mistyped or revoked token should fail here, not as an opaque 401
    halfway through. Provisioning needs `provision:write`, minted in the
-   Backoffice under Admin, Service Tokens with the read/write/provision preset.
+   Backoffice under Service tokens with the preset called **Set up
+   integrations**. Only an organization administrator can mint it, so a
+   configurator who is not one has to ask for it rather than work around it.
+   `list_apps` then answers what already exists, and `list_widget_keys` answers
+   which keys were already minted, so a re-run recognises them instead of asking
+   for more.
 2. **`create_app`** with the app name and the domains it runs on. Idempotent, so
    a re-run converges rather than creating a second app. It returns the script
    tag, the boot snippet, and (once, at creation) the widget key and its secret.
    A **live** key needs a verified domain: on a hostname nobody has proved they
    control, the key comes back `blocked` with the TXT record to publish, while
-   the app and its domains are created anyway. Publish the record and verify, or
-   pass `isTest` for a test key that works the same way and claims nothing.
+   the app and its domains are created anyway. Publish the record, then
+   `verify_domain` with `trigger`, or pass `isTest: true` for a test key that
+   claims nothing. The parameter is `isTest`, the same name the manifest and the
+   API use.
    The **key** is publishable and belongs in the page. The **secret** is not: it
    goes in the host's backend environment and must never reach a browser or a
    client bundle. If you are connected over the remote transport the secret is
    withheld on purpose; point the user at the Backoffice for it.
-3. **`scaffold_integration`** for the host's framework. It returns file CONTENTS,
-   which you write into the repository. The identity relay is the piece that
-   matters: `resolveUser` is the security boundary and must derive the user from
-   a credential the host already trusts, never from the request body.
+
+   **Working on the user's own machine.** There are two answers and they are not
+   equal. Preferred: have them run the app on a hostname that resolves to
+   127.0.0.1 (`myapp.lvh.me:3000`, or an `/etc/hosts` entry) and register THAT
+   hostname as a domain. The page then resolves its tenant by hostname, no widget
+   key is needed, verification is not required for that path, and the turn gets
+   the full app context: views, controls, forms, plans, knowledge. Fallback:
+   bare `localhost` with a `wk_test_` key, which gets the organization and the
+   user and NO app context, because no domain resolves. Never pass `localhost` or
+   `127.0.0.1` as a domain: they name every developer's machine, one row for the
+   whole platform, and the write is refused.
+3. **`scaffold_integration`** for the host's framework, or `other` when the
+   backend is not Node (Django, Rails, PHP), which returns the raw exchange
+   instead. It returns file CONTENTS, which you write into the repository. The
+   identity relay is the piece that matters: `resolveUser` is the security
+   boundary and must derive the user from a credential the host already trusts,
+   never from the request body. The boot file reads the publishable key from the
+   framework's public variable (`NEXT_PUBLIC_APPILOT_WIDGET_KEY`,
+   `VITE_APPILOT_WIDGET_KEY`, `PUBLIC_APPILOT_WIDGET_KEY`); do not replace that
+   with a literal. `integration_snippet` returns the same two snippets later, for
+   an app that already exists, without a provisioning write.
 4. **Make one capability agent-operable** before adding screens' worth of
    configuration. The test for agent-first is whether a user could complete the
-   feature end to end through the assistant alone.
+   feature end to end through the assistant alone. `scaffold_agent_first` takes a
+   `shape`: `create` for an open/fill/submit flow, `navigate` for one step to a
+   screen, and `read` for a capability the agent answers, which gets no action
+   plan at all.
 5. **`verify_integration`** against the running page. It answers what is actually
    true: does the domain resolve to a tenant, does the relay refuse an
    unauthenticated caller correctly, does the widget boot, is the console clean.
@@ -65,12 +94,23 @@ runs in the customer's own repository, where you already are.
 6. Then configure the content model, below, and `validate_config`.
 
 **A whole tenant as one file.** `plan_manifest` / `apply_manifest` take an
-`appilot.app-manifest`: the app, its domains, its keys, and a ConfigBundle. Keep
-it in the repository under version control, so configuration is diffable in a
-pull request and promotable from staging to production. `apply_manifest` requires
-the `planToken` that `plan_manifest` returned for the same file, so you cannot
-apply something nobody previewed, and an edit between the two calls fails rather
-than committing silently.
+`appilot.app-manifest`: the app, its domains, its keys, and a ConfigBundle. A
+complete example ships with the server at `examples/app.appilot.json`; copy it
+rather than assembling one from doc snippets. Keep it in the repository under
+version control, so configuration is diffable in a pull request and promotable
+from staging to production. `apply_manifest` requires the `planToken` that
+`plan_manifest` returned for the same file, so you cannot apply something nobody
+previewed, and an edit between the two calls fails rather than committing
+silently.
+
+Two things about an apply are worth saying out loud. Only the CONFIG half is
+revisioned: every commit persists a `pre_restore` revision, so a wrong import is
+undone by restoring it, while a domain or a key the provisioning half created is
+undone by hand. And provisioning is asked for by the manifest, not by the tool:
+an apply whose app, domains and keys already exist needs only `config:write`,
+which is what lets a CI token keep content in sync without being able to claim
+domains. Outside an MCP client, `appilot-mcp plan <file>` and
+`appilot-mcp apply <file>` are the same two calls from a shell.
 
 ## The content model (what you configure)
 
@@ -239,10 +279,12 @@ file is safe to save, commit, or share. `read_config` stays the reasoning view;
 ## Guardrails
 
 - Confirm before writing. Show the diff you intend to apply; get a yes.
-- Writing needs a `config:write` service token; reading/validating needs only
-  `config:read`; provisioning needs `provision:write`. If a call 403s on scope,
-  tell the user to mint a token with that scope in the Backoffice (admin →
-  service tokens), don't work around it.
+- Writing needs a `config:write` service token; reading and validating need only
+  `config:read`; provisioning needs `provision:write`. If a call is refused on
+  scope, say which scope is missing and who grants it: `provision:write` comes
+  from an organization administrator in the Backoffice, under Service tokens
+  with the "Set up integrations" preset, or from the account approval screen. Do
+  not work around it.
 - **Never put a widget secret in a file that ships to the browser.** It goes in
   the server environment: no `NEXT_PUBLIC_` prefix, no `VITE_`, no committed
   `.env`. The publishable key is different and belongs in the page.