@pitcher/cli-scripts 3.0.1 → 3.1.0

package/README.md

@@ -6,7 +6,7 @@ Releases are published to npm automatically: a merge to `main` that bumps `versi
 
 > ⚠️ **Breaking changes in 3.0.0**
 >
-> 1. **Local `p mcp` now serves ONLY 3 tools** (`pitcher_dev_sync`, `pitcher_dev_sync_revert`, `pitcher_publish_app`), down from 124. Everything else is the hosted server `https://pitcher-mcp.fly.dev/mcp`. `p mcp` no longer reads `NG_API_KEY`/`NG_ORG`/`NG_URL`/`NG_ENV`; run `p login` once (`--domain` or `PITCHER_DOMAIN` when logged in to several orgs).
+> 1. **Local `p mcp` now serves ONLY 3 tools** (`pitcher_dev_sync`, `pitcher_dev_sync_revert`, `pitcher_publish_app`), down from 124. Everything else is the hosted server `https://mcp.pitcher.com/mcp`. `p mcp` no longer reads `NG_API_KEY`/`NG_ORG`/`NG_URL`/`NG_ENV`; run `p login` once (`--domain` or `PITCHER_DOMAIN` when logged in to several orgs).
 > 2. **Every other command uses your `p login` session.** `--api-key` (automation) still wins when passed; `NG_API_KEY` is used only when you have NO `p login` session, and is otherwise ignored with a notice. `--org` no longer defaults to `dev` on the session path: the session's org is the target. `--domain` cannot be combined with `--api-key` or `--org`.
 > 3. **The Claude Desktop `.mcpb` extension is retired.** Claude Desktop adds the remote URL natively.
 > 4. **`p analytics kpi` requires `--type`** (one of the 12 KPI types listed in `p analytics kpi --help`). The old default `all` always returned a 500.
@@ -44,7 +44,7 @@ Pitcher's MCP tools come from two places:
 
 | Server | Tools | Add it with |
 |---|---|---|
-| **Hosted** (OAuth; Claude Code, Claude Desktop, claude.ai, ChatGPT) | everything: content, canvases, DSRs, analytics, L&D, users, … (121 tools, prompts, resources) | `claude mcp add --transport http pitcher https://pitcher-mcp.fly.dev/mcp` — Claude Desktop: Settings → Connectors → Add custom connector, same URL |
+| **Hosted** (OAuth; Claude Code, Claude Desktop, claude.ai, ChatGPT) | everything: content, canvases, DSRs, analytics, L&D, users, … (121 tools, prompts, resources) | `claude mcp add --transport http pitcher https://mcp.pitcher.com/mcp` — Claude Desktop: Settings → Connectors → Add custom connector, same URL |
 | **Local** `p mcp` (stdio) | only `pitcher_dev_sync`, `pitcher_dev_sync_revert`, `pitcher_publish_app` (they zip a folder on YOUR machine) | `claude mcp add pitcher-local -- p mcp` |
 
 Claude Code users add both. The local server runs on your `p login` session (no API key, no env block); the domain is fixed when it starts. Signed in to several orgs? Add one entry per org:

package/dist/src/commands/scaffolds.js

@@ -205,7 +205,6 @@ const METADATA_TEMPLATE_SCAFFOLD_DATA = [
                 is_required: true,
                 is_filterable: true,
                 is_sortable: true,
-                is_pitch_master: false,
                 help_text: 'Marketed product name',
                 default: '',
             },
@@ -216,7 +215,6 @@ const METADATA_TEMPLATE_SCAFFOLD_DATA = [
                 is_required: false,
                 is_filterable: true,
                 is_sortable: true,
-                is_pitch_master: false,
             },
             {
                 name: 'therapeutic_area',
@@ -225,7 +223,6 @@ const METADATA_TEMPLATE_SCAFFOLD_DATA = [
                 is_required: false,
                 is_filterable: true,
                 is_sortable: false,
-                is_pitch_master: false,
                 options: [
                     { label: 'Cardiology', value: 'cardiology' },
                     { label: 'Oncology', value: 'oncology' },
@@ -239,7 +236,6 @@ const METADATA_TEMPLATE_SCAFFOLD_DATA = [
                 is_required: false,
                 is_filterable: true,
                 is_sortable: false,
-                is_pitch_master: false,
                 options: [
                     { label: 'HCP', value: 'hcp' },
                     { label: 'Payer', value: 'payer' },
@@ -253,7 +249,6 @@ const METADATA_TEMPLATE_SCAFFOLD_DATA = [
                 is_required: false,
                 is_filterable: false,
                 is_sortable: true,
-                is_pitch_master: false,
                 default: 0,
             },
             {
@@ -263,7 +258,6 @@ const METADATA_TEMPLATE_SCAFFOLD_DATA = [
                 is_required: false,
                 is_filterable: true,
                 is_sortable: false,
-                is_pitch_master: false,
                 default: false,
             },
         ],

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

@@ -28,6 +28,8 @@ export declare function orgSubdomain(domain: string): string;
  * in step when a tenant is added.
  */
 export declare const AUTH0_NATIVE_CLIENT_IDS: Readonly<Record<string, string>>;
+/** The hosted MCP connector's access for an org (`pitcher_organization.settings.mcp.access`, PIT-9768). */
+export type McpAccess = 'off' | 'read_only' | 'full';
 export interface OrgConfig {
     /** The Auth0 CUSTOM domain (`auth0.test-eu.pitcher.com`) — the key into the client-id maps. */
     auth0Domain: string;
@@ -36,6 +38,11 @@ export interface OrgConfig {
     organization: string | null;
     /** `'test' | 'production'`. OPTIONAL upstream: treat unknown as production. */
     environment?: string;
+    /**
+     * undefined = UNKNOWN: next-core's org lookup failed, or that region's next-core predates the field. Never
+     * read it as "off" and never as "on" — the hosted server retries or refuses (`mcp-server` `src/oauth/access.ts`).
+     */
+    mcpAccess?: McpAccess;
 }
 export interface Auth0Tokens {
     access_token: string;
@@ -65,7 +72,11 @@ export declare function buildAuthorizeUrl(p: {
     state: string;
     codeChallenge: string;
 }): string;
-/** null = the domain is not a Pitcher org (4xx / no auth0 block). Throws an UpstreamError on network/5xx. */
+/**
+ * null = the domain is not a Pitcher org (404, or no auth0 block). Throws an UpstreamError on a network error or
+ * any other status: a 400 or a 429 says nothing about the org, and the hosted server reads null as "this token's
+ * org is gone" (401, sign in again) where an upstream error is a retryable 503.
+ */
 export declare function fetchOrgConfig(domain: string, opts?: HttpOpts): Promise<OrgConfig | null>;
 export declare function exchangeCode(p: {
     auth0Domain: string;

package/dist/src/core/pitcherAuth.js

@@ -35,7 +35,10 @@ export function orgSubdomain(domain) {
 export const AUTH0_NATIVE_CLIENT_IDS = {
     'auth0.test-eu.pitcher.com': 'EvXiukSFA9LmxkoMyGfGrX6tk5eZdJFu',
     'auth0.eu.pitcher.com': 'cJpAajaha7dWc2mnGy3GZSMBm3kzX370',
+    'auth0.test-us.pitcher.com': 'sd6biLE9qGBwUfSzl2uRC1p5JdhKY06N',
+    'auth0.us.pitcher.com': 'k6BgMI2Oy26RnyucUsWiL81JOeaufECm',
 };
+const MCP_ACCESS = new Set(['off', 'read_only', 'full']);
 export function createUpstreamError(kind, message) {
     return Object.assign(new Error(message), { isUpstreamError: true, kind });
 }
@@ -60,10 +63,16 @@ export function buildAuthorizeUrl(p) {
     }).toString();
     return u.href;
 }
-/** null = the domain is not a Pitcher org (4xx / no auth0 block). Throws an UpstreamError on network/5xx. */
+/**
+ * null = the domain is not a Pitcher org (404, or no auth0 block). Throws an UpstreamError on a network error or
+ * any other status: a 400 or a 429 says nothing about the org, and the hosted server reads null as "this token's
+ * org is gone" (401, sign in again) where an upstream error is a retryable 503.
+ */
 export async function fetchOrgConfig(domain, opts = {}) {
     const doFetch = opts.fetch ?? globalThis.fetch;
-    const url = `https://${domain}/core/api/org-config?org_subdomain=${encodeURIComponent(orgSubdomain(domain))}`;
+    // No `org_subdomain` param: the edge sets `x-original-domain` from the host, which names the same org, and
+    // next-core reports every request carrying the param to Sentry as deprecated.
+    const url = `https://${domain}/core/api/org-config`;
     let res;
     try {
         res = await doFetch(url, {
@@ -76,10 +85,10 @@ export async function fetchOrgConfig(domain, opts = {}) {
     catch {
         throw createUpstreamError('upstream', 'org-config unreachable');
     }
-    if (res.status >= 500)
-        throw createUpstreamError('upstream', `org-config returned ${res.status}`);
-    if (res.status !== 200)
+    if (res.status === 404)
         return null;
+    if (res.status !== 200)
+        throw createUpstreamError('upstream', `org-config returned ${res.status}`);
     const json = await res.json().catch(() => null);
     const a = json?.auth0;
     if (!a || typeof a.domain !== 'string' || typeof a.audience !== 'string')
@@ -89,6 +98,8 @@ export async function fetchOrgConfig(domain, opts = {}) {
         audience: a.audience,
         organization: typeof a.organization === 'string' && a.organization ? a.organization : null,
         environment: typeof json.environment === 'string' ? json.environment : undefined,
+        // A value outside the three is a newer next-core than this code: refuse it like "off", not like unknown.
+        mcpAccess: typeof json.mcp?.access === 'string' ? (MCP_ACCESS.has(json.mcp.access) ? json.mcp.access : 'off') : undefined,
     };
 }
 async function postJson(url, body, opts) {

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

@@ -1,3 +1,4 @@
+import type { PromptDescriptor } from './prompts/types.js';
 import type { BuildServerOptions } from './server.js';
 import type { ToolDescriptor } from './tools/types.js';
 /**
@@ -16,6 +17,20 @@ export declare const LOCAL_ONLY: ReadonlySet<string>;
  * exposes today (`questionFile`, `answersFile`, `canvasFile`, `assessmentsFile`, `contentHtmlFile`).
  */
 export declare const FILE_KEY: RegExp;
+/**
+ * An id-shaped input (`id`, `instanceId`, `courseIds`, …). Many commands interpolate ids straight into the
+ * request PATH (`/api/v1/files/${id}`, the L&D `/admin/courses/${id}`), so a value like `../users/1` or `1?x=`
+ * would retarget the call to another endpoint on the same host with the caller's token. Hosted accepts only
+ * plain tokens (letters, digits, `_`, `-`; comma-separated lists for string list inputs).
+ */
+export declare const ID_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[];
+/**
+ * Read-only mode (the org's `settings.mcp.access` is `read_only`, PIT-9768): only the hosted tools that read.
+ * A write tool is never registered, so calling one is "unknown tool", not a refused write.
+ */
+export declare const hostedReadOnlyTools: ToolDescriptor[];
+/** The prompts a read-only server serves: only those flagged `readOnly` (the rest drive a write tool). */
+export declare const readOnlyPrompts: PromptDescriptor[];

package/dist/src/mcp/hosted.js

@@ -1,5 +1,6 @@
 import { fail } from '../core/envelope.js';
 import { createCliError } from '../core/errors.js';
+import { allPrompts } from './prompts/registry.js';
 import { allTools } from './registry.js';
 /**
  * The tool set served by the hosted (remote, OAuth) MCP server — PIT-8912.
@@ -21,6 +22,26 @@ export const LOCAL_ONLY = new Set([
  * exposes today (`questionFile`, `answersFile`, `canvasFile`, `assessmentsFile`, `contentHtmlFile`).
  */
 export const FILE_KEY = /File$|^filePath$/;
+/**
+ * An id-shaped input (`id`, `instanceId`, `courseIds`, …). Many commands interpolate ids straight into the
+ * request PATH (`/api/v1/files/${id}`, the L&D `/admin/courses/${id}`), so a value like `../users/1` or `1?x=`
+ * would retarget the call to another endpoint on the same host with the caller's token. Hosted accepts only
+ * plain tokens (letters, digits, `_`, `-`; comma-separated lists for string list inputs).
+ */
+export const ID_KEY = /^(id|ids|.+Id|.+Ids)$/;
+const ID_TOKEN = /^[A-Za-z0-9_-]{1,200}$/;
+function isSafeIdValue(v) {
+    // '' is "absent" to every command (falsy) and reaches no path
+    if (v === undefined || v === null || v === '' || typeof v === 'boolean')
+        return true;
+    if (typeof v === 'number')
+        return Number.isSafeInteger(v);
+    if (typeof v === 'string')
+        return v.split(',').every((part) => ID_TOKEN.test(part.trim()));
+    if (Array.isArray(v))
+        return v.every((x) => (typeof x === 'number' ? Number.isSafeInteger(x) : ID_TOKEN.test(String(x))));
+    return false;
+}
 /** 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).
@@ -67,16 +88,28 @@ function toHosted(t) {
         ...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
+        // Runtime guards, 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).
+        // xFile key, a caller bypassing validation, a command-layer key no schema declares), and any
+        // id that is not a plain token (ID_KEY).
         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(', ')}`)));
             }
+            const badIds = Object.keys(opts).filter((k) => ID_KEY.test(k) && !isSafeIdValue(opts[k]));
+            if (badIds.length) {
+                return Promise.resolve(fail(createCliError('VALIDATION', `not a valid id (letters, digits, "_" and "-" only): ${badIds.join(', ')}`)));
+            }
             return t.run(opts, deps);
         },
     };
 }
 export const hostedTools = allTools.filter((t) => !LOCAL_ONLY.has(t.name)).map(toHosted);
+/**
+ * Read-only mode (the org's `settings.mcp.access` is `read_only`, PIT-9768): only the hosted tools that read.
+ * A write tool is never registered, so calling one is "unknown tool", not a refused write.
+ */
+export const hostedReadOnlyTools = hostedTools.filter((t) => t.readOnly && !t.write && !t.alwaysDestructive);
+/** The prompts a read-only server serves: only those flagged `readOnly` (the rest drive a write tool). */
+export const readOnlyPrompts = allPrompts.filter((p) => p.readOnly === true);

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

@@ -1,5 +1,5 @@
 export { buildServer, type McpRunContext, type BuildServerOptions } from './server.js';
-export { hostedTools, LOCAL_ONLY, FILE_KEY, HOSTED_BUILD_OPTIONS } from './hosted.js';
+export { hostedTools, hostedReadOnlyTools, readOnlyPrompts, LOCAL_ONLY, FILE_KEY, ID_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/index.js

@@ -1,6 +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 { hostedTools, hostedReadOnlyTools, readOnlyPrompts, LOCAL_ONLY, FILE_KEY, ID_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/local.d.ts

@@ -1,6 +1,6 @@
 /**
  * The tool set of LOCAL `p mcp` (PIT-8943): only the three disk-bound tools (`dev_sync`, `dev_sync_revert`,
  * `publish_app`), which zip a folder on this machine and so cannot run hosted. Everything else is the hosted
- * server (`https://pitcher-mcp.fly.dev/mcp`).
+ * server (`https://mcp.pitcher.com/mcp`).
  */
 export declare const localTools: import("./index.js").ToolDescriptor[];

package/dist/src/mcp/local.js

@@ -3,6 +3,6 @@ import { allTools } from './registry.js';
 /**
  * The tool set of LOCAL `p mcp` (PIT-8943): only the three disk-bound tools (`dev_sync`, `dev_sync_revert`,
  * `publish_app`), which zip a folder on this machine and so cannot run hosted. Everything else is the hosted
- * server (`https://pitcher-mcp.fly.dev/mcp`).
+ * server (`https://mcp.pitcher.com/mcp`).
  */
 export const localTools = allTools.filter((t) => LOCAL_ONLY.has(t.name));

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

@@ -7,6 +7,7 @@ import { instanceLine, readSafetyNote } from './shared.js';
 export const analyticsPrompts = [
     {
         name: 'top_content',
+        readOnly: true,
         title: 'Top-performing content',
         description: 'Rank an instance’s most-viewed canvases (and optionally files) over a window.',
         argsSchema: {
@@ -34,6 +35,7 @@ export const analyticsPrompts = [
     },
     {
         name: 'content_engagement_summary',
+        readOnly: true,
         title: 'Content engagement summary',
         description: 'Summarize per-content/DSR engagement for an instance over a window.',
         argsSchema: {
@@ -59,6 +61,7 @@ export const analyticsPrompts = [
     },
     {
         name: 'who_viewed_canvas',
+        readOnly: true,
         title: 'Who viewed a DSR canvas',
         description: 'List the viewers of a specific DSR canvas, then drill into one viewer’s session timeline.',
         argsSchema: {
@@ -89,6 +92,7 @@ export const analyticsPrompts = [
     },
     {
         name: 'adoption_snapshot',
+        readOnly: true,
         title: 'Adoption snapshot',
         description: 'Combine active-user stats and KPIs into a short adoption snapshot for an instance.',
         argsSchema: {

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

@@ -6,4 +6,5 @@ export interface PromptDescriptor {
     description: string;
     argsSchema: Record<string, ZodOptional<ZodString>>;
     build: (args: Record<string, string | undefined>) => PromptMessage[];
+    readOnly?: true;
 }

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

@@ -6,7 +6,7 @@ export interface ToolDescriptor {
     name: string;
     title: string;
     description: string;
-    inputShape: z.ZodRawShape;
+    inputShape: Record<string, z.ZodType>;
     run: (opts: Record<string, unknown> & InjectedAuth, deps?: any) => Promise<Envelope<unknown>>;
     wraps?: (...a: any[]) => unknown;
     readOnly: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pitcher/cli-scripts",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "The Pitcher CLI for various tasks in its ecosystem.",
   "author": "Pitcher AG",
   "license": "MIT",
@@ -57,6 +57,6 @@
     "chokidar": "^5.0.0",
     "commander": "^15.0.0",
     "form-data": "^4.0.6",
-    "zod": "^3"
+    "zod": "^4.6.7"
   }
 }