appilot-mcp 0.0.1 → 0.1.0

package/dist/client.js

@@ -0,0 +1,252 @@
+/**
+ * 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.
+ */
+export class AppilotApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'AppilotApiError';
+    }
+}
+/** Merge a base value + an `_i18n` override map into a single LocalizedText. */
+function fromBaseAndI18n(base, i18n) {
+    const out = {};
+    if (i18n && typeof i18n === 'object') {
+        for (const [k, v] of Object.entries(i18n)) {
+            if (typeof v === 'string')
+                out[k] = v;
+        }
+    }
+    if (typeof base === 'string' && base.length) {
+        // A base string has no locale of its own; expose it under a synthetic
+        // 'base' key AND leave declared locales as-is. The contract checks named
+        // locales, so we only surface base when nothing else exists.
+        if (Object.keys(out).length === 0)
+            out.base = base;
+    }
+    return out;
+}
+/** Build a LocalizedText from a `translations` array of `{ locale/language, [field] }`. */
+function fromTranslationRows(rows, field) {
+    const out = {};
+    if (Array.isArray(rows)) {
+        for (const row of rows) {
+            const locale = (row.locale ?? row.language);
+            const value = row[field];
+            if (locale && typeof value === 'string')
+                out[locale] = value;
+        }
+    }
+    return out;
+}
+/** Resolve a translatable field across the shapes an instance may return. */
+function localized(entity, field) {
+    const rows = entity.translations;
+    if (Array.isArray(rows) && rows.length)
+        return fromTranslationRows(rows, field);
+    return fromBaseAndI18n(entity[field], entity[`${field}_i18n`]);
+}
+export class AppilotClient {
+    conn;
+    constructor(conn) {
+        this.conn = conn;
+    }
+    async request(path, init = {}) {
+        if (!this.conn.baseUrl) {
+            throw new Error('APPILOT_BASE_URL is not configured. Set it in the MCP client environment ' +
+                '(for example, https://api.appilot.space or http://localhost:6001), then restart the client.');
+        }
+        const headers = {
+            Accept: 'application/json',
+            ...(init.body ? { 'Content-Type': 'application/json' } : {}),
+            ...(this.conn.token ? { Authorization: `Bearer ${this.conn.token}` } : {}),
+            ...init.headers,
+        };
+        const res = await fetch(`${this.conn.baseUrl}${path}`, { ...init, headers });
+        const text = await res.text();
+        const body = text ? safeJson(text) : undefined;
+        if (!res.ok) {
+            const message = body?.error ?? `${res.status} ${res.statusText}`;
+            throw new AppilotApiError(`${init.method ?? 'GET'} ${path} failed: ${message}`, res.status, body);
+        }
+        return body;
+    }
+    getCapabilities() {
+        return this.request('/config/capabilities');
+    }
+    getHealth() {
+        return this.request('/health');
+    }
+    // -- reads --------------------------------------------------------------
+    listActionPlans(appId) {
+        return this.request(`/domain/action-plans?app_id=${appId}`);
+    }
+    listControls(appId) {
+        return this.request(`/domain/controls?app_id=${appId}`);
+    }
+    listForms(appId) {
+        return this.request(`/domain/forms?app_id=${appId}&resolveFields=true`);
+    }
+    listViews(appId) {
+        return this.request(`/views?app_id=${appId}`);
+    }
+    listKnowledge(appId) {
+        return this.request(`/knowledge/content?app_id=${appId}`);
+    }
+    // -- writes -------------------------------------------------------------
+    updateActionPlan(id, body) {
+        return this.request(`/domain/action-plans/${id}`, { method: 'PUT', body: JSON.stringify(body) });
+    }
+    updateControl(id, body) {
+        return this.request(`/domain/controls/${id}`, { method: 'PUT', body: JSON.stringify(body) });
+    }
+    createControl(body) {
+        return this.request(`/domain/controls`, { method: 'POST', body: JSON.stringify(body) });
+    }
+    updateForm(id, body) {
+        return this.request(`/domain/forms/${id}`, { method: 'PUT', body: JSON.stringify(body) });
+    }
+    updateKnowledge(id, body) {
+        return this.request(`/knowledge/content/${id}`, { method: 'PUT', body: JSON.stringify(body) });
+    }
+    /** Server-side non-persisting plan validation (echoes the runtime trust boundary). */
+    validatePlan(appId, sections, formValues) {
+        return this.request('/domain/action-plans/validate', {
+            method: 'POST',
+            body: JSON.stringify({ app_id: appId, sections, form_values: formValues }),
+        });
+    }
+    // -- provisioning (plan/external-developer-surface) ---------------------
+    // Requires a service token holding `provision:write` (or an org admin JWT).
+    // Both calls are idempotent and dry-runnable server-side, so `plan` before
+    // `apply` is a property of the endpoint rather than a request in prose.
+    listProvisioned() {
+        return this.request('/provision/apps');
+    }
+    provisionApp(body) {
+        return this.request('/provision/app', { method: 'POST', body: JSON.stringify(body) });
+    }
+    /**
+     * 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) {
+        return this.request(`/domain/check?domain=${encodeURIComponent(domain)}`);
+    }
+    /** Who this credential is: org, app narrowing, scopes. Never a secret. */
+    whoami() {
+        return this.request('/config/whoami');
+    }
+    // -- config portability (docs/architecture/config-portability.md) -------
+    // exportConfig is the ROUND-TRIP view (the canonical ConfigBundle) as
+    // opposed to buildSnapshot, which is the agent's REASONING view; the two
+    // are deliberately distinct shapes.
+    exportConfig(appId) {
+        return this.request(`/config/export?appId=${appId}`);
+    }
+    importConfig(appId, body) {
+        return this.request('/config/import', {
+            method: 'POST',
+            body: JSON.stringify({ appId, ...body }),
+        });
+    }
+    /**
+     * 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.
+     */
+    async buildSnapshot(appId, expectedLocales = ['de', 'en', 'es']) {
+        const [plans, controls, forms, views, knowledge] = await Promise.all([
+            this.listActionPlans(appId).catch(() => []),
+            this.listControls(appId).catch(() => []),
+            this.listForms(appId).catch(() => []),
+            this.listViews(appId).catch(() => []),
+            this.listKnowledge(appId).catch(() => []),
+        ]);
+        return {
+            expectedLocales,
+            views: views.map(mapView),
+            controls: controls.map(mapControl),
+            forms: forms.map(mapForm),
+            zones: [], // zones read per-domain; wired in Phase F once domain ids are resolved.
+            actionPlans: plans.map(mapActionPlan),
+            knowledge: knowledge.map(mapKnowledge),
+        };
+    }
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function mapView(v) {
+    return { slug: v.slug, path: String(v.path ?? v.view_path ?? ''), name: localized(v, 'name') };
+}
+function mapControl(c) {
+    return {
+        semantic_id: String(c.semantic_id ?? c.name ?? ''),
+        locator_type: String(c.locator_type ?? c.locator_strategy ?? ''),
+        locator: String(c.locator ?? c.locator_value ?? ''),
+        view_path: c.view_path ?? null,
+        scope: c.scope ?? null,
+    };
+}
+function mapForm(f) {
+    const fields = f.fields ?? [];
+    return {
+        semantic_id: String(f.semantic_id ?? ''),
+        field_ids: fields.map(fl => String(fl.semantic_id ?? fl.control_id ?? '')).filter(Boolean),
+        submit_control_id: f.submit_control_semantic_id ?? f.submit_control_id ?? null,
+        entry_control_id: f.entry_control_semantic_id ?? f.entry_control_id ?? null,
+    };
+}
+function mapActionPlan(p) {
+    const sections = p.sections ?? [];
+    return {
+        semantic_id: String(p.semantic_id ?? ''),
+        sections,
+        form_values: p.form_values ?? {},
+        name: localized(p, 'name'),
+        description: localized(p, 'description'),
+        step_narratives: p.step_narratives_i18n ?? undefined,
+        is_active: p.is_active !== false,
+    };
+}
+function mapKnowledge(k) {
+    // A knowledge article read may return either a single localized row or a group
+    // of language rows. Normalize both into a bodies[] list.
+    const bodies = [];
+    const rows = (k.translations ?? k.languages ?? k.contents);
+    if (Array.isArray(rows) && rows.length) {
+        for (const row of rows) {
+            bodies.push({
+                language: String(row.language ?? row.locale ?? ''),
+                text: String(row.general_info ?? row.description ?? row.body ?? row.title ?? ''),
+                title: row.title,
+            });
+        }
+    }
+    else {
+        bodies.push({
+            language: String(k.language ?? ''),
+            text: String(k.general_info ?? k.description ?? k.body ?? ''),
+            title: k.title,
+        });
+    }
+    return { id: k.article_id ?? k.id ?? '', scope: String(k.scope ?? ''), bodies };
+}

package/dist/config.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Connection profile for the Appilot MCP server.
+ *
+ * Endpoint-agnostic by design: the same server binary talks to a cloud tenant or
+ * an on-premise / sovereign instance purely by pointing APPILOT_BASE_URL at it.
+ * Auth is a scoped service token (appilot_pat_…); no token is needed for the
+ * public capabilities/health probes. Nothing here is hard-coded to a host.
+ */
+export interface AppilotConnection {
+    /** Base URL of the Appilot backend, e.g. https://api.appilot.space or http://localhost:6001. */
+    baseUrl?: string;
+    /** Scoped service token (appilot_pat_…). Optional for read-only capability probes. */
+    token?: string;
+    /** Default app id for tools that omit one. */
+    defaultAppId?: number;
+    /** Optional site session for the soak tool (see soak.ts). */
+    soakStorageStatePath?: string;
+    /**
+     * Which transport this server instance is serving.
+     *
+     * The tool surface is identical across both, by design. What differs is what
+     * a tool may put in its RESULT: the remote transport carries results into a
+     * third party's conversation (ChatGPT, claude.ai), where they are stored and
+     * summarized. A newly minted widget SECRET must not travel that way, so
+     * provisioning withholds it there and points at the Backoffice instead.
+     * Defaults to stdio, which is the operator's own machine.
+     */
+    transport?: 'stdio' | 'http';
+}
+export declare function loadConnection(env?: NodeJS.ProcessEnv): AppilotConnection;
+/** Which transport the process serves. Local stdio unless asked otherwise. */
+export type TransportMode = 'stdio' | 'http';
+export declare function resolveTransport(argv?: string[], env?: NodeJS.ProcessEnv): TransportMode;
+/**
+ * Settings for the remote (Streamable HTTP) deployment.
+ *
+ * The remote service holds NO Appilot credential of its own: every caller
+ * arrives with their own service token, wrapped in an OAuth access token. What
+ * it does hold is one signing/encryption secret, which is what makes the OAuth
+ * authorization server stateless (see remote/oauth.ts). A deployment therefore
+ * needs three things and no database.
+ */
+export interface RemoteConfig {
+    /** Port to listen on. Cloud Run supplies PORT. */
+    port: number;
+    /** Public origin the clients reach, e.g. https://mcp.appilot.space. */
+    publicUrl: URL;
+    /** Secret behind the stateless OAuth tokens. Rotating it logs every client out. */
+    secret: string;
+    /** Hosts accepted in the Host header (DNS-rebinding protection). */
+    allowedHosts: string[];
+    /** The single Appilot backend this deployment serves. Never client-supplied: a
+     *  caller-chosen base URL would turn the service into an SSRF relay. */
+    baseUrl: string;
+    /** Customer-facing docs root, published in the OAuth metadata a client reads
+     *  before it shows the consent screen. Configurable because the docs host
+     *  moves independently of the code that links to it. */
+    docsUrl: URL;
+}
+/** Where the docs live when a deployment does not say otherwise. */
+export declare const DEFAULT_DOCS_URL = "https://docs.appilot.space";
+export declare class RemoteConfigError extends Error {
+}
+export declare function loadRemoteConfig(env?: NodeJS.ProcessEnv): RemoteConfig;

package/dist/config.js

@@ -0,0 +1,78 @@
+/**
+ * Connection profile for the Appilot MCP server.
+ *
+ * Endpoint-agnostic by design: the same server binary talks to a cloud tenant or
+ * an on-premise / sovereign instance purely by pointing APPILOT_BASE_URL at it.
+ * Auth is a scoped service token (appilot_pat_…); no token is needed for the
+ * public capabilities/health probes. Nothing here is hard-coded to a host.
+ */
+function trimTrailingSlash(url) {
+    return url.replace(/\/+$/, '');
+}
+export function loadConnection(env = process.env) {
+    const baseUrl = env.APPILOT_BASE_URL?.trim();
+    const defaultAppId = env.APPILOT_APP_ID ? Number(env.APPILOT_APP_ID) : undefined;
+    return {
+        baseUrl: baseUrl ? trimTrailingSlash(baseUrl) : undefined,
+        token: env.APPILOT_PAT?.trim() || undefined,
+        defaultAppId: Number.isFinite(defaultAppId) ? defaultAppId : undefined,
+        soakStorageStatePath: env.APPILOT_SOAK_STORAGE_STATE?.trim() || undefined,
+    };
+}
+export function resolveTransport(argv = process.argv.slice(2), env = process.env) {
+    if (argv.includes('--http'))
+        return 'http';
+    return env.APPILOT_MCP_TRANSPORT?.trim() === 'http' ? 'http' : 'stdio';
+}
+/** Where the docs live when a deployment does not say otherwise. */
+export const DEFAULT_DOCS_URL = 'https://docs.appilot.space';
+export class RemoteConfigError extends Error {
+}
+export function loadRemoteConfig(env = process.env) {
+    const baseUrl = env.APPILOT_BASE_URL?.trim();
+    if (!baseUrl) {
+        throw new RemoteConfigError('APPILOT_BASE_URL is required in HTTP mode: it names the one Appilot backend this deployment serves.');
+    }
+    const rawPublic = env.APPILOT_MCP_PUBLIC_URL?.trim();
+    if (!rawPublic) {
+        throw new RemoteConfigError('APPILOT_MCP_PUBLIC_URL is required in HTTP mode (for example https://mcp.appilot.space). OAuth metadata and redirects are absolute, so the service must know its own public origin.');
+    }
+    let publicUrl;
+    try {
+        publicUrl = new URL(rawPublic);
+    }
+    catch {
+        throw new RemoteConfigError(`APPILOT_MCP_PUBLIC_URL is not a valid URL: ${rawPublic}`);
+    }
+    if (publicUrl.protocol !== 'https:' && publicUrl.hostname !== 'localhost' && publicUrl.hostname !== '127.0.0.1') {
+        throw new RemoteConfigError('APPILOT_MCP_PUBLIC_URL must use https (localhost excepted for development). OAuth 2.1 refuses plaintext issuers.');
+    }
+    const secret = env.APPILOT_MCP_OAUTH_SECRET?.trim();
+    if (!secret || secret.length < 32) {
+        throw new RemoteConfigError('APPILOT_MCP_OAUTH_SECRET is required in HTTP mode and must be at least 32 characters (openssl rand -base64 32).');
+    }
+    const port = Number(env.PORT ?? env.APPILOT_MCP_PORT ?? 8080);
+    if (!Number.isFinite(port) || port <= 0) {
+        throw new RemoteConfigError(`PORT is not a valid port number: ${env.PORT ?? env.APPILOT_MCP_PORT}`);
+    }
+    const extraHosts = (env.APPILOT_MCP_ALLOWED_HOSTS ?? '')
+        .split(',')
+        .map(h => h.trim())
+        .filter(Boolean);
+    const rawDocs = env.APPILOT_MCP_DOCS_URL?.trim() || DEFAULT_DOCS_URL;
+    let docsUrl;
+    try {
+        docsUrl = new URL(rawDocs);
+    }
+    catch {
+        throw new RemoteConfigError(`APPILOT_MCP_DOCS_URL is not a valid URL: ${rawDocs}`);
+    }
+    return {
+        port,
+        publicUrl,
+        secret,
+        allowedHosts: [publicUrl.host, ...extraHosts],
+        baseUrl: trimTrailingSlash(baseUrl),
+        docsUrl,
+    };
+}

package/dist/contract/bundleSnapshot.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Adapter: ConfigBundle entities -> ConfigSnapshot.
+ *
+ * Lets `runHealthContract` gate a portable bundle (the backend import path
+ * and the MCP import tool both use it) with the exact same lints that run
+ * over a live snapshot. Lives in the contract dir because it maps INTO the
+ * contract's `ConfigSnapshot` types; the bundle shape itself is owned by
+ * `appilot-shared/config-bundle`.
+ */
+import type { ConfigBundleEntities } from 'appilot-shared/config-bundle';
+import type { ConfigSnapshot } from './types.js';
+export declare function snapshotFromBundle(entities: ConfigBundleEntities, expectedLocales: string[]): ConfigSnapshot;

package/dist/contract/bundleSnapshot.js

@@ -0,0 +1,65 @@
+/** Collapse a bundle translations map into `{ locale -> value }` for one field. */
+function localizedField(translations, field) {
+    const out = {};
+    for (const [locale, fields] of Object.entries(translations)) {
+        const value = fields?.[field];
+        if (typeof value === 'string' && value.length)
+            out[locale] = value;
+    }
+    return out;
+}
+export function snapshotFromBundle(entities, expectedLocales) {
+    const views = entities.views.map(v => ({
+        slug: v.slug,
+        path: v.path,
+        name: localizedField(v.translations, 'name'),
+    }));
+    const controls = entities.controls.map(c => ({
+        semantic_id: c.semantic_id,
+        locator_type: c.locator_type,
+        locator: c.locator,
+        view_path: c.view_path,
+        scope: c.scope,
+    }));
+    // A form's fields are the controls declaring membership via `form`.
+    const fieldsByForm = new Map();
+    for (const c of entities.controls) {
+        if (!c.form)
+            continue;
+        (fieldsByForm.get(c.form.form) ?? fieldsByForm.set(c.form.form, []).get(c.form.form)).push(c.semantic_id);
+    }
+    const forms = entities.forms.map(f => ({
+        semantic_id: f.semantic_id,
+        field_ids: fieldsByForm.get(f.semantic_id) ?? [],
+        submit_control_id: f.submit_control,
+        entry_control_id: f.entry_control,
+    }));
+    const actionPlans = entities.action_plans.map(p => {
+        const step_narratives = {};
+        for (const [locale, t] of Object.entries(p.translations)) {
+            if (Array.isArray(t?.step_narratives)) {
+                step_narratives[locale] = t.step_narratives;
+            }
+        }
+        return {
+            semantic_id: p.semantic_id,
+            sections: p.sections,
+            form_values: p.form_values,
+            name: localizedField(p.translations, 'name'),
+            description: localizedField(p.translations, 'description'),
+            step_narratives: Object.keys(step_narratives).length ? step_narratives : undefined,
+            is_active: p.is_active,
+        };
+    });
+    const zones = entities.zones.map(z => ({ semantic_id: z.semantic_id }));
+    const knowledge = entities.knowledge_content.map(k => ({
+        id: k.group,
+        scope: k.scope,
+        bodies: k.bodies.map(b => ({
+            language: b.language ?? '',
+            text: String(b.general_info ?? b.description ?? b.title ?? ''),
+            title: b.title,
+        })),
+    }));
+    return { expectedLocales, views, controls, forms, zones, actionPlans, knowledge };
+}

package/dist/contract/healthContract.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The Appilot config health contract.
+ *
+ * A set of pure lints over a `ConfigSnapshot` that encode what a WELL-FORMED
+ * content-model configuration looks like. Every lint traces to a real failure
+ * mode observed when apps are hand-authored (see the BeKnow `create-task`
+ * audit). The marker + identifier checks REUSE the canonical validators from
+ * `appilot-shared` so the contract can never drift from the runtime:
+ *   - `validateActionPlanMarkers` (the same trust boundary the backend applies)
+ *   - `IDENTIFIER_KINDS` (the single source of truth for identifier shape)
+ *
+ * Contract docs: docs/content-model/config-health-contract.md.
+ */
+import type { ConfigSnapshot, HealthReport } from './types.js';
+/**
+ * Run the full config health contract over a snapshot. Findings are returned
+ * most-severe first, so the report reads like the manual audit.
+ */
+export declare function runHealthContract(snap: ConfigSnapshot): HealthReport;