@pitcher/cli-scripts 2.8.0 → 2.9.0

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

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import { runFoldersList, runFoldersGet, runFoldersCreate, runFoldersUpdate } from '../../commands/folders.js';
+export const foldersTools = [
+    {
+        name: 'pitcher_folders_list',
+        title: 'List folders',
+        description: 'List folders in an instance. Use to discover folder IDs before creating content or browsing structure.',
+        inputShape: {
+            instanceId: z.string().describe('Instance ID (required)'),
+            page: z.number().int().optional(),
+            pageSize: z.number().int().optional().describe('Page size (max 500)'),
+        },
+        run: runFoldersList,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_folders_get',
+        title: 'Get a folder',
+        description: 'Retrieve a single folder by its ID, or the instance root folder via root + instanceId.',
+        inputShape: {
+            id: z.string().optional().describe('Folder ID (omit and set root=true for the instance root)'),
+            root: z.boolean().optional().describe('Fetch the instance root folder'),
+            instanceId: z.string().optional().describe('Instance ID (required with root)'),
+        },
+        run: runFoldersGet,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_folders_create',
+        title: 'Create a folder',
+        description: 'Create a folder under a parent folder in an instance. Additive.',
+        inputShape: {
+            name: z.string().describe('Folder name (required)'),
+            parentFolderId: z.string().describe('Parent folder ID (required)'),
+            accessType: z.enum(['public', 'restricted', 'personal']).optional(),
+            rules: z.string().optional().describe('Smart-folder rules JSON array as a string'),
+        },
+        run: runFoldersCreate,
+        readOnly: false,
+        write: true,
+    },
+    {
+        name: 'pitcher_folders_update',
+        title: 'Update a folder',
+        description: 'Update an existing folder by ID (name, access type, or smart-folder rules; rules replace existing).',
+        inputShape: {
+            id: z.string().describe('Folder ID'),
+            name: z.string().optional().describe('Folder name'),
+            accessType: z.enum(['public', 'restricted', 'personal']).optional(),
+            rules: z.string().optional().describe('Smart-folder rules JSON array as a string (replaces existing)'),
+        },
+        run: runFoldersUpdate,
+        readOnly: false,
+        write: true,
+    },
+];

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

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

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

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import { runGroupsList, runGroupsGet, runGroupsCreate, runGroupsAddUser, runGroupsListUsers, } from '../../commands/groups.js';
+export const groupsTools = [
+    {
+        name: 'pitcher_groups_list',
+        title: 'List content-distribution groups',
+        description: 'List content-distribution groups. Filter by instance.',
+        inputShape: {
+            instanceId: z.string().optional().describe('Filter by instance'),
+            page: z.number().int().optional().describe('Page number'),
+            pageSize: z.number().int().optional().describe('Page size (max 500)'),
+        },
+        run: runGroupsList,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_groups_get',
+        title: 'Get a group',
+        description: 'Retrieve a single content-distribution group by its ID.',
+        inputShape: { id: z.string().describe('Group ID') },
+        run: runGroupsGet,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_groups_create',
+        title: 'Create a group',
+        description: 'Create a content-distribution group in an instance. Additive.',
+        inputShape: {
+            instanceId: z.string().describe('Instance ID (required)'),
+            name: z.string().describe('Group name (required)'),
+        },
+        run: runGroupsCreate,
+        readOnly: false,
+        write: true,
+    },
+    {
+        name: 'pitcher_groups_add_user',
+        title: 'Add a user to a group',
+        description: 'Add a user to a content-distribution group. Rejected on auto-login-managed groups.',
+        inputShape: {
+            groupId: z.string().describe('Group ID (required)'),
+            userId: z.string().describe('User ID (integer, required)'),
+        },
+        run: runGroupsAddUser,
+        readOnly: false,
+        write: true,
+    },
+    {
+        name: 'pitcher_groups_list_users',
+        title: "List a group's members",
+        description: "List a content-distribution group's members.",
+        inputShape: {
+            groupId: z.string().describe('Group whose members to list (required)'),
+            page: z.number().int().optional().describe('Page number'),
+            pageSize: z.number().int().optional().describe('Page size (max 500)'),
+        },
+        run: runGroupsListUsers,
+        readOnly: true,
+    },
+];

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

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

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

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import { runInstancesList, runInstancesInfo } from '../../commands/instances.js';
+export const instancesTools = [
+    {
+        name: 'pitcher_instances_list',
+        title: 'List instances',
+        description: 'Discover Pitcher instances in the org. Use to resolve instance names to instance IDs.' +
+            ' Output may include raw instance settings/metadata (potentially integration credentials) - treat as sensitive.',
+        inputShape: {
+            region: z.string().optional().describe('Filter by region'),
+            storageRegion: z.string().optional().describe('Filter by storage region'),
+            environment: z.string().optional().describe('Filter by environment'),
+            page: z.number().int().optional(),
+            pageSize: z.number().int().optional().describe('Page size (max 500)'),
+        },
+        run: runInstancesList,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_instances_info',
+        title: 'Get an instance',
+        description: 'Retrieve details for a single instance by its ID.' +
+            ' Output may include raw instance settings/metadata (potentially integration credentials) - treat as sensitive.',
+        inputShape: { id: z.string().describe('Instance ID') },
+        run: runInstancesInfo,
+        readOnly: true,
+    },
+];

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

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

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

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { runInvitationsList, runInvitationsGet } from '../../commands/invitations.js';
+export const invitationsTools = [
+    {
+        name: 'pitcher_invitations_list',
+        title: 'List invitations',
+        description: 'List pending user invitations in the org.',
+        inputShape: {
+            page: z.number().int().optional().describe('Page number'),
+            pageSize: z.number().int().optional().describe('Page size (max 500)'),
+        },
+        run: runInvitationsList,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_invitations_get',
+        title: 'Get an invitation',
+        description: 'Retrieve a single pending invitation by ID.',
+        inputShape: { id: z.string().describe('Invitation ID') },
+        run: runInvitationsGet,
+        readOnly: true,
+    },
+];

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

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

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

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { runMembershipsList, runMembershipsAdd, runMembershipsSetRole } from '../../commands/memberships.js';
+export const membershipsTools = [
+    {
+        name: 'pitcher_memberships_list',
+        title: 'List instance memberships',
+        description: 'List instance memberships. Filter by instance or user to discover membership IDs before set-role.',
+        inputShape: {
+            instanceId: z.string().optional().describe('Filter by instance'),
+            userId: z.string().optional().describe('Filter by user (integer id)'),
+            page: z.number().int().optional().describe('Page number'),
+            pageSize: z.number().int().optional().describe('Page size (max 500)'),
+        },
+        run: runMembershipsList,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_memberships_add',
+        title: 'Add a member',
+        description: "Add a user to an instance as 'member' (role is always 'member' — this endpoint never accepts a " +
+            "caller-supplied role). Use pitcher_memberships_set_role to change the role afterward.",
+        inputShape: {
+            instanceId: z.string().describe('Instance ID (required)'),
+            userId: z.string().describe('User ID (integer, required)'),
+        },
+        run: runMembershipsAdd,
+        readOnly: false,
+        write: true,
+    },
+    {
+        name: 'pitcher_memberships_set_role',
+        title: 'Set a membership role',
+        description: "Change a membership's role via the validating next-core endpoint. Requires an org-admin key. " +
+            "--role is the SHORT role name (e.g. 'editor') from pitcher_roles_list, not a prefixed key.",
+        inputShape: {
+            membershipId: z.string().describe('Membership row ID (integer, required)'),
+            role: z.string().describe('Short role name, e.g. editor (required)'),
+            scope: z
+                .enum(['instance', 'organization'])
+                .optional()
+                .describe('Scope of the role assignment (default instance)'),
+        },
+        run: runMembershipsSetRole,
+        readOnly: false,
+        write: true,
+    },
+];

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

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

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

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { runMetadataTemplateList, runMetadataTemplateGet, runMetadataTemplateUpsert, } from '../../commands/metadataTemplate.js';
+export const metadataTemplateTools = [
+    {
+        name: 'pitcher_metadata_template_list',
+        title: 'List metadata templates',
+        description: "List an instance's metadata-field schema(s) (metadata templates).",
+        inputShape: {
+            instanceId: z.string().describe('Instance ID (required)'),
+            page: z.number().int().optional().describe('Page number'),
+            pageSize: z.number().int().optional().describe('Page size (max 500)'),
+        },
+        run: runMetadataTemplateList,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_metadata_template_get',
+        title: 'Get a metadata template',
+        description: 'Retrieve a single metadata template by its ID (ULID).',
+        inputShape: { id: z.string().describe('Metadata template ID (ULID)') },
+        run: runMetadataTemplateGet,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_metadata_template_upsert',
+        title: 'Upsert a metadata template',
+        description: "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. Pass exactly one of sections or sectionsFile. Requires an instance- or org-admin key.',
+        inputShape: {
+            instanceId: z.string().describe('Instance ID (required)'),
+            sections: z.string().optional().describe('Sections JSON array (inline)'),
+            sectionsFile: z
+                .string()
+                .optional()
+                .describe('Path to a JSON file (on the MCP server host) with the sections array'),
+        },
+        run: runMetadataTemplateUpsert,
+        readOnly: false,
+        write: true,
+    },
+];

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

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

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

@@ -0,0 +1,12 @@
+import { runOrgGet } from '../../commands/org.js';
+export const orgTools = [
+    {
+        name: 'pitcher_org_get',
+        title: 'Get the organization',
+        description: 'Retrieve the organization the API key belongs to. Response may include raw settings/metadata ' +
+            '(potentially integration credentials) — treat output as sensitive.',
+        inputShape: {},
+        run: runOrgGet,
+        readOnly: true,
+    },
+];

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

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

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

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { runPublishApp } from '../../commands/publishApp.js';
+// Narrow individual injected/validated values (the MCP zod schema already guarantees the runtime
+// type) instead of casting the whole opts blob — same approach as the devSync wrappers.
+const asString = (v) => (typeof v === 'string' ? v : undefined);
+const asBool = (v) => (typeof v === 'boolean' ? v : undefined);
+export const publishAppTools = [
+    {
+        name: 'pitcher_publish_app',
+        title: 'Publish an app release',
+        description: 'Zip a local app folder (on the MCP server host) and publish it as a new app release to the org, ' +
+            'optionally installing it to specific instances or all instances of an environment afterward. ' +
+            'Consequential: this creates a live, org-visible app release — use dryRun to preview first. ' +
+            'Re-publishing an already-existing version is a no-op (returns ok with a warning), not a failure. ' +
+            'Publish targets the org resolved from NG_ORG; the injected NG_URL is not used as the publish endpoint.',
+        inputShape: {
+            folder: z.string().optional().describe('Local folder to zip and publish (defaults to the MCP server cwd)'),
+            incrementVersion: z.boolean().optional().describe('Bump the version in app.json before publishing'),
+            dryRun: z.boolean().optional().describe('Preview the publish (version, target) without publishing anything'),
+            installTo: z.string().optional().describe('Comma-separated instance IDs to install the app to after publishing'),
+            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.
+        run: (opts) => runPublishApp({
+            folder: asString(opts.folder),
+            incrementVersion: asBool(opts.incrementVersion),
+            dryRun: asBool(opts.dryRun),
+            installTo: asString(opts.installTo),
+            installToEnvName: asString(opts.installToEnvName),
+            apiKey: opts.apiKey,
+            org: opts.org,
+        }),
+        wraps: runPublishApp,
+        readOnly: false,
+        write: true,
+        alwaysDestructive: true,
+    },
+];

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

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

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

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import { runRolesList } from '../../commands/roles.js';
+export const rolesTools = [
+    {
+        name: 'pitcher_roles_list',
+        title: 'List roles',
+        description: 'List the org role set (system + custom roles) — use to discover valid short role names ' +
+            'before setting a membership role. Needs an org-admin key.',
+        inputShape: {
+            scope: z.enum(['instance', 'organization']).optional().describe('Filter by scope'),
+        },
+        run: runRolesList,
+        readOnly: true,
+    },
+];

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

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

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

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import { runSearch } from '../../commands/search.js';
+export const searchTools = [
+    {
+        name: 'pitcher_search',
+        title: 'Search content',
+        description: 'Cross-type ranked search across an instance (files, canvases, users, apps). Use to find content by keyword when the ID is unknown.',
+        inputShape: {
+            instanceId: z.string().describe('Instance ID (required)'),
+            query: z.string().describe('Search query (required)'),
+            includeExpired: z.boolean().optional().describe('Include expired content'),
+        },
+        run: runSearch,
+        readOnly: true,
+    },
+];

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

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

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

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import { runSharedLinksCreate, runSharedLinksGet } from '../../commands/sharedLinks.js';
+export const sharedLinksTools = [
+    {
+        name: 'pitcher_shared_links_create',
+        title: 'Create a shared link',
+        description: 'Create a share link (short_url) for a canvas or a file. Pass exactly one of canvasId or fileId. Additive.',
+        inputShape: {
+            canvasId: z.string().optional().describe('Canvas to share (exactly one of canvasId/fileId is required)'),
+            fileId: z.string().optional().describe('File to share (exactly one of canvasId/fileId is required)'),
+        },
+        run: runSharedLinksCreate,
+        readOnly: false,
+        write: true,
+    },
+    {
+        name: 'pitcher_shared_links_get',
+        title: 'Get a shared link',
+        description: 'Retrieve the existing share link for a canvas or a file. Pass exactly one of canvasId or fileId.',
+        inputShape: {
+            canvasId: z.string().optional().describe('Canvas whose link to fetch (exactly one of canvasId/fileId is required)'),
+            fileId: z.string().optional().describe('File whose link to fetch (exactly one of canvasId/fileId is required)'),
+        },
+        run: runSharedLinksGet,
+        readOnly: true,
+    },
+];

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

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

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

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { runTagsList } from '../../commands/tags.js';
+export const tagsTools = [
+    {
+        name: 'pitcher_tags_list',
+        title: 'List tags',
+        description: 'List tags in an instance matching a search term (at least 3 characters). Use to discover tag values before filtering files/canvases.',
+        inputShape: {
+            instanceId: z.string().describe('Instance ID (required)'),
+            search: z.string().min(3).describe('Search term (required, at least 3 characters)'),
+            type: z.enum(['files', 'canvases']).optional(),
+            canvasType: z.string().optional().describe('Canvas type filter'),
+            includeHidden: z.boolean().optional().describe('Include hidden tags'),
+            page: z.number().int().optional(),
+            pageSize: z.number().int().optional().describe('Page size (max 500)'),
+        },
+        run: runTagsList,
+        readOnly: true,
+    },
+];

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

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

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

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import { runThemesList, runThemesGet } from '../../commands/themes.js';
+export const themesTools = [
+    {
+        name: 'pitcher_themes_list',
+        title: 'List themes',
+        description: 'List canvas/branding themes (colors, fonts, assets) in the org. Omit instanceId to see all ' +
+            'org-level and instance themes; set it to narrow to themes bound to that instance.',
+        inputShape: {
+            instanceId: z
+                .string()
+                .optional()
+                .describe('Filter to themes bound to this instance (excludes org-level themes)'),
+            withUsage: z.boolean().optional().describe('Include a per-theme count of canvases using it'),
+            withCanvasIds: z.boolean().optional().describe('Include the canvas ids using each theme'),
+        },
+        run: runThemesList,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_themes_get',
+        title: 'Get a theme',
+        description: 'Retrieve a single theme by its ID.',
+        inputShape: { id: z.string().describe('Theme ID') },
+        run: runThemesGet,
+        readOnly: true,
+    },
+];

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

@@ -0,0 +1,15 @@
+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 interface ToolDescriptor {
+    name: string;
+    title: string;
+    description: string;
+    inputShape: z.ZodRawShape;
+    run: (opts: Record<string, unknown> & InjectedAuth, deps?: any) => Promise<Envelope<unknown>>;
+    wraps?: (...a: any[]) => unknown;
+    readOnly: boolean;
+    write?: boolean;
+    alwaysDestructive?: boolean;
+}

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

@@ -0,0 +1 @@
+export {};

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

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

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

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { runUsersList, runUsersGet } from '../../commands/users.js';
+export const usersTools = [
+    {
+        name: 'pitcher_users_list',
+        title: 'List users',
+        description: 'List users in the org. Use filters to narrow by instance membership, role, or active status.',
+        inputShape: {
+            instanceId: z.string().optional().describe('Filter to users with a membership in this instance'),
+            instanceRole: z.string().optional().describe('Filter by instance role (requires instanceId server-side)'),
+            role: z.string().optional().describe('Filter by org role'),
+            isActive: z
+                .literal(true)
+                .optional()
+                .describe('Filter to active users only (only true is meaningful; false is a no-op)'),
+            cdg: z.string().optional().describe('Filter to members of this content-distribution group'),
+            page: z.number().int().optional().describe('Page number'),
+            pageSize: z.number().int().optional().describe('Page size (max 500)'),
+        },
+        run: runUsersList,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_users_get',
+        title: 'Get a user',
+        description: 'Retrieve a single user by ID.',
+        inputShape: { id: z.string().describe('User ID (integer)') },
+        run: runUsersGet,
+        readOnly: true,
+    },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pitcher/cli-scripts",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "The Pitcher CLI for various tasks in its ecosystem.",
   "author": "Pitcher AG",
   "license": "MIT",
@@ -31,10 +31,12 @@
     "vitest": "^4.1.9"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1",
     "archiver": "^7.0.1",
     "axios": "^1.18.1",
     "chokidar": "^5.0.0",
     "commander": "^14.0.3",
-    "form-data": "^4.0.6"
+    "form-data": "^4.0.6",
+    "zod": "^3"
   }
 }