@pitcher/cli-scripts 2.18.0 → 2.20.0

package/dist/src/core/credential.js

@@ -0,0 +1,25 @@
+import { resolveApiKey } from './auth.js';
+import { createCliError } from './errors.js';
+/** The auth header(s) for a credential. Exactly one header, never both. */
+export function authHeaders(c) {
+    return c.kind === 'bearer' ? { authorization: `Bearer ${c.token}` } : { 'x-api-key': c.key };
+}
+/**
+ * The ONE credential resolver every call site uses.
+ *
+ * An explicit `credential` always wins and never falls through: a bearer context must fail CLOSED,
+ * so it can never pick up `--api-key` or `NG_API_KEY` from the process env (the hosted server
+ * would otherwise act as whoever minted that key). Only when no credential is given (CLI / stdio)
+ * does this reach `resolveApiKey`, which reads `--api-key` then `NG_API_KEY`.
+ */
+export function credentialOf(opts) {
+    const c = opts.credential;
+    if (c) {
+        const value = c.kind === 'bearer' ? c.token : c.key;
+        if (typeof value !== 'string' || !value.trim()) {
+            throw createCliError('AUTH', `Empty ${c.kind === 'bearer' ? 'bearer token' : 'API key'} credential`);
+        }
+        return c;
+    }
+    return { kind: 'apiKey', key: resolveApiKey(opts) };
+}

package/dist/src/core/http.d.ts

@@ -1,8 +1,13 @@
 import { type AxiosInstance } from 'axios';
+import { type Credential } from './credential.js';
 import { type CliError } from './errors.js';
-export declare function makeClient(baseUrl: string, apiKey: string): AxiosInstance;
+export declare function makeClient(baseUrl: string, cred: Credential, opts?: {
+    maxRedirects?: number;
+}): AxiosInstance;
 export interface CommonOpts {
     apiKey?: string;
+    /** Explicit credential (hosted MCP: a user's bearer token). Wins over `apiKey`/`NG_API_KEY` — see `credentialOf`. */
+    credential?: Credential;
     org?: string;
     url?: string;
     quiet?: boolean;

package/dist/src/core/http.js

@@ -1,19 +1,20 @@
 import axios from 'axios';
-import { resolveApiKey } from './auth.js';
 import { resolveBaseUrl } from './baseUrl.js';
+import { authHeaders, credentialOf } from './credential.js';
 import { createCliError, isCliError } from './errors.js';
-export function makeClient(baseUrl, apiKey) {
+export function makeClient(baseUrl, cred, opts = {}) {
     return axios.create({
+        ...opts,
         baseURL: baseUrl,
         headers: {
             accept: 'application/json',
-            'x-api-key': apiKey,
+            ...authHeaders(cred),
         },
     });
 }
 /** Resolve auth + base URL into a client, or use an injected one (tests). */
 export function clientFor(opts, deps = {}) {
-    return deps.client ?? makeClient(resolveBaseUrl({ org: opts.org, url: opts.url }), resolveApiKey(opts));
+    return deps.client ?? makeClient(resolveBaseUrl({ org: opts.org, url: opts.url }), credentialOf(opts));
 }
 export const CLICKHOUSE_API_BASE_URL = 'https://clickhouse.pitcher.com';
 /**
@@ -30,7 +31,7 @@ export function clickhouseClientFor(opts, deps = {}) {
         baseURL: CLICKHOUSE_API_BASE_URL,
         headers: {
             accept: 'application/json',
-            'x-api-key': resolveApiKey(opts),
+            ...authHeaders(credentialOf(opts)),
             'x-original-domain': originalDomain,
         },
     });

package/dist/src/core/ld.d.ts

@@ -1,4 +1,4 @@
-import type { AxiosInstance } from 'axios';
+import { type AxiosInstance } from 'axios';
 import { type CommonOpts } from './http.js';
 import { type CliError } from './errors.js';
 export interface LdCommonOpts extends CommonOpts {
@@ -8,7 +8,17 @@ export interface LdCommonOpts extends CommonOpts {
 export interface LdDeps {
     ldClient?: AxiosInstance;
     platformClient?: AxiosInstance;
+    /** Test seam for the bearer → L&D token exchange POST (`{ldBase}/auth/token`). */
+    ldAuthClient?: AxiosInstance;
 }
+/** The exact hosts a bearer credential may be sent to. An unusable `LD_ALLOWED_HOSTS` entry fails closed. */
+export declare function ldAllowedHosts(env?: NodeJS.ProcessEnv): Set<string>;
+/**
+ * Resolved L&D base URL per (platform host, instance). Bounded in TIME, not just per process: the
+ * hosted MCP server is one long-lived process, so an admin re-pointing an instance's ld-app
+ * `api_base_url` must take effect without a restart.
+ */
+export declare const LD_BASE_URL_TTL_MS: number;
 /** Test-only: reset the resolved-base-URL cache between cases. */
 export declare function __clearLdBaseUrlCache(): void;
 /** Every L&D run* requires an instance; returns it narrowed to string, else VALIDATION. */
@@ -29,7 +39,33 @@ export declare function pickTruthy<T extends object>(opts: T, keys: readonly (ke
  * over a credential the CLI actually holds.
  */
 export declare function resolveLdBaseUrl(opts: LdCommonOpts, deps?: LdDeps, env?: NodeJS.ProcessEnv): Promise<string>;
-/** Build (or inject, in tests) an axios client pointed at the resolved L&D Lambda base. */
+/** Max cached L&D tokens (one per distinct Pitcher token × L&D base). Oldest-used evicted first. */
+export declare const LD_TOKEN_CACHE_MAX = 500;
+/** Test-only: reset the L&D token-exchange cache between cases. */
+export declare function __clearLdTokenCache(): void;
+/** Test-only: current number of cached L&D tokens. */
+export declare function __ldTokenCacheSize(): number;
+/**
+ * The client that POSTs the user's token. `maxRedirects: 0` is load-bearing: axios follows 307/308 and
+ * RE-SENDS the body, so an allowlisted host answering 307 would forward the token to any host it names —
+ * straight past the allowlist. A 3xx is therefore a failed exchange (non-2xx), never followed.
+ */
+export declare function createLdAuthHttp(): AxiosInstance;
+/**
+ * Exchange a Pitcher (Auth0) access token for an L&D JWT at `POST {ldBase}/auth/token {token}`.
+ * The L&D envelope is `{ success, message, data: { token, refreshToken, user }, statusCode }`, so the
+ * JWT is at `res.data.data.token` (ld-app `authController.ts`).
+ *
+ * Cached until `min(L&D exp, Pitcher exp) − 60 s`: the L&D JWT embeds the Pitcher token, so it is
+ * useless once that expires, and its own lifetime is env-configurable (`JWT_EXPIRES_IN`), so neither
+ * is assumed. A token whose TTL cannot be read, or is already ≤ 0, is used once and not cached.
+ */
+export declare function exchangeLdToken(ldBase: string, pitcherToken: string, deps: LdDeps, env: NodeJS.ProcessEnv): Promise<string>;
+/**
+ * Build (or inject, in tests) an axios client pointed at the resolved L&D Lambda base.
+ * API key → sent as-is (`x-api-key`). Bearer → exchanged for an L&D JWT first (the Lambda does not
+ * accept an Auth0 token directly), and that JWT is sent as the bearer.
+ */
 export declare function ldClientFor(opts: LdCommonOpts, deps?: LdDeps, env?: NodeJS.ProcessEnv): Promise<AxiosInstance>;
 /**
  * Unwrap the L&D success envelope `{ success, data, message? }` to its resource payload.

package/dist/src/core/ld.js

@@ -1,4 +1,6 @@
-import { resolveApiKey } from './auth.js';
+import axios from 'axios';
+import { createHash } from 'crypto';
+import { credentialOf } from './credential.js';
 import { clientFor, makeClient, toCliError } from './http.js';
 import { resolveBaseUrl } from './baseUrl.js';
 import { createCliError } from './errors.js';
@@ -41,6 +43,50 @@ const LD_FALLBACK_BASE_URL = 'https://cgmfr9gjza.execute-api.eu-west-1.amazonaws
  * what points each instance at it — the fallback must never silently stand in.
  */
 const LD_FALLBACK_PLATFORM_ORIGIN = 'https://dev.my.pitcher.com';
+/**
+ * Bearer mode (the hosted MCP server) sends the USER's Pitcher Auth0 access token to
+ * `POST {ldBase}/auth/token`. `ldBase` can come from `metadata.api_base_url`, which any
+ * instance admin can write — so without a gate an admin could point it at a host they own and
+ * collect every user's token (plus SSRF from the server). In bearer mode the resolved base
+ * must therefore be `https:` on an EXACT allowlisted host (no port, no wildcard, no suffix
+ * match — anyone can mint a `*.execute-api` host). Default = the fallback Lambda's host;
+ * `LD_ALLOWED_HOSTS` (comma-separated exact hostnames) extends it. API-key mode is unchanged.
+ */
+const LD_DEFAULT_ALLOWED_HOST = new URL(LD_FALLBACK_BASE_URL).host;
+/** The exact hosts a bearer credential may be sent to. An unusable `LD_ALLOWED_HOSTS` entry fails closed. */
+export function ldAllowedHosts(env = process.env) {
+    const hosts = new Set([LD_DEFAULT_ALLOWED_HOST]);
+    for (const raw of (env.LD_ALLOWED_HOSTS ?? '').split(',')) {
+        const entry = raw.trim().toLowerCase();
+        if (!entry)
+            continue;
+        if (!/^[a-z0-9-]+(\.[a-z0-9-]+)+$/.test(entry)) {
+            throw createCliError('VALIDATION', `LD_ALLOWED_HOSTS entries must be exact hostnames (no wildcard/port/scheme): ${entry}`);
+        }
+        hosts.add(entry);
+    }
+    return hosts;
+}
+/**
+ * Fail CLOSED unless `url` is safe to receive a bearer token. The message names the host, never the
+ * token. Called at resolution AND immediately before the exchange POST (defence in depth).
+ */
+function assertBearerLdBase(url, env) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw createCliError('VALIDATION', 'LD_HOST_NOT_ALLOWED: the L&D base URL is not a valid URL');
+    }
+    if (parsed.protocol !== 'https:') {
+        throw createCliError('VALIDATION', `LD_HOST_NOT_ALLOWED: the L&D base URL must be https (got ${parsed.protocol})`);
+    }
+    if (!ldAllowedHosts(env).has(parsed.host)) {
+        throw createCliError('VALIDATION', `LD_HOST_NOT_ALLOWED: ${parsed.host} is not an allowed L&D host for a signed-in user. ` +
+            `Add it to LD_ALLOWED_HOSTS on the server if it is a genuine L&D deployment.`);
+    }
+}
 /**
  * Safety stop for the installed-apps scan. At 500 records/page this is 10k apps in one
  * instance — unreachable in practice, so tripping it means the server kept advertising a
@@ -51,6 +97,12 @@ const MAX_APP_PAGES = 20;
 function isRecord(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
+/**
+ * Resolved L&D base URL per (platform host, instance). Bounded in TIME, not just per process: the
+ * hosted MCP server is one long-lived process, so an admin re-pointing an instance's ld-app
+ * `api_base_url` must take effect without a restart.
+ */
+export const LD_BASE_URL_TTL_MS = 10 * 60000;
 const baseUrlCache = new Map();
 /** Test-only: reset the resolved-base-URL cache between cases. */
 export function __clearLdBaseUrlCache() {
@@ -176,6 +228,13 @@ async function fetchLdAppMetadata(platform, instanceId) {
  * over a credential the CLI actually holds.
  */
 export async function resolveLdBaseUrl(opts, deps = {}, env = process.env) {
+    const url = await resolveLdBaseUrlUnchecked(opts, deps, env);
+    // Every source (flag, env, instance metadata, fallback, cache) is checked, on every call.
+    if (opts.credential?.kind === 'bearer')
+        assertBearerLdBase(url, env);
+    return url;
+}
+async function resolveLdBaseUrlUnchecked(opts, deps, env) {
     const override = opts.ldUrl?.trim() || env.NG_LD_API_URL?.trim();
     if (override)
         return trimUrl(override, opts.ldUrl ? '--ld-url' : 'NG_LD_API_URL');
@@ -186,8 +245,8 @@ export async function resolveLdBaseUrl(opts, deps = {}, env = process.env) {
     // different platform hosts collide on one cached L&D URL within a single process.
     const cacheKey = `${opts.url ?? opts.org ?? 'dev'}:${opts.instanceId}`;
     const cached = baseUrlCache.get(cacheKey);
-    if (cached)
-        return cached;
+    if (cached && cached.expiresAt > Date.now())
+        return cached.url;
     const platform = deps.platformClient ?? clientFor(opts);
     const metadata = await fetchLdAppMetadata(platform, opts.instanceId);
     if (!metadata) {
@@ -209,15 +268,112 @@ export async function resolveLdBaseUrl(opts, deps = {}, env = process.env) {
         }
         url = LD_FALLBACK_BASE_URL;
     }
-    baseUrlCache.set(cacheKey, url);
+    baseUrlCache.set(cacheKey, { url, expiresAt: Date.now() + LD_BASE_URL_TTL_MS });
     return url;
 }
-/** Build (or inject, in tests) an axios client pointed at the resolved L&D Lambda base. */
+/** Max cached L&D tokens (one per distinct Pitcher token × L&D base). Oldest-used evicted first. */
+export const LD_TOKEN_CACHE_MAX = 500;
+/** Safety margin subtracted from the earliest expiry, so a cached token is never used at the edge. */
+const LD_TOKEN_SKEW_MS = 60000;
+/**
+ * Bearer → L&D token cache, keyed `sha256(pitcherToken)|ldBase` (the raw token is never a key).
+ * A `Map` iterates in insertion order, so re-inserting on hit makes the first key the LRU one.
+ */
+const ldTokenCache = new Map();
+/** Test-only: reset the L&D token-exchange cache between cases. */
+export function __clearLdTokenCache() {
+    ldTokenCache.clear();
+}
+/** Test-only: current number of cached L&D tokens. */
+export function __ldTokenCacheSize() {
+    return ldTokenCache.size;
+}
+/** `exp` (seconds) of a JWT, read WITHOUT verification — only ever used to bound a cache TTL. */
+function jwtExpMs(token) {
+    const payload = token.split('.')[1];
+    if (!payload)
+        return undefined;
+    try {
+        const exp = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8')).exp;
+        return typeof exp === 'number' && Number.isFinite(exp) ? exp * 1000 : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The client that POSTs the user's token. `maxRedirects: 0` is load-bearing: axios follows 307/308 and
+ * RE-SENDS the body, so an allowlisted host answering 307 would forward the token to any host it names —
+ * straight past the allowlist. A 3xx is therefore a failed exchange (non-2xx), never followed.
+ */
+export function createLdAuthHttp() {
+    return axios.create({ headers: { accept: 'application/json' }, timeout: 10000, maxRedirects: 0 });
+}
+/**
+ * Exchange a Pitcher (Auth0) access token for an L&D JWT at `POST {ldBase}/auth/token {token}`.
+ * The L&D envelope is `{ success, message, data: { token, refreshToken, user }, statusCode }`, so the
+ * JWT is at `res.data.data.token` (ld-app `authController.ts`).
+ *
+ * Cached until `min(L&D exp, Pitcher exp) − 60 s`: the L&D JWT embeds the Pitcher token, so it is
+ * useless once that expires, and its own lifetime is env-configurable (`JWT_EXPIRES_IN`), so neither
+ * is assumed. A token whose TTL cannot be read, or is already ≤ 0, is used once and not cached.
+ */
+export async function exchangeLdToken(ldBase, pitcherToken, deps, env) {
+    // Re-checked at the point the token leaves, independent of how `ldBase` was obtained.
+    assertBearerLdBase(ldBase, env);
+    const key = `${createHash('sha256').update(pitcherToken).digest('hex')}|${ldBase}`;
+    const hit = ldTokenCache.get(key);
+    if (hit) {
+        ldTokenCache.delete(key);
+        if (hit.expiresAt > Date.now()) {
+            ldTokenCache.set(key, hit);
+            return hit.token;
+        }
+    }
+    let ldToken;
+    try {
+        const http = deps.ldAuthClient ?? createLdAuthHttp();
+        const res = await http.post(`${ldBase}/auth/token`, { token: pitcherToken });
+        ldToken = res.data?.data?.token;
+    }
+    catch (e) {
+        const err = toLdCliError(e);
+        throw createCliError('AUTH', `L&D token exchange failed: ${err.message}`);
+    }
+    if (typeof ldToken !== 'string' || !ldToken) {
+        throw createCliError('AUTH', 'L&D token exchange failed: no token in the /auth/token response');
+    }
+    const ldExp = jwtExpMs(ldToken);
+    const pitcherExp = jwtExpMs(pitcherToken);
+    if (ldExp !== undefined && pitcherExp !== undefined) {
+        const expiresAt = Math.min(ldExp, pitcherExp) - LD_TOKEN_SKEW_MS;
+        if (expiresAt > Date.now()) {
+            ldTokenCache.set(key, { token: ldToken, expiresAt });
+            while (ldTokenCache.size > LD_TOKEN_CACHE_MAX) {
+                const oldest = ldTokenCache.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                ldTokenCache.delete(oldest);
+            }
+        }
+    }
+    return ldToken;
+}
+/**
+ * Build (or inject, in tests) an axios client pointed at the resolved L&D Lambda base.
+ * API key → sent as-is (`x-api-key`). Bearer → exchanged for an L&D JWT first (the Lambda does not
+ * accept an Auth0 token directly), and that JWT is sent as the bearer.
+ */
 export async function ldClientFor(opts, deps = {}, env = process.env) {
     if (deps.ldClient)
         return deps.ldClient;
     const base = await resolveLdBaseUrl(opts, deps, env);
-    return makeClient(base, resolveApiKey(opts));
+    const cred = credentialOf(opts);
+    if (cred.kind === 'apiKey')
+        return makeClient(base, cred);
+    // No redirects for a bearer either: the L&D JWT embeds the user's Pitcher token.
+    const ldToken = await exchangeLdToken(base, cred.token, deps, env);
+    return makeClient(base, { kind: 'bearer', token: ldToken }, { maxRedirects: 0 });
 }
 /**
  * Unwrap the L&D success envelope `{ success, data, message? }` to its resource payload.

package/dist/src/core/readInput.js

@@ -48,9 +48,16 @@ export function resolveTextInput(inline, file, label) {
 // Resolve an inline-or-file JSON flag and parse it. VALIDATION when neither is given
 // (`provide --<label> (inline JSON) or --<label>-file`) or the content is not valid JSON.
 // Used by the L&D canvas / question / assessment-link inputs.
+//
+// The "neither" test is `=== undefined`, NOT truthiness: `resolveTextInput` returns `''` for a
+// ZERO-BYTE file, and a falsy test would report that as "you did not pass the flag" when the
+// caller passed `--<label>-file empty.json` and the file is simply empty. An empty string is
+// content, so let it reach `JSON.parse` and be named for what it is — not valid JSON. (An empty
+// INLINE value still lands on the "neither" message: `resolveTextInput`'s own XOR is truthy-based,
+// so it returns undefined for `--<label> ''` before this line runs.)
 export function parseJsonInput(inline, file, label) {
     const raw = resolveTextInput(inline, file, label);
-    if (!raw)
+    if (raw === undefined)
         throw createCliError('VALIDATION', `provide --${label} (inline JSON) or --${label}-file`);
     try {
         return JSON.parse(raw);

package/dist/src/mcp/bundled.js

@@ -1,7 +1,7 @@
 import { allTools } from './registry.js';
 // Developer-only tools excluded from the consumer .mcpb bundle. `publish_app` is alwaysDestructive
 // (creates a live, org-visible app release); `dev_sync`/`dev_sync_revert` mutate remote S3 dev state.
-// None are relevant to a non-technical adopter installing the extension. The CLI `p mcp` keeps all 123.
+// None are relevant to a non-technical adopter installing the extension. The CLI `p mcp` registers every tool.
 export const BUNDLE_EXCLUDED_TOOLS = new Set(['pitcher_publish_app', 'pitcher_dev_sync', 'pitcher_dev_sync_revert']);
 // The tool set the .mcpb bundle registers.
 export const bundledTools = allTools.filter((t) => !BUNDLE_EXCLUDED_TOOLS.has(t.name));

package/dist/src/mcp/hosted.d.ts

@@ -0,0 +1,21 @@
+import type { BuildServerOptions } from './server.js';
+import type { ToolDescriptor } from './tools/types.js';
+/**
+ * The tool set served by the hosted (remote, OAuth) MCP server — PIT-8912.
+ *
+ * Differences from stdio `p mcp`:
+ * - the three disk-bound tools (`LOCAL_ONLY`) are dropped: they zip a folder on the server host;
+ * - every file-path input (`FILE_KEY`) is stripped from the schemas AND rejected at runtime, so a
+ *   hosted call can never make the server read its own disk; every one has an inline alternative;
+ * - descriptions that talk about local files are rewritten.
+ */
+export declare const LOCAL_ONLY: ReadonlySet<string>;
+/**
+ * A file-path input. Covers the 8 schema keys on main (`filePath`, `configFile`, `landingContextFile`,
+ * `htmlFile`, `cssFile`, `bodyFile`, `fromFile`, `sectionsFile`) AND command-layer keys no schema
+ * exposes today (`questionFile`, `answersFile`, `canvasFile`, `assessmentsFile`, `contentHtmlFile`).
+ */
+export declare const FILE_KEY: RegExp;
+/** Build options every hosted server uses: a write always asks the client to confirm. */
+export declare const HOSTED_BUILD_OPTIONS: Readonly<BuildServerOptions>;
+export declare const hostedTools: ToolDescriptor[];

package/dist/src/mcp/hosted.js

@@ -0,0 +1,82 @@
+import { fail } from '../core/envelope.js';
+import { createCliError } from '../core/errors.js';
+import { allTools } from './registry.js';
+/**
+ * The tool set served by the hosted (remote, OAuth) MCP server — PIT-8912.
+ *
+ * Differences from stdio `p mcp`:
+ * - the three disk-bound tools (`LOCAL_ONLY`) are dropped: they zip a folder on the server host;
+ * - every file-path input (`FILE_KEY`) is stripped from the schemas AND rejected at runtime, so a
+ *   hosted call can never make the server read its own disk; every one has an inline alternative;
+ * - descriptions that talk about local files are rewritten.
+ */
+export const LOCAL_ONLY = new Set([
+    'pitcher_dev_sync',
+    'pitcher_dev_sync_revert',
+    'pitcher_publish_app',
+]);
+/**
+ * A file-path input. Covers the 8 schema keys on main (`filePath`, `configFile`, `landingContextFile`,
+ * `htmlFile`, `cssFile`, `bodyFile`, `fromFile`, `sectionsFile`) AND command-layer keys no schema
+ * exposes today (`questionFile`, `answersFile`, `canvasFile`, `assessmentsFile`, `contentHtmlFile`).
+ */
+export const FILE_KEY = /File$|^filePath$/;
+/** Build options every hosted server uses: a write always asks the client to confirm. */
+export const HOSTED_BUILD_OPTIONS = Object.freeze({ destructiveWrites: true });
+// Tool descriptions rewritten without the local-file wording (the stdio text is kept for p mcp).
+const HOSTED_DESCRIPTIONS = {
+    pitcher_files_create: 'Create a content file in an instance from a source URL. Additive.',
+    pitcher_files_update: 'Update a file by ID (name, folder, access, tags, metadata). sourceUrl replaces/overwrites the file binary; metadata is deep-merged.',
+    pitcher_announcements_create: 'Create a wa-announcements appsDB record (title/body, optional media, CTA link, scheduling, group targeting). Requires title and body. Additive.',
+    pitcher_dsr_create: 'Create a Digital Sales Room (a canvas share link) and get a clickable link back. Source is a canvas (canvasId) OR files (shareboxFileIds) - exactly one. Optional email/domain gating and a bound landing-page template. Returns the share: id, url (the full link), short_url, and a nested canvas object - there is no full_url field. This endpoint is a GET-OR-CREATE: sharing an already-shared canvas returns the existing link and only updates the fields you pass, so use pitcher_dsr_update to change or remove a value on an existing share. A failed landing bind does not fail the call: it returns the link with a warning - and binding a landing page needs instanceId, without which the bind is skipped with that warning. tags are a ShareBox-only field (they name the canvas the server builds from shareboxFileIds), so non-empty tags together with canvasId are REJECTED rather than silently dropped by the server.',
+    pitcher_metadata_template_upsert: "Upsert an instance's metadata-field schema. Merges the incoming sections by section 'label' — a section whose label matches an existing one is replaced, other sections are preserved. Cannot remove a section or field. Requires an instance- or org-admin role.",
+};
+// Field descriptions that name a stripped key, rewritten for hosted (`tool name → field → text`).
+const HOSTED_FIELD_DESCRIPTIONS = {
+    pitcher_files_update: {
+        instanceId: 'Instance ID (optional; not needed to update from a sourceUrl)',
+    },
+    pitcher_announcements_create: {
+        title: 'Announcement title',
+        body: 'Announcement body HTML',
+        priority: "Priority, e.g. 'normal' or 'important'",
+    },
+    pitcher_dsr_landing_create: {
+        html: 'Landing HTML (must contain data-pitcher-email-gate)',
+        css: 'CSS for the template',
+    },
+    pitcher_dsr_create: {
+        ifExists: 'Canvas already shared: "return" (default) hands back the existing link, "error" refuses and points at pitcher_dsr_update. Not checked for a ShareBox source, which always mints a new canvas',
+    },
+    pitcher_email_template_create: {
+        bodyHtml: 'HTML body (inline CSS).',
+    },
+};
+function hostedShape(t) {
+    const fields = HOSTED_FIELD_DESCRIPTIONS[t.name] ?? {};
+    const shape = {};
+    for (const [key, schema] of Object.entries(t.inputShape)) {
+        if (FILE_KEY.test(key))
+            continue;
+        shape[key] = fields[key] !== undefined ? schema.describe(fields[key]) : schema;
+    }
+    return shape;
+}
+function toHosted(t) {
+    return {
+        ...t,
+        description: HOSTED_DESCRIPTIONS[t.name] ?? t.description,
+        inputShape: hostedShape(t),
+        // Runtime guard, independent of the schema: the stripped keys are invisible to a well-behaved
+        // client, but this refuses any file-path key however it arrives (a schema that grows a new
+        // xFile key, a caller bypassing validation, a command-layer key no schema declares).
+        run: (opts, deps) => {
+            const bad = Object.keys(opts).filter((k) => FILE_KEY.test(k) && opts[k] !== undefined);
+            if (bad.length) {
+                return Promise.resolve(fail(createCliError('VALIDATION', `not supported on the hosted server (no local files): ${bad.join(', ')}`)));
+            }
+            return t.run(opts, deps);
+        },
+    };
+}
+export const hostedTools = allTools.filter((t) => !LOCAL_ONLY.has(t.name)).map(toHosted);

package/dist/src/mcp/index.d.ts

@@ -0,0 +1,7 @@
+export { buildServer, type McpRunContext, type BuildServerOptions } from './server.js';
+export { hostedTools, LOCAL_ONLY, FILE_KEY, HOSTED_BUILD_OPTIONS } from './hosted.js';
+export { allTools } from './registry.js';
+export { allPrompts } from './prompts/registry.js';
+export { allResources } from './resources/registry.js';
+export type { ToolDescriptor } from './tools/types.js';
+export type { Credential } from '../core/credential.js';

package/dist/src/mcp/index.js

@@ -0,0 +1,6 @@
+// Public entry `@pitcher/cli-scripts/mcp` — what the hosted MCP server (web/packages/mcp-server) consumes.
+export { buildServer } from './server.js';
+export { hostedTools, LOCAL_ONLY, FILE_KEY, HOSTED_BUILD_OPTIONS } from './hosted.js';
+export { allTools } from './registry.js';
+export { allPrompts } from './prompts/registry.js';
+export { allResources } from './resources/registry.js';

package/dist/src/mcp/serve.js

@@ -9,7 +9,7 @@ import { allResources } from './resources/registry.js';
 // Prompts/resources default to the full set for every frontend (no subsetting).
 export async function runMcpServe(env = process.env, tools = allTools, prompts = allPrompts, resources = allResources) {
     const mcpEnv = resolveMcpEnv(env);
-    const server = buildServer(mcpEnv, tools, prompts, resources);
+    const server = buildServer({ credential: { kind: 'apiKey', key: mcpEnv.apiKey }, org: mcpEnv.org, url: mcpEnv.url }, tools, prompts, resources, { destructiveWrites: mcpEnv.prod });
     const transport = new StdioServerTransport();
     await server.connect(transport);
     const target = mcpEnv.url ?? `https://${mcpEnv.org}.my.pitcher.com`;

package/dist/src/mcp/server.d.ts

@@ -1,6 +1,23 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { McpEnv } from './env.js';
+import type { Credential } from '../core/credential.js';
 import type { ToolDescriptor } from './tools/types.js';
 import type { PromptDescriptor } from './prompts/types.js';
 import type { ResourceDescriptor } from './resources/types.js';
-export declare function buildServer(env: McpEnv, tools?: ToolDescriptor[], prompts?: PromptDescriptor[], resources?: ResourceDescriptor[]): McpServer;
+/**
+ * The per-server request context: who every tool call runs as, and against which origin.
+ * A plain value captured at build time — stdio builds one from env (API key); the hosted server
+ * builds one server per request from the caller's bearer token. Never a tool input.
+ */
+export interface McpRunContext {
+    credential: Credential;
+    org?: string;
+    url?: string;
+}
+export interface BuildServerOptions {
+    /**
+     * Mark every `write` tool `destructiveHint: true`. Annotations are fixed at registration, so this
+     * is a build option, never a per-call field. Stdio passes `env.prod`; hosted always passes true.
+     */
+    destructiveWrites?: boolean;
+}
+export declare function buildServer(ctx: McpRunContext, tools?: ToolDescriptor[], prompts?: PromptDescriptor[], resources?: ResourceDescriptor[], opts?: BuildServerOptions): McpServer;

package/dist/src/mcp/server.js

@@ -33,7 +33,7 @@ function errorText(e) {
         return `${e.code}: ${e.message}`;
     return e instanceof Error ? e.message : String(e);
 }
-export function buildServer(env, tools = allTools, prompts = allPrompts, resources = allResources) {
+export function buildServer(ctx, tools = allTools, prompts = allPrompts, resources = allResources, opts = {}) {
     const server = new McpServer({
         name: 'pitcher',
         version,
@@ -47,7 +47,7 @@ export function buildServer(env, tools = allTools, prompts = allPrompts, resourc
     // dashboard) instead of a rigid full dashboard every time. See renderPolicy.ts.
     { instructions: ANALYTICS_RENDER_POLICY });
     for (const tool of tools) {
-        const destructive = tool.alwaysDestructive === true || (tool.write === true && env.prod);
+        const destructive = tool.alwaysDestructive === true || (tool.write === true && opts.destructiveWrites === true);
         server.registerTool(tool.name, {
             title: tool.title,
             description: tool.description,
@@ -55,8 +55,8 @@ export function buildServer(env, tools = allTools, prompts = allPrompts, resourc
             annotations: { readOnlyHint: tool.readOnly, destructiveHint: destructive },
         }, async (args) => {
             try {
-                // spread args FIRST so injected auth/env always wins — never reorder to { apiKey, ...args }
-                const envelope = await tool.run({ ...args, apiKey: env.apiKey, org: env.org, url: env.url });
+                // spread args FIRST so injected auth/env always wins — never reorder to { credential, ...args }
+                const envelope = await tool.run({ ...args, credential: ctx.credential, org: ctx.org, url: ctx.url });
                 return envelopeToToolResult(envelope);
             }
             catch (e) {

package/dist/src/mcp/tools/analytics.js

@@ -25,7 +25,7 @@ export const analyticsTools = [
             '(inventory counts like total-members do not).',
         inputShape: {
             instanceId: z.string().describe('Instance ID (required)'),
-            type: z.string().optional().describe("KPI type, e.g. total-members, total-active-users (default 'all')"),
+            type: z.string().describe('KPI type, e.g. total-members, total-active-users (required)'),
             startDate: z.string().optional().describe('Window start, ISO date (required by the server for activity metrics)'),
             endDate: z.string().optional().describe('Window end, ISO date (required by the server for activity metrics)'),
             groupIds: z.string().optional().describe('Comma-separated distribution-group IDs to scope by'),

package/dist/src/mcp/tools/devSync.js

@@ -27,7 +27,7 @@ export const devSyncTools = [
             const fileId = requireFileId(opts);
             if (!fileId)
                 return Promise.resolve(fail(createCliError('VALIDATION', 'fileId is required')));
-            return runDevSync({ fileId, apiKey: opts.apiKey, org: opts.org }, deps);
+            return runDevSync({ fileId, apiKey: opts.apiKey, credential: opts.credential, org: opts.org }, deps);
         },
         wraps: runDevSync,
         readOnly: false,
@@ -44,7 +44,7 @@ export const devSyncTools = [
             const fileId = requireFileId(opts);
             if (!fileId)
                 return Promise.resolve(fail(createCliError('VALIDATION', 'fileId is required')));
-            return runRevert({ fileId, apiKey: opts.apiKey, org: opts.org }, deps);
+            return runRevert({ fileId, apiKey: opts.apiKey, credential: opts.credential, org: opts.org }, deps);
         },
         wraps: runRevert,
         readOnly: false,

package/dist/src/mcp/tools/dsr.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { runDsrCreate, runDsrBindLanding, runDsrUpdate, runDsrDelete, CLEARABLE_UPDATE_FIELDS, IF_EXISTS_MODES } from '../../commands/dsr.js';
+import { runDsrCreate, runDsrGet, runDsrBindLanding, runDsrUpdate, runDsrDelete, CLEARABLE_UPDATE_FIELDS, IF_EXISTS_MODES } from '../../commands/dsr.js';
 const AUTH_STRATEGIES = [
     'none', 'any_email', 'specified_emails', 'specified_domains', 'verified_emails', 'verified_domains',
 ];
@@ -33,6 +33,10 @@ export const dsrTools = [
                 .optional()
                 .describe('Bind a landing-page template (discover via pitcher_dsr_landing_list). Needs instanceId: without it the bind is skipped and the share comes back with a warning'),
             landingContext: z.string().optional().describe('Landing-page merge fields, a JSON object as a string'),
+            landingContextFile: z
+                .string()
+                .optional()
+                .describe('Path on the MCP server host to a JSON file holding the landing-page merge fields - the same field as landingContext, read off disk. Pass one or the other, never both (both is rejected as VALIDATION). Prefer landingContext inline: in a host whose sandbox is a separate filesystem from the MCP subprocess, a path written there is not visible here'),
             configFile: z.string().optional().describe('Path on the MCP server host to a full {source,security,landing} spec JSON; mutually exclusive with the individual flags'),
             ifExists: z
                 .enum(IF_EXISTS_MODES)
@@ -43,6 +47,16 @@ export const dsrTools = [
         readOnly: false,
         write: true,
     },
+    {
+        name: 'pitcher_dsr_get',
+        title: 'Read a DSR share',
+        description: "Read an EXISTING DSR share back by its shared-link id. It returns the ACCESS CONFIG only: auth_strategy, allowed_emails / allowed_domains, valid_until, allow_forward (plus allow_forward_raw, the rep's own toggle before the admin setting is applied), the bound landing page (landing_page_template_id, landing_page_template_snapshot, landing_page_context) and created_at / modified_at. It does NOT return the canvas or the file - keep the id pitcher_dsr_create handed back for those. Use it to confirm what pitcher_dsr_create or pitcher_dsr_update actually stored, or to check a share before changing it. Read-only - it changes nothing. ANY id that matches no share comes back NOT_FOUND, malformed ids included: the endpoint does not validate the id's format.",
+        inputShape: {
+            id: z.string().describe('Shared-link ID'),
+        },
+        run: runDsrGet,
+        readOnly: true,
+    },
     {
         name: 'pitcher_dsr_bind_landing',
         title: 'Bind a DSR landing page',
@@ -51,6 +65,10 @@ export const dsrTools = [
             id: z.string().describe('Shared-link ID'),
             landingTemplateId: z.string().describe('Landing template ID, or "none" to unbind'),
             landingContext: z.string().optional().describe('Landing-page merge fields, a JSON object as a string'),
+            landingContextFile: z
+                .string()
+                .optional()
+                .describe('Path on the MCP server host to a JSON file holding the merge fields - the same field as landingContext, read off disk. Pass one or the other, never both (both is rejected as VALIDATION). Prefer landingContext inline: in a host whose sandbox is a separate filesystem from the MCP subprocess, a path written there is not visible here'),
             instanceId: z
                 .string()
                 .describe('Instance ID. The endpoint resolves the instance from this query param and rejects the call without it'),