@typeroll/mcp-server 0.33.2 → 0.35.0

package/dist/extension-cli.js

@@ -0,0 +1,188 @@
+import { readFile } from 'node:fs/promises';
+function option(args, name) {
+    const index = args.indexOf(name);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+async function readJson(path) {
+    const parsed = JSON.parse(await readFile(path, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        throw new Error(`${path} must contain a JSON object`);
+    return parsed;
+}
+export function validateExtensionManifestShape(manifest) {
+    const errors = [];
+    if (manifest.schema_version !== 1)
+        errors.push('schema_version must be 1');
+    if (typeof manifest.id !== 'string' || !/^[a-z0-9]+(?:[.-][a-z0-9][a-z0-9-]*){2,}$/.test(manifest.id))
+        errors.push('id must be a lowercase namespaced identifier');
+    if (typeof manifest.name !== 'string' || !manifest.name.trim())
+        errors.push('name is required');
+    if (typeof manifest.version !== 'string' || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(manifest.version))
+        errors.push('version must be semver');
+    if (typeof manifest.runtime_compatibility !== 'string' || !manifest.runtime_compatibility.trim())
+        errors.push('runtime_compatibility is required');
+    if (!['private', 'unlisted', 'public'].includes(String(manifest.distribution)))
+        errors.push('distribution must be private, unlisted or public');
+    const developer = manifest.developer;
+    if (!developer || typeof developer.name !== 'string')
+        errors.push('developer.name is required');
+    const frontend = manifest.frontend;
+    const components = frontend?.components;
+    if (components !== undefined && !Array.isArray(components))
+        errors.push('frontend.components must be an array');
+    for (const [index, value] of (Array.isArray(components) ? components : []).entries()) {
+        const component = value;
+        const entry = component?.entry;
+        if (!component || typeof component.id !== 'string' || typeof component.label !== 'string')
+            errors.push(`frontend.components[${index}] needs id and label`);
+        if (!['bundled_component', 'embedded_app'].includes(String(component?.render_mode)))
+            errors.push(`frontend.components[${index}].render_mode is invalid`);
+        if (component?.render_mode === 'bundled_component' && (!entry || typeof entry.script_url !== 'string' || !/^[a-f0-9]{64}$/.test(String(entry.script_sha256)))) {
+            errors.push(`frontend.components[${index}] needs script_url and lowercase SHA-256`);
+        }
+        if (component?.render_mode === 'embedded_app' && (!entry || typeof entry.frame_url !== 'string'))
+            errors.push(`frontend.components[${index}] needs frame_url`);
+    }
+    return errors;
+}
+function executionOrigins(manifest) {
+    const urls = [];
+    const components = (manifest.frontend?.components ?? []);
+    for (const component of components) {
+        const entry = component.entry;
+        for (const key of ['script_url', 'style_url', 'frame_url'])
+            if (typeof entry?.[key] === 'string')
+                urls.push(entry[key]);
+    }
+    const pages = (manifest.admin?.pages ?? []);
+    for (const page of pages)
+        if (typeof page.launch_url === 'string')
+            urls.push(page.launch_url);
+    for (const value of [
+        manifest.gateway?.base_url,
+        manifest.events?.webhook_url,
+        manifest.auth?.pairing_url,
+    ])
+        if (typeof value === 'string')
+            urls.push(value);
+    return [...new Set(urls.map((value) => new URL(value).origin))];
+}
+async function api(path, init = {}, allowed = []) {
+    const baseUrl = process.env.TYPEROLL_API_URL?.trim().replace(/\/$/, '');
+    const apiKey = process.env.TYPEROLL_API_KEY?.trim();
+    if (!baseUrl || !apiKey)
+        throw new Error('TYPEROLL_API_URL and TYPEROLL_API_KEY are required');
+    const headers = new Headers(init.headers);
+    headers.set('Authorization', `Bearer ${apiKey}`);
+    if (init.body)
+        headers.set('Content-Type', 'application/json');
+    const response = await fetch(`${baseUrl}${path}`, { ...init, headers });
+    const data = await response.json().catch(() => ({}));
+    if (!response.ok && !allowed.includes(response.status))
+        throw new Error(String(data.error ?? `Typeroll API returned ${response.status}`));
+    return { status: response.status, data };
+}
+function help() {
+    console.error('Usage:');
+    console.error('  typeroll extension validate [manifest]');
+    console.error('  typeroll extension push --draft [--manifest path]');
+    console.error('  typeroll extension install --site <site-id> [--manifest path] [--config config.json]');
+    console.error('  typeroll extension promote <version> [--manifest path]');
+}
+export async function runExtensionCli(args) {
+    const command = args[0];
+    if (!command || ['help', '--help', '-h'].includes(command)) {
+        help();
+        return 0;
+    }
+    const manifestPath = option(args, '--manifest') ?? (command === 'validate' && args[1] && !args[1].startsWith('-') ? args[1] : 'typeroll-extension.json');
+    try {
+        const manifest = await readJson(manifestPath);
+        const errors = validateExtensionManifestShape(manifest);
+        if (errors.length) {
+            for (const error of errors)
+                console.error(`- ${error}`);
+            return 1;
+        }
+        if (command === 'validate') {
+            console.log(`${manifestPath}: valid manifest v1 shape (server validation remains authoritative)`);
+            return 0;
+        }
+        const extensionId = String(manifest.id);
+        if (command === 'push') {
+            const current = await api(`/api/developer/extensions/${encodeURIComponent(extensionId)}`, {}, [404]);
+            if (current.status === 404) {
+                const created = await api('/api/developer/extensions', {
+                    method: 'POST',
+                    body: JSON.stringify({
+                        id: extensionId,
+                        name: manifest.name,
+                        distribution: manifest.distribution,
+                        trusted_origins: executionOrigins(manifest),
+                    }),
+                });
+                if (created.data.client_secret)
+                    console.error('Extension client secret (shown once):', created.data.client_secret);
+            }
+            else {
+                const registered = current.data.extension;
+                const trusted = Array.isArray(registered?.trusted_origins) ? registered.trusted_origins.map(String) : [];
+                await api(`/api/developer/extensions/${encodeURIComponent(extensionId)}`, {
+                    method: 'PATCH',
+                    body: JSON.stringify({
+                        name: manifest.name,
+                        trusted_origins: [...new Set([...trusted, ...executionOrigins(manifest)])],
+                    }),
+                });
+            }
+            const pushed = await api(`/api/developer/extensions/${encodeURIComponent(extensionId)}/versions`, {
+                method: 'POST', body: JSON.stringify({ manifest }),
+            });
+            console.log(`Saved ${extensionId}@${String(pushed.data.version?.version ?? manifest.version)} as draft`);
+            return 0;
+        }
+        if (command === 'promote') {
+            const version = args[1];
+            if (!version || version.startsWith('-'))
+                throw new Error('promote requires a version');
+            const promoted = await api(`/api/developer/extensions/${encodeURIComponent(extensionId)}/versions/${encodeURIComponent(version)}/publish`, { method: 'POST' });
+            console.log(`${extensionId}@${version}: ${String(promoted.data.version?.status ?? 'published')}`);
+            return 0;
+        }
+        if (command === 'install') {
+            const siteId = option(args, '--site');
+            if (!siteId)
+                throw new Error('install requires --site <site-id>');
+            const configPath = option(args, '--config');
+            const config = configPath ? await readJson(configPath) : {};
+            const permissions = Array.isArray(manifest.permissions) ? manifest.permissions : [];
+            if (manifest.distribution === 'private') {
+                const current = await api(`/api/developer/extensions/${encodeURIComponent(extensionId)}`);
+                const registered = current.data.extension;
+                const allowed = Array.isArray(registered?.allowed_site_ids) ? registered.allowed_site_ids.map(String) : [];
+                if (!allowed.includes(siteId)) {
+                    await api(`/api/developer/extensions/${encodeURIComponent(extensionId)}`, {
+                        method: 'PATCH', body: JSON.stringify({ allowed_site_ids: [...allowed, siteId] }),
+                    });
+                }
+            }
+            const installed = await api(`/api/v1/sites/${encodeURIComponent(siteId)}/extensions`, {
+                method: 'POST',
+                body: JSON.stringify({
+                    extension_id: extensionId,
+                    version: manifest.version,
+                    granted_scopes: permissions.map((permission) => permission.scope).filter((scope) => typeof scope === 'string'),
+                    config,
+                }),
+            });
+            console.log(`Installed ${extensionId}@${String(manifest.version)} as ${String(installed.data.installation?.id ?? '')}`);
+            return 0;
+        }
+        help();
+        return 1;
+    }
+    catch (error) {
+        console.error(`typeroll extension: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+}

package/dist/index.js

@@ -19,6 +19,7 @@ import { runInstallSkillsCli } from './install-skills.js';
 import { resolveSiteId } from './resolve-site-id.js';
 import { buildServer } from './server.js';
 import { VERSION } from './version.js';
+import { runExtensionCli } from './extension-cli.js';
 function bail(message) {
     console.error(`typeroll-mcp: ${message}`);
     process.exit(1);
@@ -33,11 +34,16 @@ async function main() {
         const code = await runInstallSkillsCli(argv.slice(1));
         process.exit(code);
     }
+    if (argv[0] === 'extension') {
+        const code = await runExtensionCli(argv.slice(1));
+        process.exit(code);
+    }
     if (argv[0] === '--help' || argv[0] === '-h' || argv[0] === 'help') {
         console.error('Usage:');
         console.error('  typeroll-mcp                              Start the MCP server (reads TYPEROLL_API_URL and TYPEROLL_API_KEY)');
         console.error('  typeroll-mcp init [dir] [-f]              Bootstrap a project: skills + .mcp.json + AGENTS.md + imagegen lab');
         console.error('  typeroll-mcp install-skills <dir> [-f]    Copy bundled skill files to <dir>');
+        console.error('  typeroll extension <command>              Validate, push, install or promote an Extension');
         console.error('  typeroll-mcp --help                       Show this help');
         process.exit(0);
     }

package/dist/server.js

@@ -28,6 +28,7 @@ import { settingsTools } from './tools/settings.js';
 import { siteTools } from './tools/sites.js';
 import { domainTools } from './tools/domain.js';
 import { funnelAttributionTools } from './tools/funnel-attribution.js';
+import { appTools } from './tools/apps.js';
 import { skillTools } from './tools/skills.js';
 import { fail } from './tools/helpers.js';
 import { VERSION } from './version.js';
@@ -42,7 +43,11 @@ const PERM_RANK = { read: 0, write: 1, admin: 2 };
  * mutates.
  */
 function effectFor(name) {
-    if (name === 'update_funnel_attribution')
+    if (name === 'list_apps'
+        || name === 'read_app'
+        || name === 'update_app'
+        || name === 'read_funnel_attribution'
+        || name === 'update_funnel_attribution')
         return 'admin';
     if (name.startsWith('list_') ||
         name.startsWith('read_') ||
@@ -119,6 +124,7 @@ export function buildServer(options) {
         ...migrationTools,
         ...formTools,
         ...settingsTools,
+        ...appTools,
         ...funnelAttributionTools,
         ...searchTools,
         ...bulkTools,

package/dist/tools/apps.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { ok, withErrorBoundary } from './helpers.js';
+export const appTools = [
+    {
+        name: 'list_apps',
+        description: 'List every Typeroll app available to this site, including its field schema, build impact, and masked enabled/config state. Admin permission required.',
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            return ok(await client.get(siteId, 'apps'));
+        }),
+    },
+    {
+        name: 'read_app',
+        description: 'Read one Typeroll app by registry id, including its field schema and masked state. Use list_apps to discover ids and required config fields. Secret values are never returned. Admin permission required.',
+        inputSchema: {
+            app_id: z.string().min(1).describe('Registry id returned by list_apps, for example analytics or integrations.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            return ok(await client.get(siteId, `apps/${encodeURIComponent(args.app_id)}`));
+        }),
+    },
+    {
+        name: 'update_app',
+        description: 'Enable, configure, or disable any registered Typeroll app through the same admin API key used for publishing. Read the app first and send config keys from its field schema. Omitted fields preserve existing values, including encrypted secrets; secret values are masked on reads and encrypted server-side on writes. Analytics provisioning runs server-side when enabled. If affects_build is true, trigger_deploy is required to publish the change. Admin permission required.',
+        inputSchema: {
+            app_id: z.string().min(1).describe('Registry id returned by list_apps.'),
+            enabled: z.boolean(),
+            config: z.record(z.unknown()).optional().describe('Schema-driven app config. Omitted fields preserve their existing values.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            return ok(await client.put(siteId, `apps/${encodeURIComponent(args.app_id)}`, {
+                enabled: args.enabled,
+                config: args.config ?? {},
+            }));
+        }),
+    },
+];

package/dist/tools/forms.js

@@ -1,10 +1,8 @@
 // Forms — agents can create/update/delete forms, and read submissions.
 // The customer-facing submit endpoint is HMAC-signed and lives at
-// /api/forms/submit. read_form/create_form return `submit_token` +
-// `submit_url`, which is everything an agent needs to embed a working
-// plain-POST form (no client JS — the page sanitizer strips inline
-// <script>, and the endpoint answers form-encoded posts with an HTML
-// confirmation page).
+// /api/forms/submit. Agents place forms by reference: core/form in block mode,
+// or <x-form id="…" /> in HTML mode. Preview/build expands either reference
+// through the same trusted renderer with token, initial state, and runtime.
 import { z } from 'zod';
 import { ok, withErrorBoundary } from './helpers.js';
 const fieldSchema = z.object({
@@ -42,7 +40,7 @@ export const formTools = [
     },
     {
         name: 'read_form',
-        description: 'Read one form by id, including fields/steps, submit_text, success_message — plus submit_token and submit_url. To place the form on a page, prefer a `core/form` block with data.form_id (renders both fields-forms and steps-forms with validation). The plain <form method="POST" action={submit_url}> embed with a hidden _token input and an empty honeypot _hp remains a working no-JS fallback.',
+        description: 'Read one form by id, including fields/steps, submit_text, and success_message. Place it with a `core/form` block using data.form_id on a block-mode page, or `<x-form id="…" />` in HTML mode. Both references are expanded server-side with validation, signed token, initial state, and the shared runtime.',
         inputSchema: { form_id: z.string() },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const res = await client.get(siteId, `forms/${encodeURIComponent(args.form_id)}`);
@@ -51,7 +49,7 @@ export const formTools = [
     },
     {
         name: 'create_form',
-        description: 'Create a form. Steps are the ONLY stored model — a Block[] tree of form/* field blocks per step. Simple forms: pass `fields`, each { name, type, label, required?, placeholder?, options? } (allowed types: text, email, tel, url, number, textarea, select, checkbox, radio, hidden, gdpr_consent) — the server converts them to a single static step; read_form returns the resulting steps. Multi-step funnels: pass `steps` directly (steps swap client-side, partial submissions persist per step). PLACING THE FORM ON A PAGE: add a `core/form` block with data.form_id — validation + styled inputs + signed token all handled. The raw <form method="POST" action={submit_url}> embed (single-step forms only) is the fallback for HTML-mode pages. Do NOT add inline <script> (the page sanitizer strips it).',
+        description: 'Create a form. Steps are the ONLY stored model — a Block[] tree of form/* field blocks per step. Simple forms: pass `fields`, each { name, type, label, required?, placeholder?, options? } (allowed types: text, email, tel, url, number, textarea, select, checkbox, radio, hidden, gdpr_consent) — the server converts them to a single static step; read_form returns the resulting steps. Multi-step funnels: pass `steps` directly (steps swap client-side, partial submissions persist per step). PLACING THE FORM: add a `core/form` block with data.form_id on block-mode pages, or `<x-form id="…" />` to HTML-mode page content. Both expand server-side to the same complete signed shell; never hand-write the form or add inline submit scripts.',
         inputSchema: {
             id: z.string().regex(/^[a-z][a-z0-9_-]{0,62}$/),
             name: z.string().min(1),

package/dist/version.js

@@ -8,4 +8,4 @@
 //
 // Keep it in lockstep with package.json: tests/version.test.ts asserts
 // VERSION === package.json.version, so a bump that forgets this line fails CI.
-export const VERSION = '0.33.2';
+export const VERSION = '0.35.0';

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.33.2",
+  "version": "0.35.0",
   "description": "Model Context Protocol server for the Typeroll public API. Use with Claude Code or any MCP-compatible client to manage a Typeroll site.",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/bootingbots/typeroll.git",
+    "url": "git+https://github.com/Typeroll/typeroll-cloud.git",
     "directory": "packages/mcp-server"
   },
-  "homepage": "https://github.com/bootingbots/typeroll/tree/main/packages/mcp-server#readme",
-  "bugs": "https://github.com/bootingbots/typeroll/issues",
+  "homepage": "https://github.com/Typeroll/typeroll-cloud/tree/main/packages/mcp-server#readme",
+  "bugs": "https://github.com/Typeroll/typeroll-cloud/issues",
   "type": "module",
   "bin": {
-    "typeroll-mcp": "dist/index.js"
+    "typeroll-mcp": "dist/index.js",
+    "typeroll": "dist/index.js"
   },
   "main": "./dist/index.js",
   "exports": {