@pitcher/cli-scripts 2.17.1 → 2.19.0

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/prompts/dsr.js

@@ -20,6 +20,8 @@ export const dsrPrompts = [
                 '',
                 '## DSR sharing guidance',
                 '- **Source is exactly one of** a canvas (`canvasId`) OR files (`shareboxFileIds`).',
+                '- **`tags` are ShareBox-only.** They name the canvas the server builds from `shareboxFileIds`, so non-empty ' +
+                    '`tags` together with `canvasId` is rejected rather than silently ignored.',
                 `- **Pick the gating (\`authStrategy\`) by audience.** For ${audience}: internal/quick demo → \`none\` ` +
                     '(open link); a known individual → `specified_emails` (+ `allowedEmails`); a company → ' +
                     '`specified_domains` (+ `allowedDomains`); the server default is `any_email`. Add `validUntil` ' +
@@ -27,6 +29,8 @@ export const dsrPrompts = [
                 '- **Branding the pre-auth page is a SEPARATE step:** this recipe only **binds** an existing ' +
                     'landing template (`landingTemplateId`, discover via `pitcher_dsr_landing_list`; pass ' +
                     '`landingContext` merge fields **as a JSON object serialized to a string**, not as an object). ' +
+                    '**A landing bind needs `instanceId`** — the endpoint resolves the instance from it, so without it the bind ' +
+                    'is skipped and the share comes back with a warning. ' +
                     'If no suitable template exists and the user wants a ' +
                     'branded landing, author one FIRST with the **`seed_dsr_landing`** recipe, then bind its id here. ' +
                     'Do NOT hand-write landing HTML in this recipe.',

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/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',
 ];
@@ -7,9 +7,9 @@ export const dsrTools = [
     {
         name: 'pitcher_dsr_create',
         title: 'Create and share a DSR',
-        description: '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: with individual fields, 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 configFile spec sends its whole security block (nulls and empty lists included), so for an already-shared canvas it refuses by default (ifExists "error"). A failed landing bind does not fail the call: it returns the link with a warning.',
+        description: '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: with individual fields, 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 configFile spec sends its whole security block (nulls and empty lists included), so for an already-shared canvas it refuses by default (ifExists "error"). 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.',
         inputShape: {
-            instanceId: z.string().optional().describe('Instance ID (required for the shareboxFileIds source)'),
+            instanceId: z.string().optional().describe('Instance ID (required for the shareboxFileIds source, and to bind a landing page)'),
             canvasId: z.string().optional().describe('Canvas to share (exactly one of canvasId / shareboxFileIds)'),
             shareboxFileIds: z.array(z.string()).optional().describe('File IDs to build a share from (exactly one of canvasId / shareboxFileIds)'),
             canvasName: z.string().optional().describe('Name for the ShareBox-built canvas'),
@@ -20,10 +20,23 @@ export const dsrTools = [
             allowedDomains: z.array(z.string()).optional().describe('Required for specified_domains / verified_domains. An EMPTY array is rejected'),
             validUntil: z.string().optional().describe('Expiry, ISO datetime'),
             allowForward: z.boolean().optional(),
-            allowDownload: z.boolean().optional(),
-            tags: z.array(z.string()).optional(),
-            landingTemplateId: z.string().optional().describe('Bind a landing-page template (discover via pitcher_dsr_landing_list)'),
+            allowDownload: z
+                .boolean()
+                .optional()
+                .describe('Let recipients download the shared files. Create-time only (pitcher_dsr_update does not accept it). Sent to the server exactly as given for either source - unlike tags, the CLI applies no source-specific guard to it, so read the created share back if you need to confirm the value took'),
+            tags: z
+                .array(z.string())
+                .optional()
+                .describe('Tags for the ShareBox-built canvas. ShareBox source ONLY - a non-empty array together with canvasId is rejected, because the server reads tags only when it builds the canvas itself and would otherwise ignore them. An empty array is accepted (it asks for nothing)'),
+            landingTemplateId: z
+                .string()
+                .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)
@@ -34,15 +47,31 @@ 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',
-        description: 'Attach, re-brand, or unbind a landing-page template on an existing DSR share. Use landingTemplateId "none" to unbind. Requires an editor-level key (hard-fails AUTH otherwise).',
+        description: 'Attach, re-brand, or unbind a landing-page template on an existing DSR share. Use landingTemplateId "none" to unbind. instanceId is REQUIRED: the endpoint resolves the instance from that query param and refuses the call without it. An admin or editor key can bind any share in the org; a member key only shares that member created (hard-fails AUTH otherwise).',
         inputShape: {
             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'),
-            instanceId: z.string().optional(),
+            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'),
         },
         run: runDsrBindLanding,
         readOnly: false,

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

@@ -21,7 +21,7 @@ export const publishAppTools = [
             installToEnvName: z.string().optional().describe('Environment name (e.g. "test") to install the app to after publishing'),
         },
         // runPublishApp overloads `url` as BOTH origin and publish endpoint; the server injects NG_URL into
-        // every tool, so forward only apiKey + org (never url) plus this tool's own inputs.
+        // every tool, so forward only apiKey + credential + org (never url) plus this tool's own inputs.
         run: (opts) => runPublishApp({
             folder: asString(opts.folder),
             incrementVersion: asBool(opts.incrementVersion),
@@ -29,6 +29,7 @@ export const publishAppTools = [
             installTo: asString(opts.installTo),
             installToEnvName: asString(opts.installToEnvName),
             apiKey: opts.apiKey,
+            credential: opts.credential,
             org: opts.org,
         }),
         wraps: runPublishApp,

package/dist/src/mcp/tools/types.d.ts

@@ -1,7 +1,7 @@
 import type { z } from 'zod';
 import type { Envelope } from '../../core/envelope.js';
 import type { CommonOpts } from '../../core/http.js';
-export type InjectedAuth = Pick<CommonOpts, 'apiKey' | 'org' | 'url'>;
+export type InjectedAuth = Pick<CommonOpts, 'apiKey' | 'credential' | 'org' | 'url'>;
 export interface ToolDescriptor {
     name: string;
     title: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pitcher/cli-scripts",
-  "version": "2.17.1",
+  "version": "2.19.0",
   "description": "The Pitcher CLI for various tasks in its ecosystem.",
   "author": "Pitcher AG",
   "license": "MIT",
@@ -12,6 +12,17 @@
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/src/mcp/index.d.ts",
+      "import": "./dist/src/mcp/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "scripts": {
     "build": "tsc",
     "type-check": "tsc --noEmit && tsc -p mcpb/tsconfig.json",
@@ -28,18 +39,18 @@
   ],
   "devDependencies": {
     "@anthropic-ai/mcpb": "^2.1.2",
-    "@types/archiver": "^7.0.0",
-    "@types/node": "^24.13.2",
+    "@types/archiver": "^8.0.0",
+    "@types/node": "^24.13.5",
     "esbuild": "^0.28.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1",
-    "archiver": "^7.0.1",
+    "archiver": "^8.0.0",
     "axios": "^1.18.1",
     "chokidar": "^5.0.0",
-    "commander": "^14.0.3",
+    "commander": "^15.0.0",
     "form-data": "^4.0.6",
     "zod": "^3"
   }