@pitcher/cli-scripts 2.7.1 → 2.9.0

package/README.md

@@ -10,6 +10,43 @@ p --help
 p command --help
 ```
 
+## MCP server
+
+Run `p mcp` to start a stdio [MCP](https://modelcontextprotocol.io) server that exposes this CLI's commands as tools to an MCP-capable host (Claude Desktop, Claude Code, etc). It wraps 50 tools, one per CLI `run*` function: every command above (including `dsr create` + `dsr bind-landing`) except the five local `scaffold` subcommands (which just print/write a starter file and make no request). `dev-sync` is exposed as a one-shot sync only; the continuous `watch` mode is not available as a tool.
+
+```bash
+p mcp
+# or without a global install
+npx @pitcher/cli-scripts mcp
+```
+
+### Environment variables
+
+Auth and org scope are resolved once at boot from environment variables. They are never tool inputs, so the model cannot change org or credentials mid-session.
+
+- `NG_API_KEY` (required, secret): the API key the server authenticates as.
+- `NG_ORG` (default `dev`): organization subdomain, or set `NG_URL` directly for a full origin.
+- `NG_ENV` (`prod` or `test`): controls the destructive-hint guard on write tools (see below). Defaults to a guess based on `NG_ORG` when unset.
+
+One config entry = one org, because the API key is org-specific. To work against multiple orgs, add multiple entries (e.g. `pitcher-dev`, `pitcher-prod`) with different env blocks; do not try to pass org per tool call.
+
+### Host config example (Claude Desktop / `.mcp.json`)
+
+```jsonc
+"pitcher": {
+  "command": "npx",
+  "args": ["-y", "@pitcher/cli-scripts", "mcp"],
+  "env": { "NG_API_KEY": "<key>", "NG_ORG": "dev" }
+}
+```
+
+### Tool annotations
+
+- Read commands are marked `readOnlyHint`. `dev-sync` counts as a write (it mutates remote dev-override state).
+- `publish-app` is always marked `destructiveHint` (it creates a live, org-visible release). Other write tools get `destructiveHint` only when the resolved environment is production (`NG_ENV=prod`, or `NG_ORG` other than `dev` with `NG_ENV` unset). This steers hosts toward requiring extra confirmation before mutating a production org.
+
+This section is a reference only. For app-development conventions (modules, settings, mount points, SFDC), see the `pitcher-apps` skill, not this README.
+
 ## To run the `publish-app` command:
 
 ```bash
@@ -414,3 +451,25 @@ p metadata-template upsert --instance-id 01... --sections-file ./schema.json --a
 ```
 
 `upsert` merges the incoming sections by section `label` — a section whose label matches an existing one is replaced, other sections are preserved. It **cannot remove** a section or field (that's a UI operation). `options` for `select`/`multi-select` fields are `{ label, value }` objects (bare strings are rejected). `upsert` requires an instance- or org-admin key; a non-admin member key is rejected (400 → `VALIDATION`).
+
+## To run the `dsr` command:
+
+Create and share a Digital Sales Room (a canvas share link) and get a link back in one command. Three subcommands: `create` (build + share, with optional landing-page binding), `bind-landing` (bind/unbind a landing template on an existing share), and `scaffold` (print a starter `{source,security,landing}` spec for `--config-file`).
+
+```bash
+# simplest — email-gated link (server default auth_strategy=any_email)
+p dsr create --instance-id 01... --canvas-id 01... --api-key myapikey
+# open link
+p dsr create --instance-id 01... --canvas-id 01... --auth-strategy none
+# ShareBox + security + branded landing
+p dsr create --instance-id 01... --sharebox-file-ids 01A,01B --account-id 01... \
+  --auth-strategy specified_domains --allowed-domains acme.com --valid-until 2026-09-01T00:00:00Z \
+  --landing-template-id 01... --landing-context '{"rep":"Sam"}'
+# bind/unbind a landing template on an existing share
+p dsr bind-landing --id 01... --landing-template-id 01...
+p dsr bind-landing --id 01... --landing-template-id none
+# scaffold a spec for --config-file
+p dsr scaffold --out share.json
+```
+
+Creating needs a share-capable key; **binding a landing page currently needs an editor key** (PIT-7525 will open it to reps for their own DSRs) — a denied bind returns the link with a warning. Discover landing template IDs via `p dsr-landing list`.

package/dist/index.js

@@ -24,6 +24,8 @@ import { createMembershipsCommand } from './src/commands/memberships.js';
 import { createGroupsCommand } from './src/commands/groups.js';
 import { createRolesCommand } from './src/commands/roles.js';
 import { createMetadataTemplateCommand } from './src/commands/metadataTemplate.js';
+import { createDsrCommand } from './src/commands/dsr.js';
+import { createMcpCommand } from './src/commands/mcp.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -53,6 +55,8 @@ program.addCommand(createMembershipsCommand());
 program.addCommand(createGroupsCommand());
 program.addCommand(createRolesCommand());
 program.addCommand(createMetadataTemplateCommand());
+program.addCommand(createDsrCommand());
 program.addCommand(createOrgCommand());
 program.addCommand(createAnalyticsCommand());
+program.addCommand(createMcpCommand());
 program.parseAsync(process.argv);

package/dist/src/commands/dsr.d.ts

@@ -0,0 +1,36 @@
+import { Command } from 'commander';
+import type { AxiosInstance } from 'axios';
+import { type CommonOpts } from '../core/http.js';
+import { type Envelope } from '../core/envelope.js';
+export interface DsrDeps {
+    client?: AxiosInstance;
+}
+export declare function runDsrScaffold(opts: CommonOpts & {
+    out?: string;
+}, _deps?: DsrDeps): Promise<Envelope<unknown>>;
+export declare function runDsrBindLanding(opts: CommonOpts & {
+    id?: string;
+    landingTemplateId?: string;
+    landingContext?: string;
+    instanceId?: string;
+}, deps?: DsrDeps): Promise<Envelope<unknown>>;
+export interface DsrCreateOpts extends CommonOpts {
+    instanceId?: string;
+    canvasId?: string;
+    shareboxFileIds?: string[];
+    canvasName?: string;
+    accountId?: string;
+    templateId?: string;
+    authStrategy?: string;
+    allowedEmails?: string[];
+    allowedDomains?: string[];
+    validUntil?: string;
+    allowForward?: boolean;
+    allowDownload?: boolean;
+    tags?: string[];
+    landingTemplateId?: string;
+    landingContext?: string;
+    configFile?: string;
+}
+export declare function runDsrCreate(opts: DsrCreateOpts, deps?: DsrDeps): Promise<Envelope<unknown>>;
+export declare function createDsrCommand(): Command;

package/dist/src/commands/dsr.js

@@ -0,0 +1,229 @@
+import { Command } from 'commander';
+import { clientFor, toCliError } from '../core/http.js';
+import { ok, fail } from '../core/envelope.js';
+import { createCliError } from '../core/errors.js';
+import { emitEnvelope } from '../core/output.js';
+import { parseJsonObject, parseTags, isPlainObject } from '../schema/content.js';
+import { readTextFile } from '../core/readInput.js';
+import { withAuthFlags } from './withAuth.js';
+import { emitScaffold, DSR_SHARE_SCAFFOLD_JSON } from './scaffolds.js';
+const ENDPOINT = '/core/api/protected/shared-links';
+export async function runDsrScaffold(opts, _deps = {}) {
+    return emitScaffold(DSR_SHARE_SCAFFOLD_JSON, opts.out);
+}
+// resolve --landing-template-id text into the PUT value: undefined = not given; '' / 'none' = unbind (null); else the id
+function resolveTemplateId(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (raw === '' || raw.toLowerCase() === 'none')
+        return null;
+    return raw;
+}
+async function bindLandingRequest(client, id, body, instanceId) {
+    const url = `${ENDPOINT}/${encodeURIComponent(id)}/landing-page`;
+    const res = await client.put(url, body, instanceId ? { params: { instance_id: instanceId } } : undefined);
+    return res.data;
+}
+export async function runDsrBindLanding(opts, deps = {}) {
+    try {
+        if (!opts.id)
+            throw createCliError('VALIDATION', '--id is required for dsr bind-landing');
+        const templateId = resolveTemplateId(opts.landingTemplateId);
+        if (templateId === undefined)
+            throw createCliError('VALIDATION', '--landing-template-id is required (use "none" to unbind)');
+        const body = { landing_page_template_id: templateId };
+        if (opts.landingContext !== undefined)
+            body.landing_page_context = parseJsonObject(opts.landingContext, 'landing-context');
+        const client = clientFor(opts, deps);
+        const data = await bindLandingRequest(client, opts.id, body, opts.instanceId);
+        return ok(data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+const AUTH_STRATEGIES = [
+    'none', 'any_email', 'specified_emails', 'specified_domains', 'verified_emails', 'verified_domains',
+];
+const SPEC_FLAG_KEYS = [
+    'canvasId', 'shareboxFileIds', 'canvasName', 'accountId', 'templateId', 'authStrategy', 'allowedEmails',
+    'allowedDomains', 'validUntil', 'allowForward', 'allowDownload', 'tags', 'landingTemplateId', 'landingContext',
+];
+// config-file blocks must be JSON objects — a bare cast would silently spread a string/array into the request body
+function requirePlainObjectField(v, field) {
+    if (v === undefined)
+        return {};
+    if (!isPlainObject(v))
+        throw createCliError('VALIDATION', `config "${field}" must be a JSON object`);
+    return v;
+}
+function assembleSpec(opts) {
+    if (opts.configFile !== undefined) {
+        if (SPEC_FLAG_KEYS.some((k) => opts[k] !== undefined))
+            throw createCliError('VALIDATION', 'pass individual flags or --config-file, not both');
+        const cfg = parseJsonObject(readTextFile(opts.configFile), 'config');
+        const source = requirePlainObjectField(cfg.source, 'source');
+        const security = requirePlainObjectField(cfg.security, 'security');
+        // JSON null is a valid "no landing" opt-out, same as omitting the block
+        const landing = cfg.landing == null ? null : requirePlainObjectField(cfg.landing, 'landing');
+        const body = { ...source, ...security };
+        if (opts.instanceId !== undefined)
+            body.instance_id = opts.instanceId;
+        return { body, landing };
+    }
+    const body = {};
+    if (opts.instanceId !== undefined)
+        body.instance_id = opts.instanceId;
+    if (opts.canvasId !== undefined)
+        body.canvas_id = opts.canvasId;
+    if (opts.shareboxFileIds !== undefined)
+        body.sharebox_items = opts.shareboxFileIds.map((file_id) => ({ file_id }));
+    if (opts.canvasName !== undefined)
+        body.canvas_name = opts.canvasName;
+    if (opts.accountId !== undefined)
+        body.account_id = opts.accountId;
+    if (opts.templateId !== undefined)
+        body.template_id = opts.templateId;
+    if (opts.authStrategy !== undefined)
+        body.auth_strategy = opts.authStrategy;
+    if (opts.allowedEmails !== undefined)
+        body.allowed_emails = opts.allowedEmails;
+    if (opts.allowedDomains !== undefined)
+        body.allowed_domains = opts.allowedDomains;
+    if (opts.validUntil !== undefined)
+        body.valid_until = opts.validUntil;
+    if (opts.allowForward !== undefined)
+        body.allow_forward = opts.allowForward;
+    if (opts.allowDownload !== undefined)
+        body.allow_download = opts.allowDownload;
+    if (opts.tags !== undefined)
+        body.tags = opts.tags;
+    return { body, landing: null };
+}
+function assertCreateBody(body, instanceId) {
+    const hasCanvas = body.canvas_id !== undefined && body.canvas_id !== '';
+    const items = body.sharebox_items;
+    const hasSharebox = Array.isArray(items) && items.length > 0;
+    if (hasCanvas === hasSharebox)
+        throw createCliError('VALIDATION', 'pass exactly one source: --canvas-id or --sharebox-file-ids');
+    if (hasSharebox && !instanceId && body.instance_id === undefined)
+        throw createCliError('VALIDATION', '--instance-id is required for --sharebox-file-ids');
+    const strat = body.auth_strategy;
+    if (strat !== undefined) {
+        if (!AUTH_STRATEGIES.includes(strat))
+            throw createCliError('VALIDATION', `--auth-strategy must be one of: ${AUTH_STRATEGIES.join(', ')}`);
+        const emails = body.allowed_emails;
+        const domains = body.allowed_domains;
+        if ((strat === 'specified_emails' || strat === 'verified_emails') && !(emails && emails.length))
+            throw createCliError('VALIDATION', `--allowed-emails is required for --auth-strategy ${strat}`);
+        if ((strat === 'specified_domains' || strat === 'verified_domains') && !(domains && domains.length))
+            throw createCliError('VALIDATION', `--allowed-domains is required for --auth-strategy ${strat}`);
+    }
+}
+// binding a landing page on create needs a real template id — unlike bind-landing, there is nothing to unbind on a
+// brand-new share, so 'none'/''/null/missing (and a non-string config value) are all rejected as VALIDATION
+function requireCreateTemplateId(tid) {
+    const resolved = typeof tid === 'string' ? resolveTemplateId(tid) : tid;
+    if (typeof resolved !== 'string')
+        throw createCliError('VALIDATION', 'a landing template id is required to bind a landing page on create (use `dsr bind-landing` to unbind an existing share)');
+    return resolved;
+}
+// derive the landing PUT body from flags or from the config-file landing block; null if none requested
+function resolveLandingBody(opts, cfgLanding) {
+    if (opts.configFile !== undefined) {
+        if (!cfgLanding)
+            return null;
+        const tid = cfgLanding.landing_page_template_id;
+        const ctx = cfgLanding.landing_page_context;
+        // a blank/null template id with no (or empty) context = the untouched `dsr scaffold` default → no landing bind
+        const templateBlank = tid === undefined || tid === null || tid === '' || (typeof tid === 'string' && tid.toLowerCase() === 'none');
+        const contextEmpty = ctx === undefined || (isPlainObject(ctx) && Object.keys(ctx).length === 0);
+        if (templateBlank && contextEmpty)
+            return null;
+        const b = { landing_page_template_id: requireCreateTemplateId(tid) };
+        if (ctx !== undefined) {
+            if (!isPlainObject(ctx))
+                throw createCliError('VALIDATION', 'landing.landing_page_context must be a JSON object');
+            if (Object.keys(ctx).length > 0)
+                b.landing_page_context = ctx;
+        }
+        return b;
+    }
+    if (opts.landingTemplateId === undefined && opts.landingContext === undefined)
+        return null;
+    const b = { landing_page_template_id: requireCreateTemplateId(opts.landingTemplateId) };
+    if (opts.landingContext !== undefined)
+        b.landing_page_context = parseJsonObject(opts.landingContext, 'landing-context');
+    return b;
+}
+export async function runDsrCreate(opts, deps = {}) {
+    try {
+        const { body, landing: cfgLanding } = assembleSpec(opts);
+        assertCreateBody(body, opts.instanceId);
+        const landingBody = resolveLandingBody(opts, cfgLanding); // parse/validate context BEFORE the network call
+        // bind against the same instance the share was created in — a config-file source.instance_id must reach the PUT too
+        const effectiveInstanceId = body.instance_id ?? opts.instanceId;
+        const client = clientFor(opts, deps);
+        const res = await client.post(ENDPOINT, body);
+        const share = res.data;
+        if (!landingBody)
+            return ok(share);
+        const shareId = share?.id;
+        if (!shareId)
+            return ok({ ...share, landing: null }, ['landing not attached: no share id in create response']);
+        try {
+            const landing = await bindLandingRequest(client, shareId, landingBody, effectiveInstanceId);
+            return ok({ ...share, landing });
+        }
+        catch (e) {
+            return ok({ ...share, landing: null }, [`landing not attached: ${toCliError(e).message}`]);
+        }
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export function createDsrCommand() {
+    const cmd = new Command('dsr').description('create and share a Digital Sales Room (a canvas share link)');
+    withAuthFlags(cmd.command('scaffold'))
+        .description('print a {source,security,landing} share spec to fill in and pass to `dsr create --config-file`')
+        .option('--out <path>', 'Write the scaffold to a file instead of stdout')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runDsrScaffold({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('create'))
+        .description('create + share a DSR (canvas share link) and return the link')
+        .option('--instance-id <id>', 'Instance ID (required for --sharebox-file-ids)')
+        .option('--canvas-id <id>', 'Existing canvas to share (one source required)')
+        .option('--sharebox-file-ids <csv>', 'Build a canvas from these file IDs (one source required)', parseTags)
+        .option('--canvas-name <name>', 'Name for the ShareBox-built canvas')
+        .option('--account-id <id>', 'Account for the ShareBox-built canvas')
+        .option('--template-id <id>', 'Canvas template for the ShareBox-built canvas')
+        .option('--auth-strategy <v>', 'none|any_email|specified_emails|specified_domains|verified_emails|verified_domains')
+        .option('--allowed-emails <csv>', 'Allowed emails (required for specified/verified_emails)', parseTags)
+        .option('--allowed-domains <csv>', 'Allowed domains (required for specified/verified_domains)', parseTags)
+        .option('--valid-until <iso>', 'Expiry (ISO datetime)')
+        .option('--allow-forward', 'Allow recipients to forward')
+        .option('--no-allow-forward', 'Disallow forwarding')
+        .option('--allow-download', 'Allow download')
+        .option('--tags <csv>', 'Tags', parseTags)
+        .option('--landing-template-id <id>', 'Landing template to bind (optional)')
+        .option('--landing-context <json>', 'Landing personalization merge fields (JSON object)')
+        .option('--config-file <path>', 'Full {source,security,landing} spec JSON (mutually exclusive with the flags above)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runDsrCreate({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('bind-landing'))
+        .description("bind (or unbind with 'none') a landing-page template on an existing share")
+        .option('--id <id>', 'Shared link ID (required)')
+        .option('--landing-template-id <id>', "Landing template ID, or 'none' to unbind (required)")
+        .option('--landing-context <json>', 'Personalization merge fields (JSON object)')
+        .option('--instance-id <id>', 'Instance ID (optional)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runDsrBindLanding({ ...options, quiet: globals.quiet }), globals);
+    });
+    return cmd;
+}

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

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createMcpCommand(): Command;

package/dist/src/commands/mcp.js

@@ -0,0 +1,18 @@
+import { Command } from 'commander';
+import { runMcpServe } from '../mcp/serve.js';
+import { isCliError } from '../core/errors.js';
+export function createMcpCommand() {
+    return new Command('mcp')
+        .description('Run the Pitcher MCP server over stdio (reads NG_API_KEY, NG_ORG/NG_URL, NG_ENV from env)')
+        .action(async () => {
+        try {
+            await runMcpServe();
+        }
+        catch (e) {
+            const message = isCliError(e) ? e.message : e instanceof Error ? e.message : String(e);
+            console.error(`[pitcher-mcp] failed to start: ${message}`);
+            process.exitCode = isCliError(e) ? e.exitCode : 1;
+            return;
+        }
+    });
+}

package/dist/src/commands/scaffolds.d.ts

@@ -18,3 +18,4 @@ export declare const EMAIL_SCAFFOLD_HTML = "<!doctype html>\n<html lang=\"en\">\
 export declare const DSR_SCAFFOLD_HTML = "<!doctype html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"utf-8\" />\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n    <title>Sample DSR Landing Page</title>\n  </head>\n  <body style=\"margin:0;padding:0;background-color:#f4f4f4;font-family:Arial,Helvetica,sans-serif;color:#212121;\">\n    <table role=\"presentation\" width=\"100%\" cellpadding=\"0\" cellspacing=\"0\" style=\"padding:32px 0;\">\n      <tr>\n        <td align=\"center\">\n          <table role=\"presentation\" width=\"640\" cellpadding=\"0\" cellspacing=\"0\" style=\"background-color:#ffffff;border-radius:8px;overflow:hidden;\">\n            <tr>\n              <td style=\"background-color:var(--p-primary, #29335C);padding:28px;text-align:center;\">\n                <!-- token: organization.name -> the sharing org's display name -->\n                <span style=\"color:#ffffff;font-size:20px;font-weight:bold;\">{{organization.name}}</span>\n              </td>\n            </tr>\n            <tr>\n              <td style=\"padding:32px;\">\n                <!-- token: recipient.firstName -> the recipient's first name -->\n                <!-- token: customer.name -> the recipient's company name -->\n                <h1 style=\"margin:0 0 8px 0;font-size:22px;\">Welcome, {{recipient.firstName}}</h1>\n                <p style=\"margin:0 0 24px 0;color:#757575;font-size:14px;\">Prepared for {{customer.name}}</p>\n\n                <!--\n                  Editable region: admins can edit this block's text in the DSR\n                  landing editor without touching markup. data-field-char-limit\n                  enforces a max length in that editor.\n                -->\n                <div\n                  data-field-id=\"welcome-message\"\n                  data-field-editable=\"true\"\n                  data-field-char-limit=\"120\"\n                  style=\"padding:16px;margin:0 0 24px 0;border-left:3px solid var(--p-primary, #29335C);background-color:#f7f8fb;font-size:15px;line-height:1.5;\"\n                >\n                  Thanks for stopping by. Everything you need for this conversation is right here.\n                </div>\n\n                <!-- token: rep.name -> the sharing rep's display name -->\n                <p style=\"margin:0 0 24px 0;font-size:14px;color:#757575;\">Shared by {{rep.name}}</p>\n\n                <!--\n                  Required marker: the platform injects the email-gate form\n                  into this div at render time. It MUST be present verbatim\n                  (a literal data-pitcher-email-gate attribute) or the\n                  server rejects the template on create/update.\n                -->\n                <div data-pitcher-email-gate></div>\n              </td>\n            </tr>\n            <tr>\n              <td style=\"padding:16px 32px;border-top:1px solid #e0e2ed;text-align:center;color:#757575;font-size:12px;\">\n                <!-- token: sharedLink.valid_until -> when this share expires, if the share sets an expiry -->\n                This link is valid until {{sharedLink.valid_until}}.\n              </td>\n            </tr>\n          </table>\n        </td>\n      </tr>\n    </table>\n  </body>\n</html>\n";
 export declare const ANNOUNCEMENT_SCAFFOLD_JSON: string;
 export declare const METADATA_TEMPLATE_SCAFFOLD_JSON: string;
+export declare const DSR_SHARE_SCAFFOLD_JSON: string;

package/dist/src/commands/scaffolds.js

@@ -269,3 +269,27 @@ const METADATA_TEMPLATE_SCAFFOLD_DATA = [
     },
 ];
 export const METADATA_TEMPLATE_SCAFFOLD_JSON = JSON.stringify(METADATA_TEMPLATE_SCAFFOLD_DATA, null, 2);
+const DSR_SHARE_SCAFFOLD_DATA = {
+    source: {
+        // provide ONE of the following:
+        canvas_id: '01EXAMPLECANVASID000000000',
+        // sharebox_items: [{ file_id: '01EXAMPLEFILEID0000000000', page_index: 0 }],
+        // canvas_name: 'Acme QBR',
+        // account_id: '01EXAMPLEACCOUNTID00000000',
+        // template_id: '01EXAMPLECANVASTEMPLATE0000',
+    },
+    security: {
+        auth_strategy: 'any_email', // none|any_email|specified_emails|specified_domains|verified_emails|verified_domains
+        allowed_emails: [],
+        allowed_domains: [],
+        valid_until: null,
+        allow_forward: true,
+        allow_download: false,
+        tags: [],
+    },
+    landing: {
+        landing_page_template_id: null, // discover ids via `p dsr-landing list --instance-id <id>`
+        landing_page_context: {},
+    },
+};
+export const DSR_SHARE_SCAFFOLD_JSON = JSON.stringify(DSR_SHARE_SCAFFOLD_DATA, null, 2);

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

@@ -0,0 +1,7 @@
+export interface McpEnv {
+    apiKey: string;
+    org?: string;
+    url?: string;
+    prod: boolean;
+}
+export declare function resolveMcpEnv(env?: NodeJS.ProcessEnv): McpEnv;

package/dist/src/mcp/env.js

@@ -0,0 +1,13 @@
+import { createCliError } from '../core/errors.js';
+export function resolveMcpEnv(env = process.env) {
+    const apiKey = env.NG_API_KEY?.trim();
+    if (!apiKey) {
+        throw createCliError('AUTH', 'NG_API_KEY is required to run the MCP server (set it in the host config env).');
+    }
+    const org = env.NG_ORG?.trim() || 'dev';
+    const url = env.NG_URL?.trim() || undefined;
+    const ngEnv = env.NG_ENV?.trim();
+    const isDevHost = url ? /\/\/dev\.my\.pitcher\.com(\/|$)/.test(url) : org === 'dev';
+    const prod = ngEnv === 'prod' ? true : ngEnv === 'test' ? false : !isDevHost;
+    return { apiKey, org, url, prod };
+}

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

@@ -0,0 +1,2 @@
+import type { ToolDescriptor } from './tools/types.js';
+export declare const allTools: ToolDescriptor[];

package/dist/src/mcp/registry.js

@@ -0,0 +1,46 @@
+import { analyticsTools } from './tools/analytics.js';
+import { announcementsTools } from './tools/announcements.js';
+import { canvasesTools } from './tools/canvases.js';
+import { devSyncTools } from './tools/devSync.js';
+import { dsrTools } from './tools/dsr.js';
+import { dsrLandingTools } from './tools/dsrLanding.js';
+import { emailTemplateTools } from './tools/emailTemplate.js';
+import { filesTools } from './tools/files.js';
+import { foldersTools } from './tools/folders.js';
+import { groupsTools } from './tools/groups.js';
+import { instancesTools } from './tools/instances.js';
+import { invitationsTools } from './tools/invitations.js';
+import { membershipsTools } from './tools/memberships.js';
+import { metadataTemplateTools } from './tools/metadataTemplate.js';
+import { orgTools } from './tools/org.js';
+import { publishAppTools } from './tools/publishApp.js';
+import { rolesTools } from './tools/roles.js';
+import { searchTools } from './tools/search.js';
+import { sharedLinksTools } from './tools/sharedLinks.js';
+import { tagsTools } from './tools/tags.js';
+import { themesTools } from './tools/themes.js';
+import { usersTools } from './tools/users.js';
+export const allTools = [
+    ...canvasesTools,
+    ...filesTools,
+    ...foldersTools,
+    ...searchTools,
+    ...instancesTools,
+    ...sharedLinksTools,
+    ...tagsTools,
+    ...announcementsTools,
+    ...dsrLandingTools,
+    ...dsrTools,
+    ...emailTemplateTools,
+    ...themesTools,
+    ...usersTools,
+    ...invitationsTools,
+    ...rolesTools,
+    ...orgTools,
+    ...analyticsTools,
+    ...membershipsTools,
+    ...groupsTools,
+    ...metadataTemplateTools,
+    ...devSyncTools,
+    ...publishAppTools,
+];

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

@@ -0,0 +1,13 @@
+import type { Envelope } from '../core/envelope.js';
+export interface ToolTextContent {
+    type: 'text';
+    text: string;
+}
+export interface CallToolResultShape {
+    content: ToolTextContent[];
+    structuredContent?: Record<string, unknown>;
+    isError: boolean;
+    [key: string]: unknown;
+}
+export declare function toErrorResult(code: string, message: string): CallToolResultShape;
+export declare function envelopeToToolResult(env: Envelope<unknown>): CallToolResultShape;

package/dist/src/mcp/result.js

@@ -0,0 +1,20 @@
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+export function toErrorResult(code, message) {
+    return { content: [{ type: 'text', text: `${code}: ${message}` }], isError: true };
+}
+export function envelopeToToolResult(env) {
+    if (!env.ok) {
+        return toErrorResult(env.error?.code ?? 'UNKNOWN', env.error?.message ?? 'unknown error');
+    }
+    const text = env.data === undefined ? 'null' : JSON.stringify(env.data);
+    const content = [{ type: 'text', text }];
+    for (const w of env.warnings ?? [])
+        content.push({ type: 'text', text: `warning: ${w}` });
+    const result = { content, isError: false };
+    // structuredContent must be an object; omit for arrays/primitives (text still carries the data).
+    if (isPlainObject(env.data))
+        result.structuredContent = env.data;
+    return result;
+}

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

@@ -0,0 +1 @@
+export declare function runMcpServe(env?: NodeJS.ProcessEnv): Promise<void>;

package/dist/src/mcp/serve.js

@@ -0,0 +1,13 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { resolveMcpEnv } from './env.js';
+import { buildServer } from './server.js';
+import { allTools } from './registry.js';
+// Resolves auth/env, builds the server, connects stdio. Never writes to stdout except protocol frames.
+export async function runMcpServe(env = process.env) {
+    const mcpEnv = resolveMcpEnv(env);
+    const server = buildServer(mcpEnv);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    const target = mcpEnv.url ?? `https://${mcpEnv.org}.my.pitcher.com`;
+    console.error(`[pitcher-mcp] serving ${allTools.length} tools against ${target}${mcpEnv.prod ? ' (prod: destructive-hints on)' : ''}`);
+}

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

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { McpEnv } from './env.js';
+export declare function buildServer(env: McpEnv): McpServer;

package/dist/src/mcp/server.js

@@ -0,0 +1,41 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { allTools } from './registry.js';
+import { envelopeToToolResult, toErrorResult } from './result.js';
+import { isCliError } from '../core/errors.js';
+const version = (() => {
+    try {
+        const dir = dirname(fileURLToPath(import.meta.url));
+        return JSON.parse(readFileSync(join(dir, '..', '..', '..', 'package.json'), 'utf8')).version ?? '0.0.0';
+    }
+    catch {
+        // cosmetic server version; fall back if package.json is unreadable
+        return '0.0.0';
+    }
+})();
+export function buildServer(env) {
+    const server = new McpServer({ name: 'pitcher', version });
+    for (const tool of allTools) {
+        const destructive = tool.alwaysDestructive === true || (tool.write === true && env.prod);
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputShape,
+            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 });
+                return envelopeToToolResult(envelope);
+            }
+            catch (e) {
+                const code = isCliError(e) ? e.code : 'UNKNOWN';
+                const message = isCliError(e) ? e.message : e instanceof Error ? e.message : String(e);
+                return toErrorResult(code, message);
+            }
+        });
+    }
+    return server;
+}

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

@@ -0,0 +1,2 @@
+import type { ToolDescriptor } from './types.js';
+export declare const analyticsTools: ToolDescriptor[];

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

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { runAnalyticsOrg, runAnalyticsInstance } from '../../commands/analytics.js';
+export const analyticsTools = [
+    {
+        name: 'pitcher_analytics_org',
+        title: 'Org analytics rollups',
+        description: 'Read organization-wide analytics rollup totals. Requires an org-admin API key.',
+        inputShape: {},
+        run: runAnalyticsOrg,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_analytics_instance',
+        title: 'Instance analytics rollups',
+        description: 'Read analytics rollup totals for a single instance. Requires an instance-admin or org-admin API key.',
+        inputShape: { instanceId: z.string().describe('Instance ID (required)') },
+        run: runAnalyticsInstance,
+        readOnly: true,
+    },
+];

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

@@ -0,0 +1,2 @@
+import type { ToolDescriptor } from './types.js';
+export declare const announcementsTools: ToolDescriptor[];