appilot-mcp 0.2.1 → 0.4.0

package/dist/client.js

@@ -116,7 +116,8 @@ export class AppilotClient {
         const text = await res.text();
         const body = text ? safeJson(text) : undefined;
         if (!res.ok) {
-            throw new AppilotApiError(`${init.method ?? 'GET'} ${path} failed: ${describeError(body, res)}`, res.status, body);
+            const credential = res.status === 401 || res.status === 403 ? ` ${credentialAdvice(!!this.conn.token)}` : '';
+            throw new AppilotApiError(`${init.method ?? 'GET'} ${path} failed: ${describeError(body, res)}${credential}`, res.status, body);
         }
         return body;
     }
@@ -217,6 +218,16 @@ export class AppilotClient {
     listProvisioned() {
         return this.request('/provision/apps');
     }
+    /**
+     * The org's widget keys, prefixes only.
+     *
+     * A caller that cannot see the keys it already minted asks for another every
+     * run, and each one is a live credential.
+     */
+    async listWidgetKeys() {
+        const body = await this.request('/provision/widget-keys');
+        return Array.isArray(body?.widgetKeys) ? body.widgetKeys : [];
+    }
     provisionApp(body) {
         return this.request('/provision/app', { method: 'POST', body: JSON.stringify(body) });
     }
@@ -233,6 +244,21 @@ export class AppilotClient {
         const url = /^https?:\/\//i.test(domain) ? domain : `https://${domain}`;
         return this.request(`/domain/check?url=${encodeURIComponent(url)}`);
     }
+    /**
+     * The TXT record a domain needs, and where its verification stands.
+     *
+     * These two live on the apps router rather than under `/provision`, and that
+     * router authenticates an organization SESSION. A service token is refused
+     * there today, which is why `verify_domain` falls back to the provisioning
+     * dry run for the status and says plainly what it could not do.
+     */
+    domainVerification(domainId) {
+        return this.request(`/apps/domains/${domainId}/verification`);
+    }
+    /** Ask Appilot to look for the TXT record now. */
+    triggerDomainVerification(domainId) {
+        return this.request(`/apps/domains/${domainId}/verify`, { method: 'POST' });
+    }
     /** Who this credential is: org, app narrowing, scopes. Never a secret. */
     whoami() {
         return this.request('/config/whoami');
@@ -286,6 +312,17 @@ export class AppilotClient {
             read('knowledge', () => this.listKnowledge(appId), mapKnowledge),
             expectedLocales?.length ? Promise.resolve(expectedLocales) : this.resolveLocales(appId),
         ]);
+        // An empty knowledge list is the one read that can mean two things.
+        // `/knowledge/content` is an optional-auth route, so a missing or rejected
+        // bearer answers `200 []` instead of refusing, and from here that is
+        // indistinguishable from an app with no knowledge. Every knowledge lint
+        // then passes over a configuration nobody was allowed to look at, which is
+        // exactly the failure the `gaps` array exists to prevent.
+        if (knowledge.length === 0 && !gaps.some(g => g.entity === 'knowledge')) {
+            const refusal = await this.credentialRefusal();
+            if (refusal)
+                gaps.push({ entity: 'knowledge', reason: refusal });
+        }
         return {
             expectedLocales: locales,
             views,
@@ -298,6 +335,29 @@ export class AppilotClient {
             ...(gaps.length ? { gaps } : {}),
         };
     }
+    /**
+     * Why an empty read should not be believed, or null when the credential is
+     * fine and the app genuinely has nothing.
+     *
+     * Only a 401 or a 403 counts. An instance too old to answer `whoami` at all
+     * says nothing about the token, and reporting a gap on that would be a
+     * confident false alarm on every on-premise deployment behind cloud.
+     */
+    async credentialRefusal() {
+        if (!this.conn.token) {
+            return `No service token is set, so the knowledge read was anonymous and answered an empty list rather than refusing. ${credentialAdvice(false)}`;
+        }
+        try {
+            await this.whoami();
+            return null;
+        }
+        catch (err) {
+            if (err instanceof AppilotApiError && (err.status === 401 || err.status === 403)) {
+                return `The knowledge read returned nothing and the credential failed its own self-check, so the empty result is not evidence of an empty knowledge base. ${credentialAdvice(true)}`;
+            }
+            return null;
+        }
+    }
     /**
      * Which locales this app's configuration is expected to cover: the union of
      * its domains' configured languages. Falls back to the trilingual baseline
@@ -328,6 +388,19 @@ export class AppilotClient {
         return DEFAULT_EXPECTED_LOCALES;
     }
 }
+/**
+ * What to do about a 401 or a 403, in the same voice as the offline errors.
+ *
+ * "Access denied. Token required." is the first thing a new developer meets and
+ * it names nothing: not the variable to set, not the screen the token comes
+ * from, not the preset to choose. The `APPILOT_BASE_URL` message next door does
+ * name all three, and it is the standard this one had to reach.
+ */
+function credentialAdvice(hasToken) {
+    return hasToken
+        ? 'The credential was rejected. Check it in the Backoffice under Service tokens: it may be revoked, expired, or scoped to another app. A token narrowed to one app is refused on every other app in the organization.'
+        : 'No credential is set. Put a service token in APPILOT_PAT in the MCP client environment and restart the client. Mint one in the Backoffice under Service tokens: "Inspect only" to read and audit, "Edit configuration" to write, "Set up integrations" to create apps, domains and widget keys.';
+}
 function safeJson(text) {
     try {
         return JSON.parse(text);

package/dist/config.d.ts

@@ -11,6 +11,15 @@ export interface AppilotConnection {
     baseUrl?: string;
     /** Scoped service token (appilot_pat_…). Optional for read-only capability probes. */
     token?: string;
+    /**
+     * An Appilot USER session, which is what the runtime connector authenticates
+     * with (see userClient.ts). It is deliberately a separate field from `token`:
+     * a service token names an organization and its scopes, a session names a
+     * person, and the runtime routes exist precisely so that a connector can
+     * never do more than the person whose session it holds. Sending one where the
+     * other belongs would either fail closed or, worse, widen the connector.
+     */
+    sessionToken?: string;
     /** Default app id for tools that omit one. */
     defaultAppId?: number;
     /** Optional site session for the soak tool (see soak.ts). */
@@ -42,6 +51,18 @@ export declare function loadConnection(env?: NodeJS.ProcessEnv): AppilotConnecti
 /** 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;
+/**
+ * Which of the two servers a stdio process serves.
+ *
+ * `config` is Appilot Studio, the configuration surface a developer connects to
+ * and the default, because it is what every existing client launches. `runtime`
+ * is the Appilot connector, which operates an already-configured app on behalf
+ * of the person using it. One MCP process serves one server, so the choice is
+ * made here rather than inside either factory. The remote transport makes the
+ * same choice per request from the path, and never from an environment value.
+ */
+export type ServerSurface = 'config' | 'runtime';
+export declare function resolveServerSurface(argv?: string[], env?: NodeJS.ProcessEnv): ServerSurface;
 /**
  * Settings for the remote (Streamable HTTP) deployment.
  *

package/dist/config.js

@@ -15,6 +15,7 @@ export function loadConnection(env = process.env) {
     return {
         baseUrl: baseUrl ? trimTrailingSlash(baseUrl) : undefined,
         token: env.APPILOT_PAT?.trim() || undefined,
+        sessionToken: env.APPILOT_SESSION_TOKEN?.trim() || undefined,
         defaultAppId: Number.isFinite(defaultAppId) ? defaultAppId : undefined,
         soakStorageStatePath: env.APPILOT_SOAK_STORAGE_STATE?.trim() || undefined,
     };
@@ -24,6 +25,11 @@ export function resolveTransport(argv = process.argv.slice(2), env = process.env
         return 'http';
     return env.APPILOT_MCP_TRANSPORT?.trim() === 'http' ? 'http' : 'stdio';
 }
+export function resolveServerSurface(argv = process.argv.slice(2), env = process.env) {
+    if (argv.includes('--runtime'))
+        return 'runtime';
+    return env.APPILOT_MCP_SERVER?.trim() === 'runtime' ? 'runtime' : 'config';
+}
 /** 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 {

package/dist/contract/healthContract.js

@@ -31,6 +31,19 @@ const CREATE_INTENT = /\b(create|add|new|update|edit|erstell|anleg|neu|hinzu|cre
 function localizedValues(text) {
     return Object.values(text).filter((v) => typeof v === 'string');
 }
+/**
+ * `form_values` as a record, whatever arrived.
+ *
+ * The snapshot type says it is one, and a hand-authored or scaffolded plan can
+ * still carry null or a string. Reading it defensively keeps a malformed bundle
+ * a finding rather than an exception thrown out of the whole audit.
+ */
+function authoredFormValues(plan) {
+    const raw = plan.form_values;
+    return raw && typeof raw === 'object' && !Array.isArray(raw)
+        ? raw
+        : {};
+}
 // ---------------------------------------------------------------------------
 // Lint 1 — marker trust boundary (reuse appilot-shared).
 // ---------------------------------------------------------------------------
@@ -52,7 +65,7 @@ function lintMarkers(snap) {
             });
         }
         // form_values fields must belong to their form.
-        for (const [formId, entry] of Object.entries(plan.form_values)) {
+        for (const [formId, entry] of Object.entries(authoredFormValues(plan))) {
             if (!formIds.has(formId)) {
                 findings.push({
                     severity: 'high', category: 'markers', entity: `action_plan:${plan.semantic_id}`,
@@ -60,8 +73,22 @@ function lintMarkers(snap) {
                 });
                 continue;
             }
+            // A malformed `form_values` entry is a FINDING, not a crash. The
+            // authored shape is `{ fields: [{ control_id, value }] }`, and a bundle
+            // carrying `{}` there used to take the whole contract down with
+            // "entry.fields is not iterable", so the one tool that could have named
+            // the defect answered with a stack trace instead.
+            const authored = entry;
+            if (!authored || !Array.isArray(authored.fields)) {
+                findings.push({
+                    severity: 'high', category: 'markers', entity: `action_plan:${plan.semantic_id}`,
+                    message: `form_values["${formId}"] is not in the authored shape { fields: [{ control_id, value }] }.`,
+                    recommendation: 'Write an empty fields array when there are no authored defaults.',
+                });
+                continue;
+            }
             const fields = fieldsByForm.get(formId) ?? new Set();
-            for (const f of entry.fields) {
+            for (const f of authored.fields) {
                 if (!fields.has(f.control_id)) {
                     findings.push({
                         severity: 'high', category: 'markers', entity: `action_plan:${plan.semantic_id}`,
@@ -84,7 +111,7 @@ function lintActionability(snap) {
         const markers = planMarkers(plan);
         const hasFormStep = markers.some(m => m.kind === 'form');
         const hasSetValue = markers.some(m => m.kind === 'set_value' || m.kind === 'select');
-        const hasFormValues = Object.keys(plan.form_values).length > 0;
+        const hasFormValues = Object.keys(authoredFormValues(plan)).length > 0;
         const entersValue = hasFormStep || hasSetValue || hasFormValues;
         const looksLikeCreate = localizedValues({ ...plan.name, ...plan.description }).some(v => CREATE_INTENT.test(v))
             || CREATE_INTENT.test(plan.semantic_id);
@@ -123,7 +150,7 @@ function lintActionability(snap) {
             if (!clicksSubmit)
                 continue;
             const fillsForm = markers.some(m => m.kind === 'form' && m.id === form.semantic_id)
-                || (plan.form_values[form.semantic_id]?.fields?.length ?? 0) > 0;
+                || (authoredFormValues(plan)[form.semantic_id]?.fields?.length ?? 0) > 0;
             if (!fillsForm) {
                 findings.push({
                     severity: 'high', category: 'actionability', entity: `action_plan:${plan.semantic_id}`,