appilot-mcp 0.1.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.1.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,15 +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": "update_action_plan", "description": "Patch a stored action plan." },
-		{ "name": "update_control", "description": "Patch a control, for example to replace an unstable selector." },
-		{ "name": "update_knowledge", "description": "Patch a knowledge article." },
-		{ "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": "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": {
@@ -59,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.1.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

@@ -15,10 +15,14 @@ well-formed configuration; every rule maps to a real failure mode.
 
 ## Two modes
 
-- **Connected (Appilot MCP server available).** Tools `capabilities`, `read_config`,
-  `validate_config`, `update_action_plan` / `update_control` / `update_knowledge`,
-  `export_config` / `import_config`, and `soak_selectors` let you read, validate,
-  fix, back up, restore, and soak the user's live instance. Prefer this. Always
+- **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. `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
   (on-premise instances trail cloud).
 - **Advisory (no MCP).** Ask the user to paste or export their config (or read it
@@ -36,21 +40,53 @@ 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`.
+   halfway through. Provisioning needs `provision:write`, minted in the
+   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, 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.
@@ -58,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)
 
@@ -116,20 +163,82 @@ sparingly, over-authoring is an anti-pattern); the live DOM is ground truth.**
     as "Use when the user wants to…", localized. This is how the agent finds the
     plan; a weak/mislocalized description breaks adoption.
 
+## Authoring, one entity at a time
+
+`entity_template(kind)` first, for any kind you have not written this session. It
+returns a body with every container field present, the fields the write path
+refuses without, and the closed enums THIS instance accepts. Two failures repeat
+without it, and both are avoidable rather than diagnosable: a missing empty array
+or object, which the import answers with a path you then have to decode; and a
+guessed enum, because a brand-new app exports empty arrays and there was no
+example to copy. Control locators are `id`, `class_text`, `aria`, `xpath`,
+`semantic`. A CSS selector is not a kind, and a CSS selector list belongs under
+`class_text`.
+
+**Order is not a preference.** An entity that names another must come second.
+
+1. Controls, with stable locators.
+2. The form that names them as entry, submit and required fields.
+3. The tool, with its credential in the same call when it reaches an
+   authenticated backend. A tool with no stored credential runs in the page, so a
+   session template whose preflight calls it is refused.
+4. The action plan, after `validate_action_plan` on the draft sections.
+5. The knowledge article, carrying meaning and not steps.
+6. Activate what you created once `validate_config` is clean.
+
+**Look at the page before you author a control.** `inspect_page` takes a `url`
+and loads it, or `html` and scans markup the person pasted when there is no
+browser on this connection. It ranks locator candidates by whether they survive
+the next render and marks a framework-generated id as fragile, which is the
+defect that passes every static check and then resolves to nothing. A scan of
+pasted markup is not proof: run `soak_selectors` before you trust a locator.
+
+**Building a capability, not just fixing one.** `scaffold_agent_first` returns
+the four artifacts a capability needs so that a user could complete it through
+the assistant alone: the tool, the client action when the operation belongs in
+the page, the action plan that is the procedure, and the knowledge that carries
+the meaning. That test, whether a user could finish end to end through the
+assistant, is what agent-first means. A feature that only has a screen is not
+done.
+
+**A tool credential never travels over the remote transport.** `auth_secret` is
+refused there, on purpose: a tool argument on that transport is already stored in
+the conversation. Set it from a local stdio server, or in the Backoffice.
+
+## Reporting what is missing
+
+`report_feedback` records a gap or a defect in Appilot itself, or in this
+configuration. Say plainly what it does before you call it, because the honest
+version is short: the report is recorded and it is read, and a reply is part of a
+support plan rather than something promised here. The tool's answer says which of
+those applies to this organization.
+
+Call `list_feedback` first, so a known problem gets a counter rather than a
+duplicate. Show the person the exact title and body before sending. Never put
+configuration contents, knowledge bodies, customer data or a secret in a report;
+the machine context that matters (server version, failing tool, error code) is
+attached for you.
+
 ## Workflow
 
 1. **Discover.** Call `capabilities`. Note the version/migration level; degrade
    gracefully if a field is absent.
 2. **Read.** `read_config` for the target app. Understand the views, controls,
-   forms, plans, and knowledge.
+   forms, tools, zones, plans, and knowledge. If the result carries a `gaps`
+   array, an entity could not be read: say so, and do not report on it. Every
+   lint over a gap passed by default, which makes the rest of the report an
+   incomplete audit, not a clean one.
 3. **Validate.** `validate_config`. It runs the contract locally and echoes the
    server-side plan trust boundary. Read the severity-ranked findings.
 4. **Explain.** Give the user a prioritized, plain-language report (critical →
    low), each finding with the concrete fix. Do not dump raw tool output.
-5. **Fix (with consent).** Apply edits with `update_action_plan` /
-   `update_control` / `update_knowledge`. The server re-validates the trust
-   boundary and rejects an invalid write. For a broken create flow, that usually
-   means: add a `Form` (entry + submit + required field) → author the plan as
+5. **Fix (with consent).** Patch with `update_entity`, using the `kind` and the
+   row `id` `read_config` returns. Create with `create_entity`, after
+   `entity_template` for that kind. Remove with `delete_entity`, which refuses
+   and names the dependents when something still points at the entity; prefer
+   `is_active: false` when you mean retire rather than remove. Do not export and
+   re-import a bundle to change one thing. For a broken create flow the fix is
+   usually: add a `Form` (entry + submit + required field) → author the plan as
    open → choose → `{{form:…}}` → submit → localize name/description/narratives →
    give the control a stable selector.
 6. **Re-validate.** `validate_config` again; confirm the findings are gone.
@@ -170,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.