appilot-mcp 0.1.1 → 0.3.0

package/dist/index.js

@@ -20,6 +20,7 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { loadConnection, loadRemoteConfig, resolveTransport, RemoteConfigError } from './config.js';
 import { createAppilotServer } from './server.js';
+import { runCommand } from './cli.js';
 async function runStdio() {
     const conn = loadConnection();
     const server = createAppilotServer(conn);
@@ -32,6 +33,12 @@ async function runHttp() {
     await startRemote(loadRemoteConfig());
 }
 async function main() {
+    // A subcommand answers and exits. Without this, `appilot-mcp --help` started
+    // the stdio server and waited on stdin, which reads as a hang.
+    const handled = await runCommand(process.argv.slice(2));
+    if (handled !== null) {
+        process.exit(handled);
+    }
     if (resolveTransport() === 'http') {
         await runHttp();
         return;

package/dist/inspect.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Read a page and report what an author needs to register it.
+ *
+ * This is the half of the tool surface that was missing for the developer who
+ * says "look at this screen and configure it". Everything else could read the
+ * configuration and validate it; nothing could see the thing being configured,
+ * so a control's locator had to come from a human picking it in the extension.
+ *
+ * Two paths, because the transports differ in what they can run.
+ *
+ *   url   Loads the real page in Playwright. Playwright is an optional peer, so
+ *         this path degrades rather than crashing, exactly as `soak.ts` and
+ *         `verify.ts` do.
+ *   html  Scans pasted markup with no browser. Flat and structural only: it
+ *         reads the attributes on interactive tags in document order and groups
+ *         fields by the form they appear inside. It cannot compute an accessible
+ *         name, and it does not know what is visible. It is what keeps the
+ *         hosted endpoint useful, and it says which of the two produced a
+ *         result so nobody mistakes one for the other.
+ *
+ * A locator candidate is ranked by whether it survives the next render, which
+ * is the only property that matters: an auto-generated id passes every static
+ * check and is gone on redeploy. The `type` on each candidate is an Appilot
+ * `locator_type`, not a CSS selector kind, so the output can be pasted into a
+ * control body unchanged.
+ */
+export type LocatorType = 'id' | 'class_text' | 'aria' | 'xpath' | 'semantic';
+export interface LocatorCandidate {
+    locator: string;
+    type: LocatorType;
+    /** Higher is more likely to still resolve after the next deploy. */
+    stability: 'stable' | 'reasonable' | 'fragile';
+    why: string;
+}
+export interface InspectedElement {
+    tag: string;
+    role: string | null;
+    text: string | null;
+    kind: 'action' | 'field' | 'region';
+    /** Best first. */
+    candidates: LocatorCandidate[];
+    /** Semantic id of an already-configured control whose locator matches. */
+    configuredAs?: string;
+}
+export interface InspectedForm {
+    /** The form's own candidates, for the entry control. */
+    candidates: LocatorCandidate[];
+    fields: InspectedElement[];
+    submit: InspectedElement | null;
+}
+export interface InspectResult {
+    source: 'browser' | 'html';
+    available: boolean;
+    url?: string;
+    /** The path a View would carry, when a URL was given. */
+    viewPath?: string;
+    elements: InspectedElement[];
+    forms: InspectedForm[];
+    /** What is already registered for this view, so nothing is authored twice. */
+    alreadyConfigured?: {
+        controls: string[];
+        forms: string[];
+        zones: string[];
+    };
+    note?: string;
+}
+/**
+ * Rank the ways to address one element.
+ *
+ * Order is the contract: whoever consumes this takes the first candidate unless
+ * they have a reason not to, so the first candidate must be the one that ages
+ * best, never the shortest.
+ */
+export declare function rankCandidates(attrs: Record<string, string>, tag: string, text: string | null): LocatorCandidate[];
+/**
+ * Scan pasted markup for interactive elements.
+ *
+ * Deliberately flat. It walks tag openings in document order and tracks only one
+ * nesting fact, whether it is currently inside a form, because that is the one
+ * relationship the content model needs and the one a regex can get right.
+ */
+export declare function inspectHtml(html: string): InspectResult;
+export declare function inspectPage(opts: {
+    url?: string;
+    html?: string;
+    storageStatePath?: string;
+    timeoutMs?: number;
+}): Promise<InspectResult>;

package/dist/inspect.js

@@ -0,0 +1,384 @@
+/**
+ * Read a page and report what an author needs to register it.
+ *
+ * This is the half of the tool surface that was missing for the developer who
+ * says "look at this screen and configure it". Everything else could read the
+ * configuration and validate it; nothing could see the thing being configured,
+ * so a control's locator had to come from a human picking it in the extension.
+ *
+ * Two paths, because the transports differ in what they can run.
+ *
+ *   url   Loads the real page in Playwright. Playwright is an optional peer, so
+ *         this path degrades rather than crashing, exactly as `soak.ts` and
+ *         `verify.ts` do.
+ *   html  Scans pasted markup with no browser. Flat and structural only: it
+ *         reads the attributes on interactive tags in document order and groups
+ *         fields by the form they appear inside. It cannot compute an accessible
+ *         name, and it does not know what is visible. It is what keeps the
+ *         hosted endpoint useful, and it says which of the two produced a
+ *         result so nobody mistakes one for the other.
+ *
+ * A locator candidate is ranked by whether it survives the next render, which
+ * is the only property that matters: an auto-generated id passes every static
+ * check and is gone on redeploy. The `type` on each candidate is an Appilot
+ * `locator_type`, not a CSS selector kind, so the output can be pasted into a
+ * control body unchanged.
+ */
+/**
+ * Ids a framework generated. Registering one of these is the single most common
+ * way a configuration passes every check and then does nothing on the real page.
+ */
+const GENERATED_ID = [
+    /^(nc|mui|radix|headlessui|chakra|mantine|ember|ext-gen|yui)[-_:]/i,
+    /^:r[0-9a-z]+:$/i,
+    /^[a-f0-9]{8,}$/i,
+    /\d{4,}$/,
+    /^react-aria\d+$/i,
+];
+function idLooksGenerated(id) {
+    return GENERATED_ID.some(re => re.test(id));
+}
+const TEST_ATTRS = ['data-testid', 'data-test-id', 'data-test', 'data-qa', 'data-cy', 'data-automation-id'];
+const ACTION_TAGS = new Set(['button', 'a', 'summary']);
+const FIELD_TAGS = new Set(['input', 'select', 'textarea']);
+const REGION_TAGS = new Set(['nav', 'main', 'aside', 'header', 'footer', 'section', 'form']);
+/**
+ * Rank the ways to address one element.
+ *
+ * Order is the contract: whoever consumes this takes the first candidate unless
+ * they have a reason not to, so the first candidate must be the one that ages
+ * best, never the shortest.
+ */
+export function rankCandidates(attrs, tag, text) {
+    const out = [];
+    const q = (v) => v.replace(/"/g, '\\"');
+    for (const attr of TEST_ATTRS) {
+        const value = attrs[attr];
+        if (value) {
+            out.push({
+                locator: `[${attr}="${q(value)}"]`,
+                type: 'class_text',
+                stability: 'stable',
+                why: 'A test attribute exists to be addressed and is not rewritten by a redesign.',
+            });
+        }
+    }
+    if (attrs['aria-label']) {
+        out.push({
+            locator: attrs['aria-label'],
+            type: 'aria',
+            stability: 'stable',
+            why: 'An accessible name is user-visible and changes only when the interface changes.',
+        });
+    }
+    const id = attrs.id;
+    if (id) {
+        if (idLooksGenerated(id)) {
+            out.push({
+                locator: `#${id}`,
+                type: 'id',
+                stability: 'fragile',
+                why: 'This id looks generated by a framework. It will differ on the next render. Do not register it.',
+            });
+        }
+        else {
+            out.push({
+                locator: `#${id}`,
+                type: 'id',
+                stability: 'stable',
+                why: 'An authored id is addressed directly and survives styling changes.',
+            });
+        }
+    }
+    if (attrs.name && (FIELD_TAGS.has(tag) || tag === 'form')) {
+        out.push({
+            locator: `[name="${q(attrs.name)}"]`,
+            type: 'class_text',
+            stability: 'stable',
+            why: 'A field name is part of the form contract, so it outlives the markup around it.',
+        });
+    }
+    if (attrs.placeholder) {
+        out.push({
+            locator: `[placeholder="${q(attrs.placeholder)}"]`,
+            type: 'class_text',
+            stability: 'reasonable',
+            why: 'A placeholder is user-visible copy, so it moves with translation and rewording.',
+        });
+    }
+    if (attrs.role && text) {
+        out.push({
+            locator: `${attrs.role}:${text}`,
+            type: 'aria',
+            stability: 'reasonable',
+            why: 'Role plus accessible name, which is how a person finds the element.',
+        });
+    }
+    if (text && text.length <= 60) {
+        out.push({
+            locator: text,
+            type: 'semantic',
+            stability: 'reasonable',
+            why: 'Visible text. Correct until the copy is reworded or translated.',
+        });
+    }
+    if (out.length === 0) {
+        out.push({
+            locator: tag,
+            type: 'class_text',
+            stability: 'fragile',
+            why: 'Nothing addressable on this element. Ask the app team for a data attribute before registering it.',
+        });
+    }
+    const rank = { stable: 0, reasonable: 1, fragile: 2 };
+    return out.sort((a, b) => rank[a.stability] - rank[b.stability]);
+}
+function classify(tag, role) {
+    if (FIELD_TAGS.has(tag))
+        return 'field';
+    if (ACTION_TAGS.has(tag) || role === 'button' || role === 'link' || role === 'menuitem')
+        return 'action';
+    return 'region';
+}
+/* -------------------------------------------------------------------------- */
+/* Pasted markup                                                              */
+/* -------------------------------------------------------------------------- */
+const TAG_RE = /<\/?([a-zA-Z][a-zA-Z0-9-]*)((?:\s+[^\s"'>/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'>`]+))?)*)\s*\/?>/g;
+const ATTR_RE = /([^\s"'>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>`]+)))?/g;
+function parseAttrs(raw) {
+    const attrs = {};
+    ATTR_RE.lastIndex = 0;
+    let m;
+    while ((m = ATTR_RE.exec(raw)) !== null) {
+        const name = m[1].toLowerCase();
+        attrs[name] = m[2] ?? m[3] ?? m[4] ?? '';
+    }
+    return attrs;
+}
+function stripTags(html) {
+    return html.replace(/<[^>]*>/g, ' ').replace(/\s+/g, ' ').trim();
+}
+/**
+ * Scan pasted markup for interactive elements.
+ *
+ * Deliberately flat. It walks tag openings in document order and tracks only one
+ * nesting fact, whether it is currently inside a form, because that is the one
+ * relationship the content model needs and the one a regex can get right.
+ */
+export function inspectHtml(html) {
+    const elements = [];
+    const forms = [];
+    let current = null;
+    TAG_RE.lastIndex = 0;
+    let match;
+    while ((match = TAG_RE.exec(html)) !== null) {
+        const raw = match[0];
+        const tag = match[1].toLowerCase();
+        const closing = raw.startsWith('</');
+        if (tag === 'form') {
+            if (closing) {
+                if (current)
+                    forms.push(current);
+                current = null;
+            }
+            else {
+                const attrs = parseAttrs(match[2] ?? '');
+                current = { candidates: rankCandidates(attrs, 'form', null), fields: [], submit: null };
+            }
+            continue;
+        }
+        if (closing)
+            continue;
+        if (!ACTION_TAGS.has(tag) && !FIELD_TAGS.has(tag) && !REGION_TAGS.has(tag))
+            continue;
+        const attrs = parseAttrs(match[2] ?? '');
+        if (attrs.type === 'hidden')
+            continue;
+        // Text runs to the matching close tag when there is one on the same
+        // nesting level. Good enough for a button label, which is what it is for.
+        let text = null;
+        if (!FIELD_TAGS.has(tag)) {
+            const close = html.indexOf(`</${tag}`, match.index + raw.length);
+            if (close > -1 && close - match.index < 2000) {
+                const inner = stripTags(html.slice(match.index + raw.length, close));
+                text = inner ? inner.slice(0, 120) : null;
+            }
+        }
+        if (!text && attrs.value && FIELD_TAGS.has(tag))
+            text = attrs.value.slice(0, 120);
+        const role = attrs.role ?? null;
+        const element = {
+            tag,
+            role,
+            text,
+            kind: classify(tag, role),
+            candidates: rankCandidates(attrs, tag, text),
+        };
+        const isSubmit = tag === 'button'
+            ? attrs.type !== 'button' && attrs.type !== 'reset'
+            : tag === 'input' && attrs.type === 'submit';
+        if (current) {
+            if (isSubmit && !current.submit)
+                current.submit = element;
+            else if (element.kind === 'field')
+                current.fields.push(element);
+            else
+                elements.push(element);
+        }
+        else {
+            elements.push(element);
+        }
+    }
+    if (current)
+        forms.push(current);
+    return {
+        source: 'html',
+        available: true,
+        elements,
+        forms,
+        note: 'Scanned pasted markup with no browser. Visibility, computed roles and accessible names are unknown here, and nothing confirms these selectors resolve on the running page. Run soak_selectors, or inspect by URL from a local server, before trusting a locator.',
+    };
+}
+/* -------------------------------------------------------------------------- */
+/* Live page                                                                  */
+/* -------------------------------------------------------------------------- */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+async function loadPlaywright() {
+    try {
+        return await import('playwright');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * What runs inside the page. Returns raw attribute bags, so the ranking stays
+ * here in one place and is unit-testable without a browser.
+ */
+const EXTRACT = `() => {
+  const out = [];
+  const sel = 'button, a[href], input, select, textarea, summary, [role="button"], [role="link"], [role="menuitem"], nav, main, aside, header, footer, form';
+  for (const el of document.querySelectorAll(sel)) {
+    const rect = el.getBoundingClientRect();
+    const style = getComputedStyle(el);
+    if (style.display === 'none' || style.visibility === 'hidden') continue;
+    if (rect.width === 0 && rect.height === 0 && el.tagName !== 'FORM') continue;
+    const attrs = {};
+    for (const a of el.attributes) attrs[a.name.toLowerCase()] = a.value;
+    const label = (el.getAttribute('aria-label') || el.textContent || '').replace(/\\s+/g, ' ').trim();
+    out.push({
+      tag: el.tagName.toLowerCase(),
+      attrs,
+      text: label ? label.slice(0, 120) : null,
+      formIndex: el.form ? Array.prototype.indexOf.call(document.forms, el.form) : -1,
+      isSubmit: (el.tagName === 'BUTTON' && el.type !== 'button' && el.type !== 'reset') || (el.tagName === 'INPUT' && el.type === 'submit'),
+    });
+  }
+  return out;
+}`;
+export async function inspectPage(opts) {
+    if (opts.html)
+        return inspectHtml(opts.html);
+    if (!opts.url) {
+        return {
+            source: 'html',
+            available: false,
+            elements: [],
+            forms: [],
+            note: 'Pass either a url to load, or html to scan.',
+        };
+    }
+    const playwright = await loadPlaywright();
+    if (!playwright) {
+        return {
+            source: 'browser',
+            available: false,
+            elements: [],
+            forms: [],
+            note: 'No browser is available here, so this page cannot be loaded. Two ways forward, in order of preference: ask the person to open the page, copy the outerHTML of the region they care about, and call this tool again with `html` instead of `url`; or run the Appilot MCP server locally over stdio, where Playwright can be installed (pnpm add -D playwright && npx playwright install chromium).',
+        };
+    }
+    let browser;
+    try {
+        browser = await playwright.chromium.launch({ headless: true });
+    }
+    catch (err) {
+        return {
+            source: 'browser',
+            available: false,
+            elements: [],
+            forms: [],
+            note: `A browser could not be launched: ${err instanceof Error ? err.message : String(err)}. Run npx playwright install chromium, or pass html instead of url.`,
+        };
+    }
+    try {
+        const context = await browser.newContext(opts.storageStatePath ? { storageState: opts.storageStatePath } : undefined);
+        const page = await context.newPage();
+        await page.goto(opts.url, { waitUntil: 'domcontentloaded', timeout: opts.timeoutMs ?? 20000 });
+        const raw = (await page.evaluate(EXTRACT));
+        const elements = [];
+        const formMap = new Map();
+        for (const item of raw) {
+            const role = item.attrs.role ?? null;
+            const element = {
+                tag: item.tag,
+                role,
+                text: item.text,
+                kind: classify(item.tag, role),
+                candidates: rankCandidates(item.attrs, item.tag, item.text),
+            };
+            if (item.tag === 'form') {
+                const index = Array.from(formMap.keys()).length;
+                formMap.set(index, { candidates: element.candidates, fields: [], submit: null });
+                continue;
+            }
+            const form = item.formIndex >= 0 ? formMap.get(item.formIndex) : undefined;
+            if (form) {
+                if (item.isSubmit && !form.submit)
+                    form.submit = element;
+                else if (element.kind === 'field')
+                    form.fields.push(element);
+                else
+                    elements.push(element);
+            }
+            else {
+                elements.push(element);
+            }
+        }
+        let viewPath;
+        try {
+            viewPath = new URL(opts.url).pathname;
+        }
+        catch {
+            viewPath = undefined;
+        }
+        return {
+            source: 'browser',
+            available: true,
+            url: opts.url,
+            viewPath,
+            elements,
+            forms: Array.from(formMap.values()),
+        };
+    }
+    catch (err) {
+        // A navigation failure is a finding, not a crash. The same rule the soak
+        // and the integration verifier follow: report it and let the caller act.
+        return {
+            source: 'browser',
+            available: false,
+            url: opts.url,
+            elements: [],
+            forms: [],
+            note: `The page could not be inspected: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    finally {
+        try {
+            await browser.close();
+        }
+        catch {
+            /* closing a browser that already died is not a failure worth reporting */
+        }
+    }
+}

package/dist/manifest.d.ts

@@ -81,12 +81,24 @@ export declare function planManifest(client: AppilotClient, manifest: AppManifes
  * the token is unobtainable without the plan call and changes with the
  * manifest.
  */
-export declare function applyManifest(client: AppilotClient, manifest: AppManifest, options: {
+export interface ApplyManifestOptions {
     planToken: string;
     mode?: 'merge' | 'replace';
     expectedCurrentHash?: string;
     allowUnhealthy?: boolean;
-}): Promise<{
+    /**
+     * The refusal to raise when the caller may not provision, or null/undefined
+     * when it may.
+     *
+     * Set by the tool layer from the connection's grant. The apply then proceeds
+     * whenever the provisioning half changes nothing, which is the ordinary case
+     * in CI: the app, its domains and its keys were created once by a person and
+     * every run after that only syncs configuration. Demanding provision:write
+     * for that run contradicted the reason the two scopes are separate.
+     */
+    provisionRefusal?: string | null;
+}
+export declare function applyManifest(client: AppilotClient, manifest: AppManifest, options: ApplyManifestOptions): Promise<{
     provisioning: ProvisionAppResponse;
     config?: unknown;
     notes: string[];

package/dist/manifest.js

@@ -106,21 +106,43 @@ export async function planManifest(client, manifest, resolveAppId) {
     }
     return { planToken: manifestDigest(manifest), provisioning, config, notes };
 }
-/**
- * Apply a previously planned manifest.
- *
- * `planToken` must match the manifest being applied. This is the structural
- * version of "always dry-run first": the guidance cannot be skipped, because
- * the token is unobtainable without the plan call and changes with the
- * manifest.
- */
+/** What the provisioning half of this manifest would change, in plain words. */
+function provisioningChanges(preview) {
+    const changes = [];
+    if (preview.app.action !== 'reused')
+        changes.push(`the app "${preview.app.name}" (${preview.app.action})`);
+    for (const domain of preview.domains) {
+        if (domain.action !== 'reused')
+            changes.push(`the domain ${domain.domain} (${domain.action})`);
+    }
+    if (preview.widgetKey && preview.widgetKey.action !== 'reused') {
+        changes.push(`a widget key (${preview.widgetKey.action})`);
+    }
+    return changes;
+}
 export async function applyManifest(client, manifest, options) {
     const expected = manifestDigest(manifest);
     if (options.planToken !== expected) {
         throw new Error('planToken does not match this manifest. Run plan_manifest on the exact manifest you intend to apply, then pass the planToken it returns. A mismatch means the manifest changed after it was previewed.');
     }
     const notes = [];
-    const provisioning = await client.provisionApp(provisionRequest(manifest, false));
+    // Ask what provisioning would do before deciding whether it may. The dry run
+    // is the same call with `dryRun: true`, so this costs one request and turns
+    // "this manifest needs provision:write" from a property of the tool into a
+    // property of the manifest in front of it.
+    const preview = await client.provisionApp(provisionRequest(manifest, true));
+    const changes = provisioningChanges(preview);
+    if (changes.length > 0 && options.provisionRefusal) {
+        throw new Error(`${options.provisionRefusal}\nThis manifest would change ${changes.join(', ')}, so the apply cannot proceed without it. A manifest whose app, domains and keys already exist applies with config:write alone.`);
+    }
+    let provisioning;
+    if (changes.length === 0) {
+        provisioning = preview;
+        notes.push('Provisioning wrote nothing: the app, its domains and its keys already matched the manifest, so this apply needed only config:write. The provisioning block below is the preview, which is why it reports dryRun true.');
+    }
+    else {
+        provisioning = await client.provisionApp(provisionRequest(manifest, false));
+    }
     let config;
     if (manifest.config) {
         const appId = provisioning.app.id;

package/dist/public-marketplace/.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+	"name": "appilot",
+	"owner": {
+		"name": "Appilot",
+		"url": "https://appilot.space"
+	},
+	"metadata": {
+		"description": "Appilot agent tooling: skills and MCP servers that configure and operate Appilot apps.",
+		"version": "0.3.0"
+	},
+	"plugins": [
+		{
+			"name": "app-configurator",
+			"source": "./plugins/app-configurator",
+			"description": "Set up, configure, audit, repair, back up, restore and verify an Appilot app: provision the app, its domains and its widget key, scaffold the host integration, and keep the content model correct against the config health contract. Bundles the app-configurator skill and the Appilot MCP server (cloud or on-premise).",
+			"version": "0.3.0",
+			"strict": false
+		}
+	]
+}

package/dist/public-marketplace/README.md

@@ -0,0 +1,23 @@
+# Appilot plugins
+
+The Claude Code marketplace for the Appilot **app-configurator** plugin: the
+`app-configurator` skill plus the Appilot MCP server, which reads, validates,
+fixes and provisions an Appilot app.
+
+```
+/plugin marketplace add appilot/appilot-plugins
+/plugin install app-configurator@appilot
+```
+
+The plugin asks for your instance URL and a scoped service token from the
+Backoffice, under Service tokens.
+
+Other ways in, for clients that are not Claude Code: `npx -y appilot-mcp` plus
+`appilot-mcp install-skill --codex` (or `--cursor`, `--gemini`), the hosted
+endpoint at https://mcp.appilot.space/mcp for ChatGPT and claude.ai, and the
+Claude Desktop bundle at https://downloads.appilot.space/claude-desktop.
+
+Docs: https://docs.appilot.space/docs/developers/configure-with-ai/overview
+
+Built from appilot-mcp 0.3.0. Do not edit here; this tree is generated by
+`pnpm -C packages/tools/appilot-mcp build:marketplace` in the Appilot monorepo.

package/dist/public-marketplace/plugins/app-configurator/.claude-plugin/plugin.json

@@ -0,0 +1,43 @@
+{
+  "name": "app-configurator",
+  "version": "0.3.0",
+  "description": "Set up, configure, audit, repair, back up, restore, and verify an Appilot app: provision the app, its domains and widget key, scaffold the host integration, and keep the content model correct. Uses the Appilot MCP server and the app-configurator skill.",
+  "author": {
+    "name": "Appilot",
+    "url": "https://appilot.space"
+  },
+  "homepage": "https://docs.appilot.space/docs/developers/configure-with-ai/overview",
+  "skills": "./skills/",
+  "mcpServers": {
+    "appilot": {
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/dist/index.bundle.js"
+      ],
+      "env": {
+        "APPILOT_BASE_URL": "${user_config.base_url}",
+        "APPILOT_PAT": "${user_config.pat}",
+        "APPILOT_APP_ID": "${user_config.app_id}"
+      }
+    }
+  },
+  "userConfig": {
+    "base_url": {
+      "type": "string",
+      "title": "Appilot backend URL",
+      "description": "Cloud or on-premise Appilot backend URL.",
+      "required": true
+    },
+    "pat": {
+      "type": "string",
+      "title": "Appilot service token",
+      "description": "Scoped appilot_pat service token. config:read for audits, config:write for changes, provision:write to create apps, domains, and widget keys.",
+      "sensitive": true
+    },
+    "app_id": {
+      "type": "string",
+      "title": "Default Appilot app ID",
+      "description": "Optional default app ID used when a tool call does not provide one."
+    }
+  }
+}