@typeroll/mcp-server 0.45.82 → 0.45.84

package/dist/extension-cli.js

@@ -1,4 +1,5 @@
 import { readFile } from 'node:fs/promises';
+import { apiUrlProblem } from './api-url.js';
 function option(args, name) {
     const index = args.indexOf(name);
     return index >= 0 ? args[index + 1] : undefined;
@@ -83,11 +84,32 @@ export function extensionMetadataUpdate(manifest, registered, manifestOrigins) {
     }
     return update;
 }
+/** One id segment, by the same rule the portal applies to allowed_site_ids. */
+function isIdSegment(value) {
+    return value.length >= 1 && value.length <= 128 && value !== '.' && value !== '..' && !/[/\\\s\x00-\x1f\x7f]/.test(value);
+}
+/**
+ * Parse `install --site`. `org/site` names a site of any organization and is
+ * written to allowed_site_ids in that form; a bare site id only ever matches
+ * a site of the developer organization itself.
+ */
+export function parseInstallSite(value) {
+    const parts = value.split('/');
+    if (parts.length === 1 && isIdSegment(value))
+        return { siteId: value, ownerOrgId: null, allowEntry: value };
+    if (parts.length === 2 && isIdSegment(parts[0]) && isIdSegment(parts[1])) {
+        return { siteId: parts[1], ownerOrgId: parts[0], allowEntry: value };
+    }
+    throw new Error('--site must be <site-id> or <organization-id>/<site-id>');
+}
 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 apiUrlError = apiUrlProblem(baseUrl);
+    if (apiUrlError)
+        throw new Error(apiUrlError);
     const headers = new Headers(init.headers);
     headers.set('Authorization', `Bearer ${apiKey}`);
     if (init.body)
@@ -102,7 +124,7 @@ 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 install --site <site-id | organization-id/site-id> [--manifest path] [--config config.json]');
     console.error('  typeroll extension configure --site <site-id> --installation <installation-id> --config config.json [--no-deploy]');
     console.error('  typeroll extension promote <version> [--manifest path]');
 }
@@ -193,24 +215,32 @@ export async function runExtensionCli(args) {
             return 0;
         }
         if (command === 'install') {
-            const siteId = option(args, '--site');
-            if (!siteId)
-                throw new Error('install requires --site <site-id>');
+            const siteOption = option(args, '--site');
+            if (!siteOption)
+                throw new Error('install requires --site <site-id> or --site <organization-id>/<site-id>');
+            const site = parseInstallSite(siteOption);
             const configPath = option(args, '--config');
             const config = configPath ? await readJson(configPath) : {};
             const permissions = Array.isArray(manifest.permissions) ? manifest.permissions : [];
             if (manifest.distribution === 'private') {
+                if (!site.ownerOrgId) {
+                    console.error(`Note: allowed_site_ids entry "${site.allowEntry}" only allows a site of your developer organization. `
+                        + 'To allow a site of another organization, pass --site <organization-id>/<site-id>.');
+                }
                 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)) {
+                if (!allowed.includes(site.allowEntry)) {
                     await api(`/api/developer/extensions/${encodeURIComponent(extensionId)}`, {
-                        method: 'PATCH', body: JSON.stringify({ allowed_site_ids: [...allowed, siteId] }),
+                        method: 'PATCH', body: JSON.stringify({ allowed_site_ids: [...allowed, site.allowEntry] }),
                     });
                 }
             }
-            const installed = await api(`/api/v1/sites/${encodeURIComponent(siteId)}/extensions`, {
+            // With `org/site`, declare the owner so the server refuses to resolve the
+            // id to a different organization's site of the same name.
+            const installed = await api(`/api/v1/sites/${encodeURIComponent(site.siteId)}/extensions`, {
                 method: 'POST',
+                headers: site.ownerOrgId ? { 'Typeroll-Organization': site.ownerOrgId } : undefined,
                 body: JSON.stringify({
                     extension_id: extensionId,
                     version: manifest.version,

package/dist/index.js

@@ -20,6 +20,7 @@ import { resolveSiteId } from './resolve-site-id.js';
 import { buildServer } from './server.js';
 import { VERSION } from './version.js';
 import { runExtensionCli } from './extension-cli.js';
+import { apiUrlProblem } from './api-url.js';
 import { doctor, readWorkspace, workspaceClient, verifyWorkspaceBinding } from './workspace.js';
 function bail(message) {
     console.error(`typeroll-mcp: ${message}`);
@@ -85,6 +86,9 @@ async function main() {
     const apiKey = process.env.TYPEROLL_API_KEY?.trim();
     if (!apiUrl)
         bail('TYPEROLL_API_URL is not set. Point it at your Typeroll portal (e.g. https://app.typeroll.com).');
+    const apiUrlError = apiUrlProblem(apiUrl);
+    if (apiUrlError)
+        bail(apiUrlError);
     if (!apiKey)
         bail('TYPEROLL_API_KEY is not set. Create a key in /app/sites/{siteId}/settings/api-keys and copy it once.');
     if (!apiKey.startsWith('typeroll_live_')) {

package/dist/server.js

@@ -97,6 +97,7 @@ function effectFor(name) {
         || name === 'revoke_site_share'
         || name === 'revoke_organization_api_key'
         || name === 'create_organization_invite'
+        || name === 'revoke_organization_invite'
         || name === 'set_organization_ai_key'
         || name === 'remove_organization_ai_key'
         || name === 'set_organization_ai_site_access'

package/dist/tools/access.js

@@ -6,10 +6,11 @@
 import { z } from 'zod';
 import { ok, withErrorBoundary } from './helpers.js';
 const keyId = z.string().regex(/^[a-f0-9]{12}$/).describe('Key id (the 12-hex prefix) from list_api_keys / list_organization_api_keys.');
+const inviteId = z.string().regex(/^[A-Za-z0-9_-]{16,64}$/).describe('Invite id from create_organization_invite or list_organization_invites.');
 export const accessTools = [
     {
         name: 'list_api_keys',
-        description: 'List this Site\'s site-scoped API keys: id (prefix), name, created_at/created_by, last_used_at/last_used_ip and revoked_at. Never returns secrets or hashes. Any key that reaches the Site may list, as in Site settings → API keys.',
+        description: 'List this Site\'s site-scoped API keys: id (prefix), name, created_at/created_by, last_used_at/last_used_ip and revoked_at. Never returns secrets or hashes. Requires admin on the Site, as in Site settings → API keys.',
         inputSchema: {},
         handler: withErrorBoundary(async (_args, { client, siteId }) => ok(await client.get(siteId, 'api-keys'))),
     },
@@ -69,10 +70,28 @@ export const accessTools = [
     {
         name: 'create_organization_invite',
         noSite: true,
-        description: 'Create a signed invite link to the Organization (organization API key required). The invited person opens invite_url, signs in and joins as an editor; the link works until expires_at (ttl_days 1–30, default 7) and cannot be revoked early. Send it only to the person the user named.',
-        inputSchema: { ttl_days: z.number().int().min(1).max(30).optional() },
+        description: 'Create a signed invite link to the Organization (organization API key required). The invited person opens invite_url, signs in and joins as an editor. The link works until expires_at (ttl_days 1–30, default 7) for max_uses people (1–50, default 1: single use); with email set, only a person signed in with that address can redeem it. Returns the invite id; list_organization_invites shows its state and revoke_organization_invite (or DELETE /api/v1/organization/invites/{id}) stops the link immediately. Send the link only to the person the user named.',
+        inputSchema: {
+            ttl_days: z.number().int().min(1).max(30).optional(),
+            max_uses: z.number().int().min(1).max(50).optional().describe('How many people may redeem the link. Default 1 (single use).'),
+            email: z.string().email().max(320).optional().describe('Bind the invite to this email address: only a person signed in with it can redeem the link.'),
+        },
         handler: withErrorBoundary(async (args, { client }) => ok(await client.rootPost('organization/invites', args))),
     },
+    {
+        name: 'list_organization_invites',
+        noSite: true,
+        description: 'List the Organization\'s invites, newest first, without their links: id, state (active | used | expired | revoked), role, email (when bound), created_by, created_at, expires_at, max_uses, used_count and revoked_at. Requires an organization API key; site-scoped keys get 403.',
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client }) => ok(await client.rootGet('organization/invites'))),
+    },
+    {
+        name: 'revoke_organization_invite',
+        noSite: true,
+        description: 'Revoke an Organization invite by id (from create_organization_invite or list_organization_invites). Its link stops working immediately; people who already joined keep their membership. Requires an organization API key.',
+        inputSchema: { invite_id: inviteId },
+        handler: withErrorBoundary(async (args, { client }) => ok(await client.rootDelete(`organization/invites/${encodeURIComponent(args.invite_id)}`))),
+    },
     {
         name: 'read_organization_ai_settings',
         noSite: true,

package/dist/tools/deploy.js

@@ -41,7 +41,7 @@ export const deployTools = [
     },
     {
         name: 'get_deploy_status',
-        description: "Status of a single deploy job. Optional top-level build_progress reports the exact task status, attempt, step and completed/total files; not an overall percentage or ETA. Returns { job, queued_for_seconds, queue_timeout_seconds }. job.status is one of queued | running | succeeded | failed. On a failed build, job.error names the failed step and the cause the step printed, job.failure.code is the reported code (e.g. media_build_process_exit_1) and job.failure.diagnostic holds { cause, lines } (the last 40 lines that step printed, credentials removed). On the Cloudflare build engine job.failure.provider_log also holds { step, build_id, summary, lines } from the provider's build log (last 60 lines). Read them before retrying; retrying does not fix a cause that is in the content or the build engine. Polling cadence: ~5s for queued/running. job.render_report, when present, reports actual HTML mode (full/partial), rendered, reused, total and removed route counts plus a fallback reason. From Core 0.2.17, custom blocks and consumed image metadata are tracked per route; older caches require one full build. It does not measure media or provider startup savings. job.coordinator, when present, reports the last completed CMS phase and duration_ms for that attempt; external build waiting is excluded. Keep observing the same job across checkpoints; do not trigger duplicate deploys. A job stuck in 'queued' for longer than queue_timeout_seconds (default 300s) auto-flips to failed with phase='queue_timeout' — so a single poll past that timestamp returns the terminal state and you can stop polling.",
+        description: "Status of a single deploy job. Optional top-level build_progress reports the exact task status, attempt, step and completed/total files; not an overall percentage or ETA. Returns { job, queued_for_seconds, queue_timeout_seconds }. job.status is one of queued | running | succeeded | failed. On a failed build, job.error names the failed step and the cause the step printed, job.failure.code is the reported code (e.g. media_build_process_exit_1) and job.failure.diagnostic holds { cause, lines } (the last 40 lines that step printed, credentials removed). On the Cloudflare build engine job.failure.provider_log also holds { step, build_id, summary, lines } from the provider's build log (last 60 lines). Read them before retrying; retrying does not fix a cause that is in the content or the build engine. job.warnings, when present, lists non-blocking findings of a deploy that still ran, for example a media file left out of the publication because it could not be published safely (an SVG that could not be sanitized); report them to the user. Polling cadence: ~5s for queued/running. job.render_report, when present, reports actual HTML mode (full/partial), rendered, reused, total and removed route counts plus a fallback reason. From Core 0.2.17, custom blocks and consumed image metadata are tracked per route; older caches require one full build. It does not measure media or provider startup savings. job.coordinator, when present, reports the last completed CMS phase and duration_ms for that attempt; external build waiting is excluded. Keep observing the same job across checkpoints; do not trigger duplicate deploys. A job stuck in 'queued' for longer than queue_timeout_seconds (default 300s) auto-flips to failed with phase='queue_timeout' — so a single poll past that timestamp returns the terminal state and you can stop polling.",
         inputSchema: { job_id: z.string(), include_provider: z.boolean().optional().describe('Also read the exact Git commit and Cloudflare build stages for a customer Git publication. Does not return build secrets.') },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const res = await client.get(siteId, `deploys/${encodeURIComponent(args.job_id)}`);

package/dist/tools/extensions.js

@@ -142,21 +142,21 @@ export const developerExtensionTools = [
     },
     {
         name: 'read_developer_extension', noSite: true,
-        description: 'Read one of your organization\'s Extensions with all saved releases and their status (draft, review, published, deprecated, revoked). Requires an organization API key.',
+        description: 'Read one of your organization\'s Extensions with all saved releases and their status (draft, review, published, deprecated, revoked). extension.developer_org_id is the value of the developer_org_id claim in every token Typeroll issues for its installations: provider backends must require it in addition to aud. id_reservation is reserved, unreserved (a registration that predates reservations; any update claims it) or held_by_other (another developer organization holds this id). Requires an organization API key.',
         inputSchema: { extension_id: z.string().min(1) },
         handler: withErrorBoundary(async (args, { client }) => ok(await client.developer('GET', ext(args.extension_id)))),
     },
     {
         name: 'update_developer_extension', noSite: true,
-        description: 'Update an Extension\'s name, status (active/suspended), distribution (only while every release is a draft), trusted origins or private allow-lists. Requires an organization API key.',
+        description: 'Update an Extension\'s name, status (active/suspended), distribution (only while every release is a draft), trusted origins or private allow-lists. Each list replaces the saved one: allowed_org_ids allows every Site of those Organizations; allowed_site_ids entries are "<organization-id>/<site-id>" for a Site of another Organization, while a bare site id only matches a Site of your own developer Organization. Requires an organization API key.',
         inputSchema: {
             extension_id: z.string().min(1),
             name: z.string().optional(),
             status: z.enum(['active', 'suspended']).optional(),
             distribution: z.enum(['private', 'unlisted', 'public']).optional(),
             trusted_origins: z.array(z.string()).optional(),
-            allowed_org_ids: z.array(z.string()).optional(),
-            allowed_site_ids: z.array(z.string()).optional(),
+            allowed_org_ids: z.array(z.string()).optional().describe('Organization ids whose every Site may install this private Extension. Replaces the saved list.'),
+            allowed_site_ids: z.array(z.string().max(257)).max(500).optional().describe('Sites that may install this private Extension, replacing the saved list: "<organization-id>/<site-id>" for another Organization\'s Site, or a bare site id for a Site of your own developer Organization.'),
         },
         handler: withErrorBoundary(async (args, { client }) => {
             const { extension_id, ...patch } = args;

package/dist/tools/forms.js

@@ -149,7 +149,7 @@ export const formTools = [
     },
     {
         name: 'list_form_submissions',
-        description: 'List submissions received for a form, newest first, cursor-paginated (cap 200 per page). Admins also see each submission\'s webhook delivery status. Use this to help a customer triage inbound contact / lead submissions; read_form_submission reads one.',
+        description: 'List submissions received for a form, newest first, cursor-paginated (cap 200 per page). Admins also see each submission\'s webhook delivery status. Visitor IP addresses are not stored or returned; completed submissions past the site\'s form_submission_retention_days (read_site_settings) are deleted and never listed. Use this to help a customer triage inbound contact / lead submissions; read_form_submission reads one.',
         inputSchema: {
             form_id: z.string(),
             limit: z.number().int().min(1).max(200).optional(),
@@ -163,7 +163,7 @@ export const formTools = [
     },
     {
         name: 'read_form_submission',
-        description: 'Read one submission of a form by id (from list_form_submissions): the submitted values, status (partial or complete), step and timestamps. Admins also see its webhook delivery status, as in the portal.',
+        description: 'Read one submission of a form by id (from list_form_submissions): the submitted values, status (partial or complete), step and timestamps, with expires_at when the submission is due for deletion. Admins also see its webhook delivery status, as in the portal.',
         inputSchema: {
             form_id: z.string(),
             submission_id: z.string(),

package/dist/tools/media.js

@@ -67,8 +67,8 @@ export const mediaTools = [
         name: 'create_upload_url',
         description: 'Mint a 5-min signed PUT URL for direct-to-R2 upload. After the upload completes, the CDN url is what you reference in <img src="…">. REQUIRED follow-up: call `finalize_media` after the PUT succeeds — without it the original ships with no Cache-Control (Lighthouse will flag it) and no responsive variants get generated. The response carries `finalize_url` as a reminder. This signed-PUT path is the INTEGRITY-SAFE way to upload bytes from disk or a generated asset — a direct `curl --data-binary @file` sends the bytes straight to R2 without transcribing them through the model, so it can\'t be corrupted the way a large `upload_media_inline` base64 blob can (ESPECIALLY use this, not inline, for SVG/logos). For a public source URL, `upload_media_from_url` is the one-call equivalent; reserve `upload_media_inline` for tiny payloads only.',
         inputSchema: {
-            filename: z.string().min(1),
-            content_type: z.string().min(1).describe('e.g. "image/png", "image/jpeg", "application/pdf"'),
+            filename: z.string().min(1).describe('Should end in an extension of content_type (e.g. logo.png with image/png). When the extension is missing or belongs to another type, the type\'s extension is appended (logo → logo.png, photo.html → photo.html.png); the response returns the stored filename. Unsupported types answer 415.'),
+            content_type: z.string().min(1).describe('e.g. "image/png", "image/jpeg", "application/pdf". SVGs are sanitized at finalize; an SVG that cannot be sanitized is refused.'),
             size: z.number().int().nonnegative().optional(),
             alt_text: z.string().optional(),
         },
@@ -82,7 +82,7 @@ export const mediaTools = [
         description: 'Fetch an image (or PDF) from any public URL and push it to the site\'s media library in one call. The MCP server downloads the source from verified public HTTP(S) destinations; private addresses and unsafe redirects are refused. Integrity-safe: the bytes are streamed, never transcribed as base64 through the model, so (unlike a large `upload_media_inline` payload) they can\'t be silently corrupted in transit. Returns { media_id, cdn_url, filename }.',
         inputSchema: {
             source_url: z.string().url().describe('Public URL to download the image from.'),
-            filename: z.string().optional().describe('Override the filename used on R2. Defaults to the last path segment of source_url.'),
+            filename: z.string().optional().describe('Override the filename used on R2. Defaults to the last path segment of source_url. When its extension does not match the content type, the type\'s extension is appended; the response returns the stored filename.'),
             content_type: z.string().optional().describe('Override the inferred content type (e.g. when source_url has no extension).'),
             alt_text: z.string().optional(),
         },
@@ -131,7 +131,7 @@ export const mediaTools = [
         name: 'upload_media_inline',
         description: 'Upload an image (or PDF) from base64-encoded bytes. ⚠️ Use ONLY for tiny payloads (a few KB). The base64 string crosses the model/tool boundary as text, where a larger blob can be SILENTLY CORRUPTED in transit — a few mutated chars yield a broken-but-valid-looking file that uploads with no error and the right size, and only fails when rendered (this has bitten a ~12KB logo SVG: half the wordmark vanished). For anything non-trivial, and ALWAYS for SVG/logos or assets you generated, prefer create_upload_url + a direct curl --data-binary PUT of the file bytes (bytes never transcribed → verified byte-identical), or upload_media_from_url (bytes fetched from a URL). After uploading any generated asset, VERIFY it (render it, or byte-diff against the source) before referencing it. Returns { media_id, cdn_url, filename }.',
         inputSchema: {
-            filename: z.string().min(1),
+            filename: z.string().min(1).describe('When its extension does not match content_type, the type\'s extension is appended; the response returns the stored filename.'),
             content_type: z.string().min(1).describe('e.g. "image/png", "image/jpeg", "application/pdf"'),
             data_base64: z.string().min(1).describe('The file bytes, base64-encoded (without a data: URL prefix).'),
             alt_text: z.string().optional(),
@@ -172,7 +172,7 @@ export const mediaTools = [
             return ok({
                 media_id: mint.media_id,
                 cdn_url: mint.cdn_url,
-                filename: args.filename,
+                filename: mint.filename ?? args.filename,
                 content_type: args.content_type,
                 size_bytes: buf.byteLength,
                 finalize: finalizeResult,
@@ -182,7 +182,7 @@ export const mediaTools = [
     },
     {
         name: 'update_media',
-        description: 'Patch a media item\'s alt text, filename or public path. A public path change is applied at the next publication.',
+        description: 'Patch a media item\'s alt text, filename or public path. A rename must be correct: a new filename or public path must end in an extension matching the file\'s type, and nothing is appended (400 media_extension_mismatch otherwise). A public path change is applied at the next publication.',
         inputSchema: {
             media_id: z.string(),
             alt_text: z.string().optional(),

package/dist/tools/settings.js

@@ -28,7 +28,7 @@ export const settingsTools = [
     },
     {
         name: 'read_site_settings',
-        description: "Read every site setting: name, tagline, logo, favicon/app icons, colors, fonts, contact info, social links, URL trailing-slash policy, iframe host allowlist, default SEO suffix/description, default_og_image, twitter_handle, organization (JSON-LD), language, robots_txt, image_sizes_default, cookie_consent, plus the scriptable surfaces scripts_head, scripts_body_end, and custom_css, `urls` (including `urls.staging`, the site's staging_url) and `render` (the site's platform render version, the latest version and what upgrading would change). Pass `version` to read a branch's settings (with copy-on-write chain-fallback to main for fields the branch hasn't overridden).",
+        description: "Read every site setting: name, tagline, logo, favicon/app icons, colors, fonts, contact info, social links, URL trailing-slash policy, iframe host allowlist, default SEO suffix/description, default_og_image, twitter_handle, organization (JSON-LD), language, robots_txt, image_sizes_default, cookie_consent, plus the scriptable surfaces scripts_head, scripts_body_end, and custom_css, form_submission_retention_days (days completed form submissions are kept before deletion; null = kept until deleted; site-wide, not per version), `urls` (including `urls.staging`, the site's staging_url) and `render` (the site's platform render version, the latest version and what upgrading would change). Pass `version` to read a branch's settings (with copy-on-write chain-fallback to main for fields the branch hasn't overridden).",
         inputSchema: {
             version: versionParam,
         },
@@ -47,6 +47,7 @@ export const settingsTools = [
             'scripts_head / scripts_body_end / custom_css and cookie_consent scripts ARE writable here — useful for a global stylesheet or analytics tag across all pages. ' +
             'Social sharing and structured data: default_og_image, twitter_handle, organization ({name, logo, same_as[]}, replaced as a whole; null clears). ' +
             'staging_url is stored on the Site (not per version), so it applies whichever `version` you pass. ' +
+            'form_submission_retention_days is also site-wide and deletes data: set it only when the user asks for a retention period. ' +
             'Pass `version` to scope the write to a branch (copy-on-write) instead of main — the right way to brand/recolor a site inside a redesign branch (colors, fonts, logo, custom_css) without touching the live settings. Omit it to write main.',
         inputSchema: {
             version: versionParam,
@@ -81,6 +82,7 @@ export const settingsTools = [
                 same_as: z.array(z.string()).max(50).optional().describe('Profile URLs (LinkedIn, X, Facebook, …) emitted as sameAs.'),
             }).strict().nullable().optional().describe('Organization schema.org JSON-LD emitted on every page. Replaces the stored value as a whole; null (or all-empty) clears it.'),
             staging_url: z.string().nullable().optional().describe('URL of a staging environment for this site, reported as urls.staging. Stored on the Site, not per version. Trailing slashes are dropped; empty string or null clears.'),
+            form_submission_retention_days: z.number().int().min(30).max(3650).nullable().optional().describe('Opt-in deletion of completed form submissions this many days (30–3650) after they were completed, on every form of the site, including existing submissions: those already older are deleted immediately and cannot be restored. null (the default) keeps submissions until someone deletes them. Site administrators only (never an Extension credential); stored on the Site, not per version. The response reports form_submission_retention { updated, deleted }. Partial submissions keep their form\'s partial_ttl_days.'),
             render_version: z.number().int().min(1).optional().describe('Platform render version. Platform output changes ship as new versions so existing sites never change look on their own. Upgrade only after previewing (get_preview_link render_version) and with the user\'s approval; the tr-upgrade-rendering skill compares every page. Lowering it returns to an earlier version.'),
             design_scales: z.record(z.string(), z.record(z.string(), z.string())).optional().describe('Site token scales (replaced as a whole): type_size xs/sm/md/lg/xl/2xl/3xl; space none/xs/sm/md/lg/xl in px/rem/em; leading tight/snug/normal/relaxed/loose as unitless 1–2. Omitted steps use platform defaults.'),
             colors: z.record(z.string(), z.string().nullable()).optional().describe('Palette: primary, secondary, accent, background, surface, surface_hover, text, text_light (shallow-merged). Optional on_primary, on_secondary, on_accent set the text colour on that theme colour (buttons, badges, tabs, call-to-action sections, styles using the on_* tokens) as a hex colour such as "#ffffff"; null returns to the automatic black or white (chosen by APCA from render version 8, by the WCAG 2 ratio before). A chosen on_* colour applies on every render version. The response lists `on_colors` with each one\'s APCA Lc and WCAG 2 ratio; a choice below APCA Lc 60 (button text, 16px/600) is kept and returned as a warning. Prefer the automatic choice unless the brand specifies a colour.'),

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.45.82';
+export const VERSION = '0.45.84';

package/dist/workspace.js

@@ -5,12 +5,12 @@ import { z } from 'zod';
 import { VERSION } from './version.js';
 import { BUNDLED_WORKSPACE_TEMPLATES } from './bundled-content.js';
 import { ApiError, TyperollClient } from './client.js';
+import { isSecureApiUrl } from './api-url.js';
 export const workspaceSchema = z.object({
     schema_version: z.literal(1),
     portal: z.string().url().refine(value => {
         const url = new URL(value);
-        return !url.username && !url.password && !url.search && !url.hash && url.pathname === '/' &&
-            (url.protocol === 'https:' || (url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)));
+        return !url.username && !url.password && !url.search && !url.hash && url.pathname === '/' && isSecureApiUrl(url);
     }, 'Use an HTTPS portal origin (HTTP is allowed only on loopback).'),
     organization_id: z.string().min(1).nullable(), site_id: z.string().min(1).nullable(),
     version: z.string().min(1), tool_mode: z.enum(['compact', 'full']),
@@ -186,11 +186,32 @@ export async function writeWorkspaceFiles(dir, templates, update) {
     await fs.writeFile(lockFile, JSON.stringify({ schema_version: 1, generator_version: VERSION, files }, null, 2) + '\n');
     return results;
 }
+/** The hosted Typeroll Cloud portal: the only origin trusted from typeroll.json alone. */
+export const OFFICIAL_PORTAL_ORIGIN = 'https://app.typeroll.com';
+/** Raised before any credential is sent when the committed portal is not confirmed by the environment. */
+export class UntrustedPortalError extends Error {
+}
+/**
+ * typeroll.json is committed and can be changed by anyone who can open a pull
+ * request, so its portal alone never receives the injected API key. Another
+ * origin must be confirmed through the private TYPEROLL_API_URL setting.
+ */
+export function assertTrustedPortal(config, env) {
+    const portal = config.portal.replace(/\/$/, '');
+    const confirmed = env.TYPEROLL_API_URL?.trim().replace(/\/$/, '');
+    if (confirmed) {
+        if (confirmed !== portal)
+            throw new Error('TYPEROLL_API_URL conflicts with typeroll.json.');
+        return;
+    }
+    if (portal !== OFFICIAL_PORTAL_ORIGIN) {
+        throw new UntrustedPortalError(`typeroll.json names the portal ${portal}. The API key is sent only to ${OFFICIAL_PORTAL_ORIGIN} unless you confirm another portal: set TYPEROLL_API_URL=${portal} in your private client settings or environment.`);
+    }
+}
 export function workspaceClient(config, env, fetchImpl) {
     if (!env.TYPEROLL_API_KEY)
         throw new Error('Inject TYPEROLL_API_KEY through private client settings or the environment.');
-    if (env.TYPEROLL_API_URL && env.TYPEROLL_API_URL.replace(/\/$/, '') !== config.portal.replace(/\/$/, ''))
-        throw new Error('TYPEROLL_API_URL conflicts with typeroll.json.');
+    assertTrustedPortal(config, env);
     if (env.TYPEROLL_SITE_ID && env.TYPEROLL_SITE_ID !== config.site_id)
         throw new Error('TYPEROLL_SITE_ID conflicts with typeroll.json.');
     return new TyperollClient({ baseUrl: config.portal, apiKey: env.TYPEROLL_API_KEY, defaultVersion: config.version, fetchImpl });
@@ -229,7 +250,7 @@ export async function doctor(dir, offline, env = process.env, fetchImpl) {
             checks.push({ check: 'writes_and_publishing', status: 'not_checked', message: 'Read-only doctor. No edits, media transfer, app activation or publication was attempted; check publishing/import readiness for those tasks.' });
         }
         catch (error) {
-            checks.push({ check: 'connection', status: 'required', message: error instanceof ApiError ? `Portal HTTP ${error.status}. Check credential scope, portal and Site/Version.` : 'Could not verify the connection. Check injected credentials, matching environment, network and Site/Version.' });
+            checks.push({ check: 'connection', status: 'required', message: error instanceof ApiError ? `Portal HTTP ${error.status}. Check credential scope, portal and Site/Version.` : error instanceof UntrustedPortalError ? error.message : 'Could not verify the connection. Check injected credentials, matching environment, network and Site/Version.' });
         }
     }
     return { passed: !checks.some(check => check.status === 'required'), generator_version: VERSION, checks };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.45.82",
+  "version": "0.45.84",
   "description": "Typeroll CMS MCP server \u2013 connect AI agents to the REST API to manage content and publish static websites.",
   "license": "MIT",
   "repository": {

package/workspace-templates/scripts/README.md

@@ -13,7 +13,8 @@ npx playwright install chromium
 Run the commands below from the **workspace root**. Inject TYPEROLL_API_KEY through
 your private credential manager. Never put it in a file or command argument.
 trlib.py reads portal, organization_id, site_id and version from typeroll.json,
-checks the connected Site/Organization, discovers the live tool schema, and
+sends the key only to https://app.typeroll.com or to a portal you confirm by
+setting TYPEROLL_API_URL to the same origin privately, checks the connected Site/Organization, discovers the live tool schema, and
 passes the Version where supported. It refuses unversioned operations on a
 non-main binding; use the explicit interactive API workflow for organization or
 shared media operations instead. It is a small hosted MCP helper for API keys,

package/workspace-templates/scripts/typeroll/trlib.py

@@ -31,6 +31,28 @@ def workspace():
     raise ValueError('Run from a workspace containing typeroll.json')
 
 
+OFFICIAL_PORTAL = 'https://app.typeroll.com'
+
+
+def trusted_portal(config):
+    """Return the portal origin that may receive the API key.
+
+    typeroll.json is committed, so its portal alone is trusted only when it is
+    the hosted portal. Another origin must be confirmed by TYPEROLL_API_URL.
+    """
+    portal = config['portal'].rstrip('/')
+    confirmed = (os.environ.get('TYPEROLL_API_URL') or '').strip().rstrip('/')
+    if confirmed:
+        if confirmed != portal:
+            raise ValueError('TYPEROLL_API_URL conflicts with typeroll.json')
+        return portal
+    if portal != OFFICIAL_PORTAL:
+        raise ValueError(f'typeroll.json names the portal {portal}. The API key is sent only to '
+                         f'{OFFICIAL_PORTAL} unless you confirm another portal: set '
+                         f'TYPEROLL_API_URL={portal} in your private environment')
+    return portal
+
+
 class Client:
     def __init__(self, config=None):
         self.config = config or workspace()
@@ -51,6 +73,8 @@ class Client:
         key = os.environ.get('TYPEROLL_API_KEY')
         if not key:
             raise ValueError('Inject TYPEROLL_API_KEY privately before running')
+        if trusted_portal(self.config) + '/api/mcp?tools=full' != self.url:
+            raise ValueError('Workspace portal changed after the client was created')
         headers = {'Authorization': 'Bearer ' + key, 'Content-Type': 'application/json',
                    'Accept': 'application/json, text/event-stream'}
         if self.session: