appilot-mcp 0.1.0 → 0.2.1

package/dist/templates.js

@@ -0,0 +1,255 @@
+/**
+ * Valid skeletons for each configurable entity.
+ *
+ * Pure: no SDK, no network. The instance's own vocabularies are passed in from
+ * `capabilities` rather than restated here, so a template can never advertise an
+ * enum value the write path rejects.
+ *
+ * Why this exists. Two authoring failures repeat, and both are answerable
+ * before the write rather than after it. A container field the entity kind
+ * declares is left out, and the import answers with a path the author then has
+ * to decode. And an enum value is guessed, because a brand-new app exports empty
+ * arrays and there was no example to copy: an agent reading a live page writes
+ * `locator_type: "css"`, which is not one of the kinds.
+ */
+function pick(vocab, path) {
+    const group = vocab[path[0]];
+    const values = group?.[path[1]];
+    return Array.isArray(values) && values.every(v => typeof v === 'string') ? values : null;
+}
+/**
+ * Build the skeleton for one kind.
+ *
+ * `appId` is filled in where the entity is app-scoped, because leaving it null
+ * produces a body that looks complete and is refused.
+ */
+export function entityTemplate(kind, appId, vocab = {}) {
+    const locatorTypes = pick(vocab, ['controls', 'locator_type']);
+    const controlScopes = pick(vocab, ['controls', 'scope']);
+    const knowledgeScopes = pick(vocab, ['knowledge_content', 'scope']);
+    const knowledgeVisibility = pick(vocab, ['knowledge_content', 'visibility']);
+    const markerKinds = pick(vocab, ['action_plans', 'marker_kinds']);
+    const landmarkRoles = pick(vocab, ['zones', 'landmark_role']);
+    switch (kind) {
+        case 'view':
+            return {
+                kind,
+                body: {
+                    app_id: appId,
+                    domain_id: null,
+                    name: '',
+                    path: '/',
+                    slug: '',
+                    description: '',
+                    entry_path: null,
+                    name_i18n: {},
+                    description_i18n: {},
+                    rules: [],
+                },
+                required: ['app_id', 'domain_id', 'name', 'path'],
+                vocabularies: {},
+                notes: [
+                    'domain_id names one registered hostname. Read the app\'s domains first; a view on an unregistered hostname can never resolve a tenant.',
+                    'path is the route as the browser shows it, and it is half the view\'s identity in a bundle.',
+                    'entry_path, when set, must be path-absolute.',
+                ],
+            };
+        case 'control':
+            return {
+                kind,
+                body: {
+                    app_id: appId,
+                    semantic_id: '',
+                    locator: '',
+                    locator_type: locatorTypes?.[0] ?? '',
+                    label: '',
+                    description: '',
+                    llm_hint: null,
+                    label_i18n: {},
+                    description_i18n: {},
+                    view_path: null,
+                    scope: controlScopes?.[0] ?? '',
+                    prerequisites: [],
+                    form_id: null,
+                    form_order: null,
+                },
+                required: ['app_id', 'semantic_id', 'locator', 'locator_type'],
+                vocabularies: {
+                    ...(locatorTypes ? { locator_type: locatorTypes } : {}),
+                    ...(controlScopes ? { scope: controlScopes } : {}),
+                },
+                notes: [
+                    'locator_type is a closed set and `css` is not in it. A CSS selector list belongs under class_text.',
+                    'A stable locator is a data attribute, an aria role or a placeholder. An auto-generated id or an :nth-child position passes every static check and is gone on the next render.',
+                    'scope=global takes no view_path.',
+                    'A control becomes a FIELD of a form by carrying form_id and form_order, together, on its own row. The form\'s required_field_ids does not create that membership. Create the form first, then patch each field control with the form\'s row id and its fill order counting from 0, or a plan that fills the form is refused with "field does not belong to form".',
+                    'The control that OPENS a form is the form\'s entry_control and must not also be one of its fields.',
+                    'semantic_id is a short English slug that survives a label change, not a slugified UI label.',
+                ],
+            };
+        case 'form':
+            return {
+                kind,
+                body: {
+                    app_id: appId,
+                    semantic_id: '',
+                    label: '',
+                    domain_id: null,
+                    description: '',
+                    llm_hint: null,
+                    label_i18n: {},
+                    description_i18n: {},
+                    view_paths: [],
+                    required_field_ids: [],
+                    submit_control_id: null,
+                    entry_control_id: null,
+                    visibility_rules: null,
+                    field_defaults: null,
+                    prerequisites: [],
+                    is_active: true,
+                },
+                required: ['app_id', 'semantic_id', 'label'],
+                vocabularies: {},
+                notes: [
+                    'The controls a form names must exist first: create them, then the form.',
+                    'entry_control is what OPENS the form, so it cannot also be one of required_field_ids. The three roles are distinct controls: one opens, several are filled, one submits.',
+                    'view_paths cannot be empty: a form nobody can reach from a view is refused.',
+                    'required_field_ids records which of the form\'s EXISTING fields are mandatory, and it does not create membership. So the order is: create the form with an empty required_field_ids, patch each field control with form_id and form_order, then patch the form with required_field_ids.',
+                    'A form without an entry control and a submit control cannot carry a create flow, and the health contract will say so.',
+                ],
+            };
+        case 'tool':
+            return {
+                kind,
+                body: {
+                    app_id: appId,
+                    tool_name: '',
+                    title: '',
+                    description: '',
+                    view_id: null,
+                    parameters: {},
+                    runtime_spec: {},
+                    title_i18n: {},
+                    description_i18n: {},
+                },
+                required: ['app_id', 'tool_name', 'title', 'description'],
+                vocabularies: {},
+                notes: [
+                    'description is what the agent reads to decide whether to call this at all. Write the trigger, not the implementation.',
+                    'runtime_spec is a discriminated union on `kind`. For `http_proxy` it needs `method` and `path_template`, a path on the host application origin; an absolute URL is rejected, because a server-side call is proxied to the app\'s own origin and nowhere else. For `client_action` the page owns the behaviour and registers it at runtime.',
+                    'A server-side tool stores its credential through auth_secret and auth_header_name on this same body. That value is write-only and never comes back on a read.',
+                    'auth_header_name defaults to Authorization and cannot be a hop-by-hop header.',
+                ],
+            };
+        case 'zone':
+            return {
+                kind,
+                body: {
+                    domain_id: null,
+                    app_id: appId,
+                    semantic_id: '',
+                    label: '',
+                    label_i18n: {},
+                    description: '',
+                    description_i18n: {},
+                    selector: '',
+                    landmark_role: null,
+                    parent_zone_id: null,
+                    view_paths: [],
+                },
+                required: ['domain_id', 'semantic_id', 'label', 'selector'],
+                vocabularies: landmarkRoles ? { landmark_role: landmarkRoles } : {},
+                notes: [
+                    'A zone is a passive region the agent refers to. If it can be clicked, it is a control.',
+                    'Zones are domain-scoped, so domain_id is required and app_id only narrows it.',
+                ],
+            };
+        case 'action_plan':
+            return {
+                kind,
+                body: {
+                    app_id: appId,
+                    semantic_id: '',
+                    name: '',
+                    description: '',
+                    sections: [],
+                    form_values: {},
+                    step_narratives_i18n: {},
+                    is_active: true,
+                },
+                required: ['app_id', 'semantic_id'],
+                vocabularies: markerKinds ? { marker_kinds: markerKinds } : {},
+                notes: [
+                    'description is the agent-facing trigger, written as "Use when the user wants to ...", and localized. A weak description means the plan is never adopted.',
+                    'Each step carries exactly one executable marker. Values never go inside a marker; they ride form_values keyed by form.',
+                    'A create flow must enter a value and submit. A plan that only opens or focuses an element does nothing, and that is the most common defect there is.',
+                    'Validate the sections with validate_action_plan before writing them.',
+                ],
+            };
+        case 'knowledge':
+            return {
+                kind,
+                body: {
+                    application_id: appId,
+                    title: '',
+                    description: '',
+                    general_info: '',
+                    notes: '',
+                    url_pattern: null,
+                    domain: null,
+                    language: 'en',
+                    visibility: knowledgeVisibility?.[0] ?? '',
+                    is_active: true,
+                },
+                required: ['title'],
+                vocabularies: {
+                    ...(knowledgeScopes ? { scope: knowledgeScopes } : {}),
+                    ...(knowledgeVisibility ? { visibility: knowledgeVisibility } : {}),
+                },
+                notes: [
+                    'scope is derived from url_pattern, so narrow the article by giving it a pattern rather than by naming a scope.',
+                    'Knowledge carries meaning: workflows, rules, terminology. A step-by-step article is a procedure in the wrong place, and it competes with the action plan that owns it.',
+                    'is_active defaults to false on this endpoint. Set it explicitly when the article should be live.',
+                ],
+            };
+        case 'session_template':
+            return {
+                kind,
+                body: {
+                    app_id: appId,
+                    semantic_id: '',
+                    name: '',
+                    description: '',
+                    mission_prompt: '',
+                    outcome_schema: { type: 'object', properties: {}, required: [] },
+                    variables: [],
+                    allowed_tools: [],
+                    preflight: [],
+                    presentation: null,
+                    kb_doc_ids: null,
+                    max_turns: null,
+                    is_active: true,
+                    name_i18n: {},
+                    description_i18n: {},
+                    mission_prompt_i18n: {},
+                },
+                required: ['app_id', 'semantic_id', 'name', 'mission_prompt', 'outcome_schema'],
+                vocabularies: {},
+                notes: [
+                    'A preflight entry names a tool that must already hold a stored credential. A tool that runs in the page cannot be called before the session exists, and the write is refused. Create the tool with its credential first.',
+                    'A field the reviewer must have belongs in outcome_schema.required. An optional field is a field the model renames or drops.',
+                    'If the model must do something for the session to be valid, it is a precondition the runtime enforces through preflight, not a sentence in the mission.',
+                ],
+            };
+    }
+}
+export const TEMPLATE_KINDS = [
+    'view',
+    'control',
+    'form',
+    'tool',
+    'zone',
+    'action_plan',
+    'knowledge',
+    'session_template',
+];

package/dist/verify.js

@@ -61,7 +61,15 @@ async function checkWidgetBoots(url, storageStatePath) {
             check('widget-boot', 'Widget boots on the page', 'skip', 'Playwright is not installed.', 'npm i -D playwright && npx playwright install chromium, then re-run to check the browser half.'),
         ];
     }
-    const browser = await chromium.launch();
+    let browser;
+    try {
+        browser = await chromium.launch();
+    }
+    catch (error) {
+        return [
+            check('widget-boot', 'Widget boots on the page', 'skip', `A browser could not be launched: ${error instanceof Error ? error.message : String(error)}`, 'Run npx playwright install chromium, then re-run to check the browser half.'),
+        ];
+    }
     try {
         const context = await browser.newContext(storageStatePath ? { storageState: storageStatePath } : {});
         const page = await context.newPage();
@@ -93,6 +101,15 @@ async function checkWidgetBoots(url, storageStatePath) {
         }
         return checks;
     }
+    catch (error) {
+        // The browser half must not take the run down with it. Navigation is the
+        // most likely thing to fail here (the page is not up yet, DNS does not
+        // resolve, TLS is wrong), and that is exactly the moment the caller needs
+        // the four network checks that already ran.
+        return [
+            check('widget-boot', 'Widget boots on the page', 'fail', `The page could not be loaded in a browser: ${error instanceof Error ? error.message : String(error)}`, 'Confirm the URL is reachable from this machine, then re-run. The network checks above still apply.'),
+        ];
+    }
     finally {
         await browser.close();
     }

package/dist/version.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The version this server reports on initialize.
+ *
+ * A constant, not a read of `package.json`. The published bundle is the only
+ * file in the Cloud Run image, so a runtime read resolves to a path that does
+ * not exist there and takes the service down on start. Reading it at build time
+ * would work for the bundle and diverge for the `tsc` output.
+ *
+ * The number also lives in `package.json`, the MCP bundle manifest and both
+ * plugin manifests. `test/version.test.ts` holds all five to this value, because
+ * hand-synced numbers drift and the drift shows up as a client reporting a
+ * version the server does not have.
+ */
+export declare const SERVER_VERSION = "0.2.1";

package/dist/version.js

@@ -0,0 +1,14 @@
+/**
+ * The version this server reports on initialize.
+ *
+ * A constant, not a read of `package.json`. The published bundle is the only
+ * file in the Cloud Run image, so a runtime read resolves to a path that does
+ * not exist there and takes the service down on start. Reading it at build time
+ * would work for the bundle and diverge for the `tsc` output.
+ *
+ * The number also lives in `package.json`, the MCP bundle manifest and both
+ * plugin manifests. `test/version.test.ts` holds all five to this value, because
+ * hand-synced numbers drift and the drift shows up as a client reporting a
+ * version the server does not have.
+ */
+export const SERVER_VERSION = '0.2.1';

package/mcpb/manifest.json

@@ -2,7 +2,7 @@
 	"manifest_version": "0.3",
 	"name": "appilot-configurator",
 	"display_name": "Appilot Configurator",
-	"version": "0.1.0",
+	"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.",
 	"author": {
@@ -30,12 +30,18 @@
 		{ "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": "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": "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." }
 	],
 	"user_config": {
 		"base_url": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appilot-mcp",
-  "version": "0.1.0",
+  "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.",
   "homepage": "https://appilot.space",
   "author": "BetterKnow GmbH",

package/skills/app-configurator/SKILL.md

@@ -15,10 +15,12 @@ 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. `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,10 +38,15 @@ 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 Admin, Service Tokens with the read/write/provision preset.
 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 **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
@@ -116,20 +123,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.