appilot-mcp 0.0.1 → 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,43 @@
+{
+  "name": "app-configurator",
+  "version": "0.1.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."
+    }
+  }
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,37 @@
+{
+  "name": "app-configurator",
+  "version": "0.1.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",
+  "license": "ISC",
+  "keywords": [
+    "appilot",
+    "mcp",
+    "agent-skill",
+    "configuration"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Appilot Configurator",
+    "shortDescription": "Configure and validate Appilot apps with AI",
+    "longDescription": "Connect an AI agent to an Appilot instance to inspect, validate, repair, back up, restore, clone, and live-test its content-model configuration.",
+    "developerName": "Appilot",
+    "category": "Engineering",
+    "capabilities": [
+      "Interactive",
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://appilot.space",
+    "defaultPrompt": [
+      "Audit my Appilot app configuration",
+      "Fix the critical Appilot config findings",
+      "Back up and validate my Appilot app"
+    ]
+  }
+}

package/.mcp.json

@@ -0,0 +1,19 @@
+{
+  "mcpServers": {
+    "appilot": {
+      "command": "node",
+      "args": [
+        "./dist/index.bundle.js"
+      ],
+      "cwd": ".",
+      "env_vars": [
+        "APPILOT_BASE_URL",
+        "APPILOT_PAT",
+        "APPILOT_APP_ID",
+        "APPILOT_SOAK_STORAGE_STATE"
+      ],
+      "startup_timeout_sec": 10,
+      "tool_timeout_sec": 60
+    }
+  }
+}

package/README.md

@@ -1,11 +1,273 @@
 # appilot-mcp
 
-This version is a name reservation, not a working package. It contains no code.
+MCP server that lets an AI agent **read, validate, fix, and soak** an Appilot
+app's content-model configuration (Views, Controls, Forms, Action Plans,
+Knowledge, Zones, Tools) against the **config health contract**.
 
-The published package will hold the MCP server that lets a coding agent configure an Appilot app.
+It is the tool surface behind the `app-configurator` skill. The skill is the
+instructions; this server is what actually touches your instance.
 
-Appilot adds intelligence to any web app: its AI helps people operate the app and
-act on their behalf, shipping as a browser extension or an embeddable widget.
-See https://appilot.space.
+## Why
 
-Maintained by BetterKnow GmbH.
+Hand-authored app config drifts silently: a plan that opens an input but never
+submits, an auto-generated selector like `#nc-vue-30`, half-translated labels, a
+knowledge article that is really a procedure. This server encodes the contract
+those failures violate and checks it locally (no round-trip, air-gapped-safe)
+and against the live instance.
+
+## Cloud or on-premise
+
+Endpoint-agnostic by design. The same binary talks to a cloud tenant or an
+on-premise / sovereign instance purely by pointing `APPILOT_BASE_URL` at it. The
+static gate runs locally from `appilot-shared`, so it works with no network.
+
+## Two transports, one tool surface
+
+The same tools serve two shapes, and which one you need is decided by the client,
+not by preference.
+
+| Transport | Who launches it | Credential | Clients |
+|-----------|-----------------|------------|---------|
+| **stdio** (default) | The client, as a local child process | `APPILOT_PAT` in the process environment | Claude Code, Codex (CLI, IDE, app), Claude Desktop, Cursor, Antigravity |
+| **HTTP** (`--http`) | You, as a deployed service | The caller's own service token, collected once through OAuth | ChatGPT, claude.ai, and any remote MCP client |
+
+ChatGPT and claude.ai cannot start a process on your machine, and neither offers
+a field for pasting an API key: they connect to a URL and authenticate with
+OAuth. That is what HTTP mode is for. See
+[Remote deployment](#remote-deployment).
+
+## Configuration
+
+| Env | Required | Meaning |
+|-----|----------|---------|
+| `APPILOT_BASE_URL` | yes | Backend URL, e.g. `https://api.appilot.space` or `http://localhost:6001` |
+| `APPILOT_PAT` | for writes / server echo | A scoped service token (`appilot_pat_…`), minted in the Backoffice (admin → service tokens). `config:read` to read/validate, `config:write` to apply. |
+| `APPILOT_APP_ID` | optional | Default app id for tools that omit one |
+| `APPILOT_SOAK_STORAGE_STATE` | optional | Path to a Playwright `storageState` JSON for an authenticated site session (soak) |
+
+HTTP mode reads a different profile. It holds no Appilot credential of its own,
+because each caller brings theirs.
+
+| Env | Required | Meaning |
+|-----|----------|---------|
+| `APPILOT_BASE_URL` | yes | The one instance this deployment fronts. Never client-supplied: a caller-chosen URL would make the service an SSRF relay. |
+| `APPILOT_MCP_PUBLIC_URL` | yes | The public origin clients reach, e.g. `https://mcp.appilot.space`. OAuth metadata and redirects are absolute. |
+| `APPILOT_MCP_OAUTH_SECRET` | yes | At least 32 characters (`openssl rand -base64 32`). Everything the authorization server issues is sealed with it, so rotating it disconnects every client. |
+| `PORT` | no | Defaults to 8080. Cloud Run supplies it. |
+| `APPILOT_MCP_ALLOWED_HOSTS` | no | Extra `Host` values to accept, comma separated, for a proxy or a platform-assigned hostname. The public origin is always accepted. |
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `capabilities` | Version + migration level + schema versions of the connected instance (negotiate before configuring) |
+| `read_config` | Normalized snapshot of an app's content model |
+| `validate_config` | Severity-ranked findings against the health contract (local + server echo) |
+| `update_action_plan` / `update_control` / `update_knowledge` | Guarded writes (server re-validates the trust boundary) |
+| `export_config` / `import_config` | Whole-app ConfigBundle round trip, dry-run first, merge or replace |
+| `soak_selectors` | Headless-browser check that each control selector resolves on the live page (needs Playwright) |
+
+## Distribution artifacts
+
+One package carries a tool-neutral implementation plus thin discovery adapters:
+
+| Artifact | Consumers |
+|----------|-----------|
+| `skills/app-configurator/SKILL.md` | Open Agent Skills clients, including Codex, Claude Code, Cursor, and Antigravity |
+| `.mcp.json` | Codex plugin MCP declaration |
+| `.codex-plugin/plugin.json` | Codex plugin |
+| `.claude-plugin/plugin.json` | Claude Code plugin |
+| `mcpb/manifest.json` | Claude Desktop bundle manifest, packed by `pnpm build:mcpb` |
+| `Dockerfile` | The remote HTTP service |
+| `dist/index.bundle.js` | Self-contained Node.js MCP server, both transports |
+
+`pnpm pack` runs the build and includes all of these artifacts in the package.
+The server can initialize and expose its tools before connection settings are
+provided. Live tool calls return a clear configuration error until
+`APPILOT_BASE_URL` is set.
+
+## Install from this repository
+
+Build the self-contained server first:
+
+```bash
+pnpm -C packages/tools/appilot-mcp build
+```
+
+### Codex
+
+The repository is a Codex marketplace:
+
+```bash
+codex plugin marketplace add /absolute/path/to/app-pilot
+codex plugin add app-configurator@appilot
+```
+
+The plugin installs both the skill and MCP server globally. Start a new Codex
+task after installation so the new tool surface is loaded.
+
+### Claude Code
+
+Add the repository marketplace and install `app-configurator@appilot`. Claude's
+plugin settings prompt for the backend URL, service token, and optional app ID.
+The token is declared sensitive so Claude stores it in secure credential
+storage.
+
+### Claude Desktop
+
+Build the double-clickable bundle and open it:
+
+```bash
+pnpm -C packages/tools/appilot-mcp build
+pnpm -C packages/tools/appilot-mcp build:mcpb
+open packages/tools/appilot-mcp/dist/appilot-configurator.mcpb
+```
+
+Desktop asks for the backend URL and the service token, storing the token in the
+OS keychain. The bundle carries the server and its manifest and nothing else, so
+it installs on a machine with no Node toolchain and no network.
+
+### ChatGPT and claude.ai
+
+Neither can launch a local process, so both connect to a deployed HTTP endpoint.
+Once one is running (see [Remote deployment](#remote-deployment)):
+
+- **ChatGPT**: Settings, Apps, Advanced settings, turn on Developer mode, then
+  add a connector pointing at `https://<your-host>/mcp` with OAuth. The
+  authorization step asks for a service token, once.
+- **claude.ai**: Settings, Connectors, Add custom connector, same URL.
+- **Codex** can use the remote endpoint too, if you prefer one shared deployment
+  over a local process: add the URL to `~/.codex/config.toml` and run
+  `codex mcp login appilot`.
+
+To reach a private instance from ChatGPT without exposing an endpoint at all,
+run OpenAI's Secure MCP Tunnel against the local stdio server instead. The
+tunnel client makes an outbound connection from inside your network, so the
+instance needs no public listener.
+
+### Cursor
+
+Copy `skills/app-configurator` to `~/.cursor/skills/app-configurator`, then add
+the server to `~/.cursor/mcp.json`.
+
+### Antigravity
+
+Copy `skills/app-configurator` to the applicable global skills directory:
+
+- Antigravity IDE: `~/.gemini/config/skills/app-configurator`
+- Antigravity CLI: `~/.gemini/antigravity-cli/skills/app-configurator`
+
+Register the stdio server in `~/.gemini/config/mcp_config.json`.
+
+### Any stdio MCP client
+
+Point the client at the built bundle:
+
+```json
+{
+  "mcpServers": {
+    "appilot": {
+      "command": "node",
+      "args": ["/absolute/path/to/appilot-mcp/dist/index.bundle.js"],
+      "env": {
+        "APPILOT_BASE_URL": "https://api.appilot.space",
+        "APPILOT_PAT": "appilot_pat_...",
+        "APPILOT_APP_ID": "123"
+      }
+    }
+  }
+}
+```
+
+For registry-backed distribution, replace `node` and the bundle path with
+`pnpm dlx appilot-mcp` after the package is published.
+
+Do not commit service tokens. Use the MCP client's secure secret storage or
+environment forwarding when available.
+
+## Remote deployment
+
+HTTP mode is a small stateless web service. It stores nothing: no user table, no
+client registry, no token store. The OAuth authorization server seals its own
+state into the artifacts it issues (see `src/remote/tokens.ts`), so a second
+instance behaves exactly like the first and a cold start loses nothing.
+
+What it serves:
+
+| Path | Purpose |
+|------|---------|
+| `POST /mcp` | The MCP endpoint, Streamable HTTP, bearer required |
+| `/.well-known/oauth-protected-resource/mcp` | Points a client at the authorization server |
+| `/.well-known/oauth-authorization-server` | Metadata, PKCE with S256, dynamic registration |
+| `/authorize`, `/token`, `/register` | The OAuth 2.1 flow |
+| `/consent` | The one page a person sees, where they paste a service token |
+| `/health` (also `/healthz` off Cloud Run) | Liveness |
+
+Run it:
+
+```bash
+pnpm -C packages/tools/appilot-mcp build
+docker build -t appilot-mcp packages/tools/appilot-mcp
+docker run -p 8080:8080 \
+  -e APPILOT_BASE_URL=https://api.appilot.space \
+  -e APPILOT_MCP_PUBLIC_URL=https://mcp.appilot.space \
+  -e APPILOT_MCP_OAUTH_SECRET="$(openssl rand -base64 32)" \
+  appilot-mcp
+```
+
+On Cloud Run, which is where the backend already runs, use the script rather
+than a hand-typed `gcloud` line: it creates the signing secret, grants the
+runtime service account access to it, and handles the two-pass problem where the
+service URL only exists after the first deploy while `APPILOT_MCP_PUBLIC_URL`
+has to name that exact origin.
+
+```bash
+packages/tools/appilot-mcp/scripts/deploy-cloud-run.sh
+```
+
+It deploys unauthenticated on purpose: the service does its own OAuth, and
+platform-level IAM in front of it would block the discovery endpoints a client
+has to read before it can authenticate at all. The upload carries the
+`Dockerfile` and the one bundle, which is what `.gcloudignore` is for. Mapping
+`mcp.appilot.space` onto the service is the last step, and the script prints it.
+
+### How access works
+
+The service never sees an Appilot password and never mints a credential. A
+person creates a scoped service token in the Backoffice, pastes it once on the
+consent screen, and the service checks it against the instance
+(`GET /config/whoami`) before granting anything. The granted scopes are the
+intersection of what the client asked for and what that token actually carries,
+so a `config:read` token cannot be talked into write access. The token is then
+sealed inside the OAuth tokens the client holds; the client never sees it.
+
+Revocation happens where the token was minted: revoke it in the Backoffice and
+every connection built on it stops working on the next call. Rotating
+`APPILOT_MCP_OAUTH_SECRET` invalidates every issued token at once.
+
+The soak tool is deliberately unavailable in this mode: driving a real browser
+belongs on the operator's machine over stdio, not in a shared web service.
+
+## Develop
+
+```bash
+pnpm -C packages/tools/appilot-mcp build       # tsc + the self-contained bundle
+pnpm -C packages/tools/appilot-mcp build:mcpb  # the Claude Desktop bundle
+pnpm -C packages/tools/appilot-mcp test        # vitest: contract, OAuth, HTTP end to end
+pnpm -C packages/tools/appilot-mcp typecheck
+```
+
+To exercise HTTP mode locally, point it at a dev backend and use a localhost
+public origin, which is the one case where plaintext is accepted:
+
+```bash
+APPILOT_BASE_URL=http://localhost:6001 \
+APPILOT_MCP_PUBLIC_URL=http://localhost:8080 \
+APPILOT_MCP_OAUTH_SECRET="$(openssl rand -base64 32)" \
+node packages/tools/appilot-mcp/dist/index.bundle.js --http
+```
+
+Live DOM soak needs Playwright: add it with pnpm and install Chromium.
+
+See `docs/architecture/appilot-mcp.md` (server) and
+`docs/content-model/config-health-contract.md` (the contract it enforces).

package/dist/client.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Thin HTTP client over the Appilot config API. Adds service-token auth, reads
+ * the content-model entities, and normalizes them into a `ConfigSnapshot` for
+ * the health contract. Also exposes the non-persisting server-side plan
+ * validation echo.
+ *
+ * Translation shapes vary by instance version (base + `*_i18n` map on newer
+ * builds, per-locale side-table rows on others), so the normalizers below read
+ * defensively and never throw on a missing field. Field mapping is verified
+ * against a live instance in the plan's Phase F.
+ */
+import type { AppilotConnection } from './config.js';
+import type { ConfigSnapshot } from './contract/types.js';
+export interface Capabilities {
+    appVersion: string;
+    migrations: {
+        count: number;
+        latest: string | null;
+        latestExecutedAt: string | null;
+    } | null;
+    schemaVersions: Record<string, string>;
+    configurableEntities: string[];
+    /** Absent on instances that predate config portability; clients must refuse
+     *  to import rather than guess. */
+    configPortability?: {
+        bundleFormatVersion: string;
+        maxImportBytes: number;
+    };
+}
+/** Mirrors the backend's ProvisioningService result. Secrets appear once. */
+export interface ProvisionAppResponse {
+    dryRun: boolean;
+    app: {
+        id: number | null;
+        name: string;
+        action: 'created' | 'reused' | 'updated';
+    };
+    domains: Array<{
+        id: number | null;
+        domain: string;
+        action: 'created' | 'reused' | 'updated';
+        verification_status: string;
+        dns_record_name?: string;
+        dns_record_value?: string;
+    }>;
+    widgetKey?: {
+        id: number | null;
+        action: 'created' | 'reused' | 'updated';
+        keyPrefix?: string;
+        rawKey?: string;
+        rawSecret?: string;
+    };
+    integration: {
+        apiUrl: string | null;
+        scriptTag: string;
+        bootSnippet: string;
+        tokenEndpointHint: string;
+    };
+}
+export interface ProvisionAppRequest {
+    app: {
+        name: string;
+        description?: string;
+    };
+    domains?: Array<{
+        domain: string;
+        name?: string;
+        default_language?: string | null;
+        configured_languages?: string[];
+    }>;
+    widgetKey?: {
+        name?: string;
+        allowedDomains?: string[];
+        isTest?: boolean;
+    };
+    dryRun?: boolean;
+}
+export interface ProvisionedAppSummary {
+    id: number;
+    name: string;
+    domains: Array<{
+        id: number;
+        domain: string;
+        verification_status: string;
+    }>;
+}
+export declare class AppilotApiError extends Error {
+    readonly status: number;
+    readonly body?: unknown;
+    constructor(message: string, status: number, body?: unknown);
+}
+export declare class AppilotClient {
+    private readonly conn;
+    constructor(conn: AppilotConnection);
+    private request;
+    getCapabilities(): Promise<Capabilities>;
+    getHealth(): Promise<{
+        status: string;
+        version?: string;
+    }>;
+    listActionPlans(appId: number): Promise<Record<string, unknown>[]>;
+    listControls(appId: number): Promise<Record<string, unknown>[]>;
+    listForms(appId: number): Promise<Record<string, unknown>[]>;
+    listViews(appId: number): Promise<Record<string, unknown>[]>;
+    listKnowledge(appId: number): Promise<Record<string, unknown>[]>;
+    updateActionPlan(id: string, body: unknown): Promise<unknown>;
+    updateControl(id: string, body: unknown): Promise<unknown>;
+    createControl(body: unknown): Promise<unknown>;
+    updateForm(id: string, body: unknown): Promise<unknown>;
+    updateKnowledge(id: string, body: unknown): Promise<unknown>;
+    /** Server-side non-persisting plan validation (echoes the runtime trust boundary). */
+    validatePlan(appId: number, sections: unknown, formValues: unknown): Promise<{
+        ok: boolean;
+        errors: string[];
+    }>;
+    listProvisioned(): Promise<ProvisionedAppSummary[]>;
+    provisionApp(body: ProvisionAppRequest): Promise<ProvisionAppResponse>;
+    /**
+     * Domain check: does this hostname resolve to a tenant? Public endpoint, so
+     * it answers even for a read-only caller, which is what makes it usable as
+     * the first probe of `verify_integration`.
+     */
+    checkDomain(domain: string): Promise<Record<string, unknown>>;
+    /** Who this credential is: org, app narrowing, scopes. Never a secret. */
+    whoami(): Promise<Record<string, unknown>>;
+    exportConfig(appId: number): Promise<import('appilot-shared/config-bundle').ConfigBundle>;
+    importConfig(appId: number, body: {
+        mode: 'merge' | 'replace';
+        dryRun?: boolean;
+        bundle: unknown;
+        expectedCurrentHash?: string;
+        allowUnhealthy?: boolean;
+    }): Promise<import('appilot-shared/config-bundle').ImportDiff>;
+    /**
+     * Read the app's content-model config and normalize it into a ConfigSnapshot.
+     * `expectedLocales` defaults to de/en/es (Appilot's trilingual baseline) but
+     * can be overridden per call once the domain's configured_languages are known.
+     */
+    buildSnapshot(appId: number, expectedLocales?: string[]): Promise<ConfigSnapshot>;
+}