appilot-mcp 0.2.1 → 0.3.0

package/mcpb/manifest.json

@@ -2,9 +2,9 @@
 	"manifest_version": "0.3",
 	"name": "appilot-configurator",
 	"display_name": "Appilot Configurator",
-	"version": "0.2.1",
-	"description": "Configure, audit, repair, back up, and restore an Appilot app's content model.",
-	"long_description": "Connects Claude Desktop to an Appilot instance, cloud or on-premise, so it can read the app's content-model configuration, audit it against the Appilot config health contract, repair what it finds, and export or restore a whole configuration bundle. The static gate runs locally, so an audit works without network access to anything but your own instance. Access is a scoped service token you create in the Backoffice and revoke there.",
+	"version": "0.3.0",
+	"description": "Set up, configure, audit, repair, back up and restore an Appilot app's content model, and provision the app, its domains and its widget key.",
+	"long_description": "Connects Claude Desktop to an Appilot instance, cloud or on-premise. It provisions an app, its domains and its widget key, generates the host application's integration code, and verifies the result against the running page. It then reads the app's content-model configuration, audits it against the Appilot config health contract, repairs what it finds, and exports or restores a whole configuration bundle. The static gate runs locally, so an audit works without network access to anything but your own instance. Access is a scoped service token you create in the Backoffice and revoke there.",
 	"author": {
 		"name": "Appilot",
 		"url": "https://appilot.space"
@@ -12,13 +12,20 @@
 	"homepage": "https://appilot.space",
 	"documentation": "https://docs.appilot.space/docs/developers/configure-with-ai/overview",
 	"license": "ISC",
-	"keywords": ["appilot", "configuration", "content-model", "audit"],
+	"keywords": [
+		"appilot",
+		"configuration",
+		"content-model",
+		"audit"
+	],
 	"server": {
 		"type": "node",
 		"entry_point": "dist/index.bundle.js",
 		"mcp_config": {
 			"command": "node",
-			"args": ["${__dirname}/dist/index.bundle.js"],
+			"args": [
+				"${__dirname}/dist/index.bundle.js"
+			],
 			"env": {
 				"APPILOT_BASE_URL": "${user_config.base_url}",
 				"APPILOT_PAT": "${user_config.pat}",
@@ -27,21 +34,106 @@
 		}
 	},
 	"tools": [
-		{ "name": "capabilities", "description": "Probe the instance for its version, migration level, and configurable entities." },
-		{ "name": "read_config", "description": "Read an app's content-model configuration as a normalized snapshot." },
-		{ "name": "validate_config", "description": "Audit a configuration against the Appilot config health contract." },
-		{ "name": "entity_template", "description": "A valid skeleton for one entity kind, with the enums this instance accepts." },
-		{ "name": "create_entity", "description": "Create a view, control, form, tool, zone, action plan, knowledge article or session template." },
-		{ "name": "update_entity", "description": "Patch any of the eight entity kinds by its row id." },
-		{ "name": "delete_entity", "description": "Delete an entity, refused when something still references it." },
-		{ "name": "validate_action_plan", "description": "Check draft plan sections before writing them." },
-		{ "name": "inspect_page", "description": "Read a page and rank locator candidates. Takes a URL or pasted markup." },
-		{ "name": "export_config", "description": "Export the whole configuration as a portable ConfigBundle." },
-		{ "name": "import_config", "description": "Import a ConfigBundle, dry-run first, merge or replace." },
-		{ "name": "soak_selectors", "description": "Check control selectors against a live page. Needs Playwright." },
-		{ "name": "scaffold_agent_first", "description": "The four artifacts one capability needs to be agent-operable." },
-		{ "name": "report_feedback", "description": "Report a gap or a defect in Appilot. Needs the feedback:write scope." },
-		{ "name": "list_feedback", "description": "This organization's reports, with status and occurrence count." }
+		{
+			"name": "capabilities",
+			"description": "Probe the instance for its version, migration level, and the closed vocabularies its entities accept."
+		},
+		{
+			"name": "read_config",
+			"description": "Read an app's content-model configuration as a normalized snapshot."
+		},
+		{
+			"name": "validate_config",
+			"description": "Audit a configuration against the Appilot config health contract."
+		},
+		{
+			"name": "entity_template",
+			"description": "A valid skeleton for one entity kind, with the enums this instance accepts."
+		},
+		{
+			"name": "create_entity",
+			"description": "Create a view, control, form, tool, zone, action plan, knowledge article or session template."
+		},
+		{
+			"name": "update_entity",
+			"description": "Patch any of the eight entity kinds by its row id."
+		},
+		{
+			"name": "delete_entity",
+			"description": "Delete an entity, refused when something still references it."
+		},
+		{
+			"name": "validate_action_plan",
+			"description": "Check draft plan sections before writing them."
+		},
+		{
+			"name": "export_config",
+			"description": "Export the whole configuration as a portable ConfigBundle."
+		},
+		{
+			"name": "import_config",
+			"description": "Import a ConfigBundle, dry-run first, merge or replace."
+		},
+		{
+			"name": "whoami",
+			"description": "Which organization, which app and which scopes this credential reaches."
+		},
+		{
+			"name": "create_app",
+			"description": "Provision an app, its domains and a widget key, with the snippets to paste in."
+		},
+		{
+			"name": "list_apps",
+			"description": "The apps this organization has provisioned, with their domains and verification status."
+		},
+		{
+			"name": "list_widget_keys",
+			"description": "The organization's widget keys by label and prefix. No raw key, no secret."
+		},
+		{
+			"name": "verify_domain",
+			"description": "Where a domain's DNS verification stands, and the TXT record it needs."
+		},
+		{
+			"name": "integration_snippet",
+			"description": "The script tag and boot call for an app that already exists. Writes nothing."
+		},
+		{
+			"name": "plan_manifest",
+			"description": "Preview what an appilot.app-manifest would change. Writes nothing."
+		},
+		{
+			"name": "apply_manifest",
+			"description": "Provision and configure an app from a previously planned manifest."
+		},
+		{
+			"name": "scaffold_integration",
+			"description": "The host application's integration source: identity relay, widget boot, a client action."
+		},
+		{
+			"name": "verify_integration",
+			"description": "Load the running page and report what is actually true about the integration."
+		},
+		{
+			"name": "soak_selectors",
+			"description": "Check control selectors against a live page. Needs Playwright."
+		},
+		{
+			"name": "inspect_page",
+			"description": "Read a page and rank locator candidates. Takes a URL or pasted markup."
+		},
+		{
+			"name": "scaffold_agent_first",
+			"description": "The artifacts one capability needs to be agent-operable."
+		},
+		{
+			"name": "report_feedback",
+			"description": "Report a gap or a defect in Appilot. Needs the feedback:write scope."
+		},
+		{
+			"name": "list_feedback",
+			"description": "This organization's reports, with status and occurrence count."
+		}
 	],
 	"user_config": {
 		"base_url": {
@@ -65,7 +157,11 @@
 		}
 	},
 	"compatibility": {
-		"platforms": ["darwin", "win32", "linux"],
+		"platforms": [
+			"darwin",
+			"win32",
+			"linux"
+		],
 		"runtimes": {
 			"node": ">=18.0.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.3.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.