appilot-mcp 0.2.1 → 0.4.0

package/dist/remote/httpServer.js

@@ -2,6 +2,13 @@
  * The remote Appilot MCP service: Streamable HTTP transport plus the OAuth
  * authorization server that fronts it.
  *
+ * One deployment answers for both servers, on two paths behind one authorization
+ * server. `/mcp` is Appilot Studio, which writes configuration for a developer.
+ * `/mcp/runtime` is Appilot, which operates a configured app for the person
+ * using it. They share the consent flow and nothing else: each path refuses a
+ * grant that was not approved for it, so a runtime connection cannot reach a
+ * Studio tool and a configuration connection cannot reach a runtime tool.
+ *
  * Stateless by construction. Each request builds its own MCP server bound to the
  * caller's own service token, which arrives sealed inside the bearer token and
  * never crosses between callers. Nothing is retained between requests, so a
@@ -11,16 +18,20 @@
  */
 import express from 'express';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { mcpAuthRouter, getOAuthProtectedResourceMetadataUrl } from '@modelcontextprotocol/sdk/server/auth/router.js';
+import { mcpAuthRouter, mcpAuthMetadataRouter, createOAuthMetadata, getOAuthProtectedResourceMetadataUrl, } from '@modelcontextprotocol/sdk/server/auth/router.js';
 import { requireBearerAuth } from '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js';
 import { createAppilotServer } from '../server.js';
+import { createAppilotRuntimeServer, RUNTIME_SCOPE, RUNTIME_SCOPE_HELP } from '../userServer.js';
 import { consentLocale } from './consentMessages.js';
 import { renderErrorPage } from './consent.js';
-import { AppilotOAuthProvider, SUPPORTED_SCOPES } from './oauth.js';
+import { AppilotOAuthProvider, SERVICE_TOKEN_SCOPES, SUPPORTED_SCOPES } from './oauth.js';
 /** Where the docs root lands a person who follows the OAuth metadata. */
 const CONFIGURE_WITH_AI_PATH = '/docs/developers/configure-with-ai/overview';
 /** Body cap for a JSON-RPC request. A ConfigBundle import is the large one. */
 const MAX_BODY = '32mb';
+/** Where each server answers. One deployment, two MCP resources, one authorization server. */
+export const STUDIO_MCP_PATH = '/mcp';
+export const RUNTIME_MCP_PATH = '/mcp/runtime';
 export function createRemoteApp(config, options = {}) {
     const provider = options.provider ??
         new AppilotOAuthProvider({
@@ -30,7 +41,8 @@ export function createRemoteApp(config, options = {}) {
             handoffSecret: config.handoffSecret,
             secret: config.secret,
         });
-    const mcpUrl = new URL('/mcp', config.publicUrl);
+    const mcpUrl = new URL(STUDIO_MCP_PATH, config.publicUrl);
+    const runtimeMcpUrl = new URL(RUNTIME_MCP_PATH, config.publicUrl);
     const app = express();
     app.disable('x-powered-by');
     app.use(['/authorize', '/consent', '/connect/callback'], (_req, res, next) => {
@@ -49,6 +61,26 @@ export function createRemoteApp(config, options = {}) {
     app.get(['/health', '/healthz'], (_req, res) => {
         res.json({ status: 'ok', transport: 'http', instance: config.baseUrl });
     });
+    // The runtime resource's own metadata, mounted first.
+    //
+    // RFC 9728 puts a resource's metadata at a path-specific well-known URL, and
+    // the SDK mounts each one with a prefix match. `/…/mcp` therefore also matches
+    // `/…/mcp/runtime`, so the more specific resource has to be registered ahead
+    // of the more general one or a runtime client discovers the Studio resource
+    // and asks for the wrong scope.
+    app.use(mcpAuthMetadataRouter({
+        oauthMetadata: createOAuthMetadata({
+            provider,
+            issuerUrl: config.publicUrl,
+            baseUrl: config.publicUrl,
+            scopesSupported: [...SUPPORTED_SCOPES],
+            serviceDocumentationUrl: new URL(CONFIGURE_WITH_AI_PATH, config.docsUrl),
+        }),
+        resourceServerUrl: runtimeMcpUrl,
+        resourceName: 'Appilot',
+        scopesSupported: [RUNTIME_SCOPE],
+        serviceDocumentationUrl: new URL(CONFIGURE_WITH_AI_PATH, config.docsUrl),
+    }));
     // /.well-known/oauth-authorization-server, /authorize, /token, /register.
     // Must be mounted at the application root.
     app.use(mcpAuthRouter({
@@ -67,7 +99,7 @@ export function createRemoteApp(config, options = {}) {
             res.redirect(303, await provider.finishConnection(id, code, req.get('Cookie') ?? '', res));
         }
         catch {
-            res.status(400).type('html').send(renderErrorPage('Connection could not be completed', 'The approval expired, was already used, or belongs to another browser. Start again from your assistant.', consentLocale(req.get('Accept-Language'))));
+            res.status(400).type('html').send(renderErrorPage('failed', 'failedHelp', consentLocale(req.get('Accept-Language'))));
         }
     });
     // The consent screen posts here. Form-encoded, same-origin, no JSON.
@@ -81,50 +113,102 @@ export function createRemoteApp(config, options = {}) {
             res.status(outcome.status).set('Content-Type', 'text/html; charset=utf-8').send(outcome.html);
         }
         catch {
-            res.status(500).set('Content-Type', 'text/html; charset=utf-8').send(renderErrorPage('Connection unavailable', 'Appilot could not complete the connection. Please try again.', consentLocale(req.get('Accept-Language'))));
+            res.status(500).set('Content-Type', 'text/html; charset=utf-8').send(renderErrorPage('unavailableTitle', 'unavailableDetail', consentLocale(req.get('Accept-Language'))));
         }
     });
     const requireAuth = requireBearerAuth({
         verifier: provider,
         resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(mcpUrl),
     });
-    app.post('/mcp', requireAuth, express.json({ limit: MAX_BODY }), async (req, res) => {
-        const auth = req.auth;
-        const extra = (auth?.extra ?? {});
-        // One server and one transport per request. The connection profile is the
-        // caller's own: the deployment's fixed instance URL, their service token,
-        // and the scopes the person actually approved, which the tool surface
-        // enforces so the consent screen describes a real limit.
-        const server = createAppilotServer({
-            baseUrl: config.baseUrl,
-            token: extra.pat,
-            defaultAppId: extra.appId,
-            transport: 'http',
-            grantedScopes: auth?.scopes ?? [],
-        });
-        const transport = new StreamableHTTPServerTransport({
-            sessionIdGenerator: undefined,
-            enableDnsRebindingProtection: true,
-            allowedHosts: config.allowedHosts,
-        });
-        res.on('close', () => {
-            void transport.close();
-            void server.close();
-        });
-        try {
-            await server.connect(transport);
-            await transport.handleRequest(req, res, req.body);
-        }
-        catch (err) {
-            if (!res.headersSent) {
-                res.status(500).json({
+    const requireRuntimeAuth = requireBearerAuth({
+        verifier: provider,
+        resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(runtimeMcpUrl),
+    });
+    /**
+     * Keep the two servers apart at the door.
+     *
+     * The tools enforce their own scopes one layer in, and that is not enough on
+     * its own: several Studio tools are pure and need no scope, so a runtime-only
+     * grant could still reach them if the endpoint let it through. The endpoint
+     * therefore decides first. Studio needs at least one configuration scope,
+     * Appilot needs `runtime:use`, and a grant approved for both reaches both,
+     * which is what approving both means.
+     */
+    function wrongServer(scopes, wanted) {
+        const granted = scopes ?? [];
+        const reaches = wanted === 'runtime'
+            ? granted.includes(RUNTIME_SCOPE)
+            : granted.some(scope => SERVICE_TOKEN_SCOPES.includes(scope));
+        if (reaches)
+            return null;
+        const held = granted.length ? granted.join(', ') : 'no scopes';
+        return wanted === 'runtime'
+            ? `This connection was approved for ${held}, which does not include ${RUNTIME_SCOPE}, so it reaches Appilot Studio at ${STUDIO_MCP_PATH} and not the Appilot connector. ${RUNTIME_SCOPE_HELP}`
+            : `This connection was approved for ${held}, which carries no configuration scope, so it reaches the Appilot connector at ${RUNTIME_MCP_PATH} and not Appilot Studio. Studio is a separate connection: add it in your assistant and approve it with a service token that carries config:read or config:write, which an organization administrator mints in the Backoffice under Service tokens.`;
+    }
+    function mcpEndpoint(surface) {
+        return async (req, res) => {
+            const auth = req.auth;
+            const extra = (auth?.extra ?? {});
+            const refusal = wrongServer(auth?.scopes, surface);
+            if (refusal) {
+                res.status(403).json({
                     jsonrpc: '2.0',
-                    error: { code: -32603, message: err instanceof Error ? err.message : 'Internal error' },
+                    error: { code: -32001, message: refusal },
                     id: null,
                 });
+                return;
             }
-        }
-    });
+            // One server and one transport per request. The connection profile is the
+            // caller's own: the deployment's fixed instance URL, the credential the
+            // approval sealed, and the scopes the person actually approved, which the
+            // tool surface enforces so the consent screen describes a real limit.
+            //
+            // The sealed credential is a service token for Studio and the person's
+            // own Appilot session for the connector. It is read here, never echoed,
+            // and the two never reach the same server.
+            const server = surface === 'runtime'
+                ? createAppilotRuntimeServer({
+                    baseUrl: config.baseUrl,
+                    sessionToken: extra.pat,
+                    transport: 'http',
+                    grantedScopes: auth?.scopes ?? [],
+                })
+                : createAppilotServer({
+                    baseUrl: config.baseUrl,
+                    token: extra.pat,
+                    defaultAppId: extra.appId,
+                    transport: 'http',
+                    grantedScopes: auth?.scopes ?? [],
+                });
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+                enableDnsRebindingProtection: true,
+                allowedHosts: config.allowedHosts,
+            });
+            res.on('close', () => {
+                void transport.close();
+                void server.close();
+            });
+            try {
+                await server.connect(transport);
+                await transport.handleRequest(req, res, req.body);
+            }
+            catch (err) {
+                if (!res.headersSent) {
+                    res.status(500).json({
+                        jsonrpc: '2.0',
+                        error: { code: -32603, message: err instanceof Error ? err.message : 'Internal error' },
+                        id: null,
+                    });
+                }
+            }
+        };
+    }
+    // The runtime path is registered first: express matches in order, and `/mcp`
+    // is a prefix of it in every other place this file touches.
+    app.post(RUNTIME_MCP_PATH, requireRuntimeAuth, express.json({ limit: MAX_BODY }), mcpEndpoint('runtime'));
+    app.post(STUDIO_MCP_PATH, requireAuth, express.json({ limit: MAX_BODY }), mcpEndpoint('studio'));
     // Stateless: there is no stream to resume and no session to delete.
     const methodNotAllowed = (_req, res) => {
         res.status(405).set('Allow', 'POST').json({
@@ -133,8 +217,10 @@ export function createRemoteApp(config, options = {}) {
             id: null,
         });
     };
-    app.get('/mcp', methodNotAllowed);
-    app.delete('/mcp', methodNotAllowed);
+    for (const path of [STUDIO_MCP_PATH, RUNTIME_MCP_PATH]) {
+        app.get(path, methodNotAllowed);
+        app.delete(path, methodNotAllowed);
+    }
     return app;
 }
 export function startRemote(config) {

package/dist/remote/oauth.d.ts

@@ -34,8 +34,17 @@ import { type ConsentLocale } from './consentMessages.js';
  * `feedback:write` is the one scope that governs sending data OUT of the
  * tenant, which is why it is separate from the config scopes rather than folded
  * into them.
+ *
+ * `runtime:use` is the odd one and it is the reason this list is not simply the
+ * service-token scopes. It authorizes the Appilot connector, which holds a
+ * person's own session and operates their app through the page they are looking
+ * at. It grants nothing over configuration, and the four config scopes grant
+ * nothing over the runtime surface: the two servers sit on separate paths, each
+ * refusing a grant that was not approved for it (see `remote/httpServer.ts`).
  */
-export declare const SUPPORTED_SCOPES: readonly ["config:read", "config:write", "provision:write", "feedback:write"];
+export declare const SUPPORTED_SCOPES: readonly ["config:read", "config:write", "provision:write", "feedback:write", "runtime:use"];
+/** The scopes a service token can carry. `runtime:use` is not one of them. */
+export declare const SERVICE_TOKEN_SCOPES: readonly string[];
 /** What the instance says a credential reaches. Absent on instances without /config/whoami. */
 export interface TokenIdentity {
     organizationName?: string | null;

package/dist/remote/oauth.js

@@ -35,12 +35,27 @@ import { renderConsentPage, renderConfirmPage, renderErrorPage } from './consent
  * `feedback:write` is the one scope that governs sending data OUT of the
  * tenant, which is why it is separate from the config scopes rather than folded
  * into them.
+ *
+ * `runtime:use` is the odd one and it is the reason this list is not simply the
+ * service-token scopes. It authorizes the Appilot connector, which holds a
+ * person's own session and operates their app through the page they are looking
+ * at. It grants nothing over configuration, and the four config scopes grant
+ * nothing over the runtime surface: the two servers sit on separate paths, each
+ * refusing a grant that was not approved for it (see `remote/httpServer.ts`).
  */
 export const SUPPORTED_SCOPES = [
     'config:read',
     'config:write',
     'provision:write',
     'feedback:write',
+    'runtime:use',
+];
+/** The scopes a service token can carry. `runtime:use` is not one of them. */
+export const SERVICE_TOKEN_SCOPES = [
+    'config:read',
+    'config:write',
+    'provision:write',
+    'feedback:write',
 ];
 /**
  * What to ask for when the client asks for nothing.
@@ -112,8 +127,11 @@ async function defaultVerifyServiceToken(baseUrl, pat) {
     if (res.status === 401 || res.status === 403)
         return null;
     if (res.status === 404) {
-        // Instance predates the self-check. Accept the token on shape alone.
-        return { organizationId: null, appId: null, scopes: [...SUPPORTED_SCOPES] };
+        // Instance predates the self-check. Accept the token on shape alone, and
+        // only for what a service token can ever carry: `runtime:use` names a
+        // person's session, so an instance that cannot answer must not be read as
+        // having said yes to it.
+        return { organizationId: null, appId: null, scopes: [...SERVICE_TOKEN_SCOPES] };
     }
     if (!res.ok) {
         throw new ServerError(`The Appilot instance answered ${res.status} while verifying the service token.`);
@@ -188,7 +206,7 @@ export class AppilotOAuthProvider {
         const sealedRequest = await this.sealAuthRequest({
             language,
             client_id: client.client_id,
-            client_name: client.client_name || 'your assistant',
+            client_name: client.client_name || message('clientFallback', language),
             redirect_uri: params.redirectUri,
             code_challenge: params.codeChallenge,
             state: params.state,
@@ -204,7 +222,7 @@ export class AppilotOAuthProvider {
                     secret: this.options.handoffSecret,
                     backofficeUrl: this.options.backofficeUrl,
                     secure: this.options.publicUrl.protocol === 'https:',
-                }, sealedRequest, client.client_id, client.client_name || 'AI assistant', requested.length ? requested : [...DEFAULT_REQUESTED_SCOPES], language, res);
+                }, sealedRequest, client.client_id, client.client_name || message('clientFallback', language), requested.length ? requested : [...DEFAULT_REQUESTED_SCOPES], language, res);
                 return;
             }
             catch {
@@ -215,7 +233,7 @@ export class AppilotOAuthProvider {
                     locale: language,
                     request: sealedRequest,
                     action: this.consentPath,
-                    clientName: client.client_name || 'AI assistant',
+                    clientName: client.client_name || message('clientFallback', language),
                     baseUrl: this.options.baseUrl,
                     backofficeUrl: this.options.backofficeUrl,
                     scopes: requested.length ? requested : [...DEFAULT_REQUESTED_SCOPES],
@@ -228,7 +246,7 @@ export class AppilotOAuthProvider {
             locale: language,
             request: sealedRequest,
             action: this.consentPath,
-            clientName: client.client_name || 'an MCP client',
+            clientName: client.client_name || message('clientFallback', language),
             baseUrl: this.options.baseUrl,
             backofficeUrl: this.options.backofficeUrl,
             scopes: requested.length ? requested : [...DEFAULT_REQUESTED_SCOPES],
@@ -304,14 +322,14 @@ export class AppilotOAuthProvider {
         catch {
             return {
                 status: 400,
-                html: renderErrorPage('This sign-in link expired', 'Start the connection again from the client that sent you here. A consent link is valid for ten minutes.', fallbackLocale),
+                html: renderErrorPage('expired', 'expiredHelp', fallbackLocale),
             };
         }
         const locale = request.language ?? fallbackLocale;
         if (request.stage !== 'request' && request.stage !== 'confirm') {
             return {
                 status: 400,
-                html: renderErrorPage('Invalid request', 'That confirmation is incomplete. Start again.', locale),
+                html: renderErrorPage('invalid', 'invalidHelp', locale),
             };
         }
         const redirect = new URL(request.redirect_uri);
@@ -335,7 +353,7 @@ export class AppilotOAuthProvider {
                         locale,
                         request: await this.sealAuthRequest({ ...original, scopes }),
                         action: this.consentPath,
-                        clientName: request.client_name || 'your assistant',
+                        clientName: request.client_name || message('clientFallback', locale),
                         baseUrl: this.options.baseUrl,
                         backofficeUrl: this.options.backofficeUrl,
                         scopes,
@@ -345,7 +363,7 @@ export class AppilotOAuthProvider {
             if (form.action !== 'confirm' || !request.pat || !request.identity) {
                 return {
                     status: 400,
-                    html: renderErrorPage('Invalid request', 'That confirmation is incomplete. Start again.', locale),
+                    html: renderErrorPage('invalid', 'invalidHelp', locale),
                 };
             }
             return {
@@ -364,7 +382,7 @@ export class AppilotOAuthProvider {
                 locale,
                 request: rawRequest,
                 action: this.consentPath,
-                clientName: request.client_name || 'your assistant',
+                clientName: request.client_name || message('clientFallback', locale),
                 baseUrl: this.options.baseUrl,
                 backofficeUrl: this.options.backofficeUrl,
                 scopes: request.scopes,

package/dist/scaffold.d.ts

@@ -10,8 +10,23 @@
  * integration a developer must write in their own backend, it is
  * security-critical, and getting it wrong is invisible until an auth edge case
  * shows up in production.
+ *
+ * Everything returned here has to COMPILE. Three of the six framework outputs
+ * did not typecheck under `strict` when the 2026-09-07 audit ran them through
+ * `tsc`, and the relay, the piece a developer is least able to review, was the
+ * file that failed. `test/scaffoldTypecheck.test.ts` now compiles every output
+ * against the workspace sources of `appilot` and `appilot-server`.
+ */
+/**
+ * The frameworks with a first-class relay, plus `other`.
+ *
+ * `appilot-server` is a Node package, so a Django, Rails or PHP host cannot use
+ * it. That is not a reason to answer a raw Zod enum dump: the exchange is one
+ * authenticated HTTPS call, and `other` returns it as curl plus a Python and a
+ * Ruby handler.
  */
-export type Framework = 'next' | 'express' | 'fastify' | 'hono' | 'remix' | 'sveltekit';
+export declare const SCAFFOLD_FRAMEWORKS: readonly ["next", "express", "fastify", "hono", "remix", "sveltekit", "other"];
+export type Framework = (typeof SCAFFOLD_FRAMEWORKS)[number];
 export interface ScaffoldFile {
     /** Suggested path, relative to the repository root. The agent may move it. */
     path: string;
@@ -49,19 +64,38 @@ export declare function scaffoldIntegration(options: ScaffoldOptions): ScaffoldR
  * A step-by-step knowledge article is a procedure in the wrong place, and it
  * teaches the agent to author steps instead of adopting the plan that already
  * exists. Emitting both halves correctly is how a scaffold teaches that once.
+ *
+ * Everything emitted here is in the shape the API accepts, and
+ * `test/scaffoldAgentFirst.test.ts` proves it by running the output through the
+ * shared action-plan schemas and through the health contract. The previous
+ * version emitted `{ title, steps: [{ text }] }` sections and a `form_values`
+ * entry with no `fields`, so the tool meant to make an app agent-first produced
+ * a plan `create_entity` rejected and `runHealthContract` crashed on.
  */
 export interface AgentFirstScaffold {
     capability: string;
-    /** Ready for `create_tool`, minus the credential. */
-    tool: Record<string, unknown>;
-    /** Ready for `create_action_plan` once the control ids exist. */
-    actionPlan: Record<string, unknown>;
-    /** Ready for `create_knowledge`. */
+    shape: CapabilityShape;
+    /** Ready for `create_entity({ kind: 'tool' })`, minus the credential. Null for a page-only capability. */
+    tool: Record<string, unknown> | null;
+    /** Ready for `create_entity({ kind: 'action_plan' })` once the control ids exist. Null when the capability has no in-page procedure. */
+    actionPlan: Record<string, unknown> | null;
+    /** Ready for `create_entity({ kind: 'knowledge' })`. */
     knowledge: Record<string, unknown>;
     files: ScaffoldFile[];
     order: string[];
     notes: string[];
 }
+/**
+ * What the capability does to the app, which decides whether a plan makes sense
+ * and what its steps are.
+ *
+ * `create` is a form the user fills and submits. `navigate` takes them to a
+ * place. `read` answers a question, and it gets NO action plan: a plan whose
+ * only step opens a screen does nothing, and the health contract says so. The
+ * scaffold used to emit the open/fill/submit template for all three, so asking
+ * it for "Show a booking" produced a plan that filled a form nobody had.
+ */
+export type CapabilityShape = 'create' | 'navigate' | 'read';
 interface AgentFirstOptions {
     /** What the user is trying to do, in their words. */
     capability: string;
@@ -79,6 +113,34 @@ interface AgentFirstOptions {
     } | null;
     /** True when the operation is UI-coupled and belongs in the page instead. */
     clientSide?: boolean;
+    /** What the capability does. Defaults to `create`. */
+    shape?: CapabilityShape;
+    /** Where the plan's steps run. Defaults to `/`. */
+    viewPath?: string;
 }
 export declare function scaffoldAgentFirst(options: AgentFirstOptions): AgentFirstScaffold;
+export interface IntegrationSnippet {
+    apiUrl: string | null;
+    scriptTag: string;
+    bootSnippet: string;
+    tokenEndpointHint: string;
+    publicEnvName: string;
+    notes: string[];
+}
+/**
+ * The script tag and the boot call for an app that is already provisioned.
+ *
+ * `create_app` returns these, and returning them was the only way to get them,
+ * so a developer who had lost the snippet re-ran a provisioning write to read
+ * one line of HTML. They are composed from the connection and the key, so this
+ * is pure: it calls nothing and needs no scope. The shape matches what the
+ * backend's own `buildIntegration` returns, deliberately, so a curl caller and
+ * an agent read the same thing.
+ */
+export declare function integrationSnippet(options: {
+    widgetScriptUrl: string;
+    apiUrl?: string | null;
+    widgetKey?: string | null;
+    framework?: Framework;
+}): IntegrationSnippet;
 export {};