appilot-mcp 0.3.0 → 0.4.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "app-configurator",
-  "version": "0.3.0",
+  "version": "0.4.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",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "app-configurator",
-  "version": "0.3.0",
+  "version": "0.4.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",

package/README.md

@@ -1,11 +1,21 @@
 # appilot-mcp
 
-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**.
+Two MCP servers ship from this package, and they do opposite jobs.
 
-It is the tool surface behind the `app-configurator` skill. The skill is the
-instructions; this server is what actually touches your instance.
+**Appilot Studio** 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**. It is the tool
+surface behind the `app-configurator` skill: the skill is the instructions, and
+this server is what actually touches your instance. It is what a bare
+`appilot-mcp` starts.
+
+**Appilot**, the runtime connector, lets the person who USES a configured app
+operate it from the assistant they already pay for. It reads the page they are
+sharing, answers from the app's curated knowledge, and runs the app's own guided
+procedures in their browser under their own session. It writes no configuration.
+Start it with `appilot-mcp --runtime`, or connect to `/mcp/runtime` on the
+deployed service. See
+[the connector spec](../../../docs/architecture/appilot-runtime-connector.md).
 
 ## Why
 
@@ -21,10 +31,10 @@ 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
+## Two transports
 
-The same tools serve two shapes, and which one you need is decided by the client,
-not by preference.
+Each server serves two shapes, and which one you need is decided by the client,
+not by preference. A tool is registered once per server and reachable over both.
 
 | Transport | Who launches it | Credential | Clients |
 |-----------|-----------------|------------|---------|
@@ -44,6 +54,8 @@ OAuth. That is what HTTP mode is for. See
 | `APPILOT_PAT` | for writes / server echo | A scoped service token (`appilot_pat_…`), minted in the Backoffice (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) |
+| `APPILOT_SESSION_TOKEN` | for `--runtime` | An Appilot user session. The connector authenticates as the person, so this is the only credential it reads. |
+| `APPILOT_MCP_SERVER` | optional | `runtime` starts the Appilot connector instead of Studio. Same as `--runtime`. |
 
 HTTP mode reads a different profile. It holds no Appilot credential of its own,
 because each caller brings theirs.
@@ -59,7 +71,7 @@ because each caller brings theirs.
 | `APPILOT_MCP_BACKOFFICE_URL` | no | The Backoffice origin consent screens link to, and the only origin account approval is accepted from. Must be HTTPS (localhost excepted). Defaults to `https://backoffice.appilot.space` when the instance is the Appilot cloud. |
 | `APPILOT_MCP_HANDOFF_SECRET` | no | Enables account approval instead of pasting a service token. At least 32 characters, and it must match the backend's. Separate from the OAuth secret, and it requires `APPILOT_MCP_BACKOFFICE_URL`. |
 
-## Tools
+## Studio tools
 
 Twenty-five, in the order the server registers them. `test/toolSurface.test.ts`
 holds this table, `mcpb/manifest.json` and the registered tools to one list.
@@ -87,6 +99,40 @@ holds this table, `mcpb/manifest.json` and the registered tools to one list.
 | `scaffold_agent_first` | The artifacts one capability needs to be operable by the agent |
 | `report_feedback` / `list_feedback` | Report a gap or a defect in Appilot, and see what this organization has already raised |
 
+## Appilot connector tools
+
+Eight, and deliberately no more: a model reads the whole list on every call.
+They are named in the vocabulary of the person using the app rather than in
+ours. `test/toolSurface.test.ts` holds this table to the registered surface.
+
+| Tool | Purpose |
+|------|---------|
+| `where_am_i` | Which app and view, whether the app is configured, whether a tab is shared, which plans apply here |
+| `read_page` | The shared page as an outline, as the visible text of a region, or as form state with its validation errors |
+| `find_on_page` | Elements by role and accessible name, with refs `highlight` can point at |
+| `highlight` | Point at one control, zone or element on the person's screen |
+| `search_knowledge` | The app's curated knowledge, with citations |
+| `list_plans` | The curated procedures that apply to this view, with the `plan_id` and fields `run_plan` takes |
+| `run_plan` | Run one curated plan in the page at a pace (`teach`, `walk`, `do`) |
+| `plan_status` | How a running plan is going, with a waiting mode that holds for the page to move |
+
+Every result says whether its work was visible in the page and what the answer
+is grounded in, and the tool descriptions oblige the assistant to act on both:
+confirm a plan in one sentence rather than re-listing steps the person is
+watching, and state the mode without inflating it.
+
+`read_page` and `find_on_page` answer with one `page_content` string: the DOM
+result serialized inside the backend's untrusted-content delimiters. The
+connector passes it through untouched, because the delimiters are the
+prompt-injection defence and they only work while they are still around the
+content. What the connector does decide is how much a read asks for, and over a
+hosted connection that is capped.
+
+The connector needs a live Appilot session, and over stdio that is
+`APPILOT_SESSION_TOKEN`. It never reads `APPILOT_PAT`: a service token names an
+organization, a session names a person, and the runtime routes exist so the
+connector can do no more than that person can.
+
 ## The command line
 
 The package is an MCP server first, and a small CLI for the things a pipeline
@@ -259,8 +305,10 @@ 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 |
+| `POST /mcp` | Appilot Studio over Streamable HTTP, bearer required, a configuration scope required |
+| `POST /mcp/runtime` | The Appilot connector, same transport, `runtime:use` required |
+| `/.well-known/oauth-protected-resource/mcp` | Points a Studio client at the authorization server |
+| `/.well-known/oauth-protected-resource/mcp/runtime` | The same for the connector |
 | `/.well-known/oauth-authorization-server` | Metadata, PKCE with S256, dynamic registration |
 | `/authorize`, `/token`, `/register` | The OAuth 2.1 flow |
 | `/consent` | Manual token verification and review |

package/dist/cli.d.ts

@@ -14,7 +14,7 @@
  * that was documented only as a marketplace command pointing at a repository
  * that does not exist.
  */
-export declare const HELP = "appilot-mcp 0.3.0\n\nThe Appilot MCP server: read, validate, fix and provision an Appilot app.\n\nUSAGE\n  appilot-mcp                     Start the MCP server on stdio (what a client launches)\n  appilot-mcp --http              Start the remote HTTP service instead\n  appilot-mcp plan <file>         Preview an appilot.app-manifest. Writes nothing\n  appilot-mcp apply <file>        Plan, then apply the same manifest\n  appilot-mcp install-skill       Copy the app-configurator skill to an agent client\n  appilot-mcp --help | --version\n\nOPTIONS\n  apply           --mode merge|replace   How the config half is imported. Default merge\n                  --allow-unhealthy      Import a bundle the health gate would refuse\n  install-skill   --claude | --codex | --cursor | --gemini | --dir <path>\n\nENVIRONMENT\n  APPILOT_BASE_URL   Your instance, e.g. https://api.appilot.space or http://localhost:6001\n  APPILOT_PAT        A scoped service token from the Backoffice, under Service tokens\n  APPILOT_APP_ID     Optional default app id\n\nDocs: https://docs.appilot.space/docs/developers/configure-with-ai/overview";
+export declare const HELP = "appilot-mcp 0.4.0\n\nThe Appilot MCP server: read, validate, fix and provision an Appilot app.\n\nUSAGE\n  appilot-mcp                     Start Appilot Studio on stdio (what a client launches)\n  appilot-mcp --runtime           Start the Appilot connector instead: operate a configured app\n  appilot-mcp --http              Start the remote HTTP service, which serves both\n  appilot-mcp plan <file>         Preview an appilot.app-manifest. Writes nothing\n  appilot-mcp apply <file>        Plan, then apply the same manifest\n  appilot-mcp install-skill       Copy the app-configurator skill to an agent client\n  appilot-mcp --help | --version\n\nOPTIONS\n  apply           --mode merge|replace   How the config half is imported. Default merge\n                  --allow-unhealthy      Import a bundle the health gate would refuse\n  install-skill   --claude | --codex | --cursor | --gemini | --dir <path>\n\nENVIRONMENT\n  APPILOT_BASE_URL   Your instance, e.g. https://api.appilot.space or http://localhost:6001\n  APPILOT_PAT        A scoped service token from the Backoffice, under Service tokens\n  APPILOT_APP_ID     Optional default app id\n  APPILOT_SESSION_TOKEN  An Appilot user session, which is what --runtime authenticates with\n\nDocs: https://docs.appilot.space/docs/developers/configure-with-ai/overview";
 /** Where each client looks for a skill. One directory per client, all under $HOME. */
 export declare const SKILL_TARGETS: Record<string, string>;
 /**

package/dist/cli.js

@@ -27,8 +27,9 @@ export const HELP = `appilot-mcp ${SERVER_VERSION}
 The Appilot MCP server: read, validate, fix and provision an Appilot app.
 
 USAGE
-  appilot-mcp                     Start the MCP server on stdio (what a client launches)
-  appilot-mcp --http              Start the remote HTTP service instead
+  appilot-mcp                     Start Appilot Studio on stdio (what a client launches)
+  appilot-mcp --runtime           Start the Appilot connector instead: operate a configured app
+  appilot-mcp --http              Start the remote HTTP service, which serves both
   appilot-mcp plan <file>         Preview an appilot.app-manifest. Writes nothing
   appilot-mcp apply <file>        Plan, then apply the same manifest
   appilot-mcp install-skill       Copy the app-configurator skill to an agent client
@@ -43,6 +44,7 @@ ENVIRONMENT
   APPILOT_BASE_URL   Your instance, e.g. https://api.appilot.space or http://localhost:6001
   APPILOT_PAT        A scoped service token from the Backoffice, under Service tokens
   APPILOT_APP_ID     Optional default app id
+  APPILOT_SESSION_TOKEN  An Appilot user session, which is what --runtime authenticates with
 
 Docs: https://docs.appilot.space/docs/developers/configure-with-ai/overview`;
 /** Where each client looks for a skill. One directory per client, all under $HOME. */

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 {