@pitcher/cli-scripts 3.1.1 → 3.3.0

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

@@ -3,6 +3,11 @@ 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';
+import { type AppViewDescriptor } from './apps/types.js';
+import type { HostClient, ProposalSigner } from './apps/confirm/types.js';
+import { type ToolAccess, type ToolGroup, type ToolPolicy } from './groups.js';
+/** The package version (the hosted audit records it as `server_version`). */
+export declare const CLI_SCRIPTS_VERSION: string;
 export declare const PITCHER_ICON = "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA1MTIgNTEyIiB3aWR0aD0iNTEyIiBoZWlnaHQ9IjUxMiI+PHJlY3Qgd2lkdGg9IjUxMiIgaGVpZ2h0PSI1MTIiIHJ4PSIxMTYiIGZpbGw9IiMyOTMzNUMiLz48Y2lyY2xlIGN4PSIzNzIiIGN5PSIxNTAiIHI9IjMwIiBmaWxsPSIjQ0MwMDAwIi8+PHBhdGggZmlsbD0iI2ZmZmZmZiIgZD0iTTE1MCAxMTZoOTZhOTIgOTIgMCAwIDEgMCAxODRoLTUwdjk2aC00NnoiLz48cGF0aCBmaWxsPSIjMjkzMzVDIiBkPSJNMTk2IDE2MHY5Nmg1MGE0OCA0OCAwIDAgMCAwLTk2eiIvPjwvc3ZnPg==";
 /**
  * The per-server request context: who every tool call runs as, and against which origin.
@@ -22,5 +27,62 @@ export interface BuildServerOptions {
      * is a build option, never a per-call field. Stdio passes `env.prod`; hosted always passes true.
      */
     destructiveWrites?: boolean;
+    /**
+     * MCP Apps (PIT-10066): the views for this request (all of them when the org's flag is on). Unset (local p mcp,
+     * hosted with the flag off) = every `ui` tool is skipped and instructions are unchanged, so the server is exactly today's.
+     */
+    apps?: {
+        views: AppViewDescriptor[];
+        loadHtml: (viewName: string) => string;
+        /** PIT-10113: the proposal signer for this request. Absent = no confirm tool is registered. */
+        proposals?: ProposalSigner;
+        /** PIT-10113: this request's host client class (chooses the proposal text tail only). */
+        hostClient?: HostClient;
+    };
+    /**
+     * PIT-10114: the org's tool policy. Hosted builds register only allowed tools already; this is defence in depth: a
+     * tool the policy forbids is refused (FORBIDDEN) without running. Unset (local p mcp) = no check.
+     */
+    policy?: ToolPolicy;
+    /** PIT-10114: one event per tool call. Unset = no-op (local p mcp). */
+    onToolCall?: ToolCallSink;
+}
+/** PIT-10114: one event per tool call. Ids only: never arguments, results, names or emails. */
+export interface ToolCallEvent {
+    tool: string;
+    group: ToolGroup;
+    /** accessOf(descriptor): the explicit class, never readOnlyHint */
+    access: ToolAccess;
+    outcome: 'ok' | 'error' | 'denied';
+    /** '' on ok; the CliError code (envelope or thrown), UNKNOWN for a thrown non-CliError, or
+     *  INVALID_ARGS | FORBIDDEN | GROUP_INACTIVE | GROUP_READ_ONLY | APP_DISABLED */
+    errorCode: string;
+    /** epoch ms when the call started (before run(); receipt time for denied and INVALID_ARGS) */
+    startedAt: number;
+    /** run() only; 0 for denied and INVALID_ARGS */
+    latencyMs: number;
+    /** HTTP status of the backend's error answer when the failure came from a backend response; 0 otherwise */
+    backendStatus: number;
+    /** the call's instanceId argument when it is a plain id token, else '' */
+    instanceId: string;
+    /** descriptor ui.visibility is exactly ['app'] */
+    viaApp: boolean;
+    /** PIT-10113 confirm tools only */
+    confirm?: {
+        role: 'propose' | 'commit';
+        action: string;
+        proposalId?: string;
+        status?: 'proposed' | 'committed' | 'already_committed' | 'refused';
+    };
 }
+export type ToolCallSink = (e: ToolCallEvent) => void | Promise<void>;
+/** The event, built field by field (never by spreading args or the envelope). */
+export declare function toolCallEvent(tool: ToolDescriptor, args: Record<string, unknown>, r: {
+    outcome: ToolCallEvent['outcome'];
+    errorCode: string;
+    startedAt: number;
+    latencyMs: number;
+    backendStatus: number;
+    data?: unknown;
+}): ToolCallEvent | undefined;
 export declare function buildServer(ctx: McpRunContext, tools?: ToolDescriptor[], prompts?: PromptDescriptor[], resources?: ResourceDescriptor[], opts?: BuildServerOptions): McpServer;

package/dist/src/mcp/server.js

@@ -1,14 +1,18 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from '@modelcontextprotocol/ext-apps/server';
 import { readFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { allTools } from './registry.js';
 import { allPrompts } from './prompts/registry.js';
 import { allResources } from './resources/registry.js';
-import { envelopeToToolResult, toErrorResult } from './result.js';
-import { ANALYTICS_RENDER_POLICY } from './renderPolicy.js';
+import { envelopeToToolResult, MAX_RESULT_BYTES, toErrorResult } from './result.js';
+import { ANALYTICS_RENDER_POLICY, APPS_RENDER_POLICY } from './renderPolicy.js';
+import { appViewUri } from './apps/types.js';
 import { isCliError } from '../core/errors.js';
-const version = (() => {
+import { accessOf, toolVerdict } from './groups.js';
+/** The package version (the hosted audit records it as `server_version`). */
+export const CLI_SCRIPTS_VERSION = (() => {
     try {
         const dir = dirname(fileURLToPath(import.meta.url));
         return JSON.parse(readFileSync(join(dir, '..', '..', '..', 'package.json'), 'utf8')).version ?? '0.0.0';
@@ -28,10 +32,79 @@ function errorText(e) {
         return `${e.code}: ${e.message}`;
     return e instanceof Error ? e.message : String(e);
 }
+const PLAIN_ID = /^[A-Za-z0-9_-]{1,200}$/;
+const CONFIRM_STATUSES = new Set(['proposed', 'committed', 'already_committed', 'refused']);
+/** A sink's throw or rejection never reaches the tool result. */
+function emitSafe(sink, e) {
+    if (!sink)
+        return Promise.resolve();
+    try {
+        return Promise.resolve(sink(e)).then(() => undefined, () => undefined);
+    }
+    catch {
+        return Promise.resolve();
+    }
+}
+/** The event, built field by field (never by spreading args or the envelope). */
+export function toolCallEvent(tool, args, r) {
+    if (!tool.group)
+        return undefined; // every hosted descriptor has one (checkDescriptor); nothing to attribute otherwise
+    const instanceId = typeof args.instanceId === 'string' && PLAIN_ID.test(args.instanceId) ? args.instanceId : '';
+    const v = tool.ui?.visibility;
+    const event = {
+        tool: tool.name,
+        group: tool.group,
+        access: accessOf(tool),
+        outcome: r.outcome,
+        errorCode: r.errorCode,
+        startedAt: r.startedAt,
+        latencyMs: r.latencyMs,
+        backendStatus: r.backendStatus,
+        instanceId,
+        viaApp: Array.isArray(v) && v.length === 1 && v[0] === 'app',
+    };
+    if (tool.confirm) {
+        const d = r.data && typeof r.data === 'object' ? r.data : {};
+        const proposalId = typeof d.proposalId === 'string' ? d.proposalId : undefined;
+        const status = r.outcome === 'ok'
+            ? typeof d.status === 'string' && CONFIRM_STATUSES.has(d.status)
+                ? d.status
+                : undefined
+            : 'refused';
+        event.confirm = {
+            role: tool.confirm.role,
+            action: tool.confirm.action,
+            ...(proposalId !== undefined ? { proposalId } : {}),
+            ...(status !== undefined ? { status } : {}),
+        };
+    }
+    return event;
+}
+/**
+ * Tool `_meta` for a `ui` tool. Keys come from ext-apps so they cannot drift. PIT-10113 adds the legacy OpenAI keys, belt
+ * and braces for ChatGPT: an app-only tool is `openai/visibility: private`, and every tool a view calls (app-only tools,
+ * and a propose tool, which the confirm view re-calls after an edit) is `openai/widgetAccessible`.
+ */
+function uiMeta(tool) {
+    const { ui } = tool;
+    const resourceUri = appViewUri(ui.view);
+    const appOnly = ui.visibility?.length === 1 && ui.visibility[0] === 'app';
+    return {
+        ui: { resourceUri, ...(ui.visibility ? { visibility: ui.visibility } : {}) },
+        [RESOURCE_URI_META_KEY]: resourceUri, // legacy key, older hosts
+        ...(appOnly ? { 'openai/visibility': 'private' } : {}),
+        ...(appOnly || tool.confirm?.role === 'propose' ? { 'openai/widgetAccessible': true } : {}),
+    };
+}
 export function buildServer(ctx, tools = allTools, prompts = allPrompts, resources = allResources, opts = {}) {
+    const enabled = new Set((opts.apps?.views ?? []).map((v) => v.name));
+    const instructions = enabled.size ? `${ANALYTICS_RENDER_POLICY}\n\n${APPS_RENDER_POLICY}` : ANALYTICS_RENDER_POLICY;
+    // A `ui` tool is registered only when its view is enabled for this server (D5); a confirm tool only with a signer.
+    const registered = tools.filter((t) => (!t.ui || enabled.has(t.ui.view)) && (!t.confirm || opts.apps?.proposals !== undefined));
+    const availableTools = new Set(registered.map((t) => t.name));
     const server = new McpServer({
         name: 'pitcher',
-        version,
+        version: CLI_SCRIPTS_VERSION,
         title: 'Pitcher',
         description: 'Search, manage, and share Pitcher content, canvases, files, DSRs, and instances.',
         websiteUrl: 'https://www.pitcher.com',
@@ -39,27 +112,79 @@ export function buildServer(ctx, tools = allTools, prompts = allPrompts, resourc
     }, 
     // Surfaced to the host model via InitializeResult.instructions — the analytics answer-rendering
     // policy so a natural-language question gets a right-sized reply (sentence / table / chart /
-    // dashboard) instead of a rigid full dashboard every time. See renderPolicy.ts.
-    { instructions: ANALYTICS_RENDER_POLICY });
-    for (const tool of tools) {
+    // dashboard) instead of a rigid full dashboard every time. See renderPolicy.ts. The apps paragraph rides
+    // along only when a view is enabled.
+    { instructions });
+    for (const tool of registered) {
         const destructive = tool.alwaysDestructive === true || (tool.write === true && opts.destructiveWrites === true);
         server.registerTool(tool.name, {
             title: tool.title,
             description: tool.description,
             inputSchema: tool.inputShape,
             annotations: { readOnlyHint: tool.readOnly, destructiveHint: destructive },
+            ...(tool.ui ? { _meta: uiMeta({ ...tool, ui: tool.ui }) } : {}),
         }, async (args) => {
+            const startedAt = Date.now();
+            // Defence in depth (PIT-10114): a hosted build never registers a forbidden tool; refuse it anyway, never run it.
+            if (opts.policy && toolVerdict(opts.policy, tool) !== 'allowed') {
+                const denied = toolCallEvent(tool, args, {
+                    outcome: 'denied',
+                    errorCode: 'FORBIDDEN',
+                    startedAt,
+                    latencyMs: 0,
+                    backendStatus: 0,
+                });
+                if (denied)
+                    void emitSafe(opts.onToolCall, denied); // nothing ran: never awaited
+                return toErrorResult('FORBIDDEN', 'This Pitcher tool is turned off for your organization.');
+            }
+            let result;
+            let outcome = 'ok';
+            let errorCode = '';
+            let backendStatus = 0;
+            let data;
             try {
                 const credential = ctx.resolveCredential ? await ctx.resolveCredential() : ctx.credential;
                 // spread args FIRST so injected auth/env always wins — never reorder to { credential, ...args }
-                const envelope = await tool.run({ ...args, credential, org: ctx.org, url: ctx.url });
-                return envelopeToToolResult(envelope);
+                // `availableTools`, `proposals` and `hostClient` reach `ui` tools only (D7); every other tool gets exactly today's keys
+                const injected = {
+                    credential,
+                    org: ctx.org,
+                    url: ctx.url,
+                    ...(tool.ui ? { availableTools, proposals: opts.apps?.proposals, hostClient: opts.apps?.hostClient } : {}),
+                };
+                const envelope = await tool.run({ ...args, ...injected });
+                if (!envelope.ok) {
+                    outcome = 'error';
+                    errorCode = envelope.error?.code ?? 'UNKNOWN';
+                    backendStatus = envelope.error?.backendStatus ?? 0;
+                }
+                data = envelope.data;
+                result = envelopeToToolResult(envelope, MAX_RESULT_BYTES, tool.ui ? tool.toText : undefined, tool.ui ? tool.textMaxBytes : undefined);
             }
             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);
+                outcome = 'error';
+                errorCode = code;
+                backendStatus = isCliError(e) ? (e.backendStatus ?? 0) : 0;
+                result = toErrorResult(code, message);
+            }
+            const event = toolCallEvent(tool, args, {
+                outcome,
+                errorCode,
+                startedAt,
+                latencyMs: Date.now() - startedAt,
+                backendStatus,
+                data,
+            });
+            if (event) {
+                const sent = emitSafe(opts.onToolCall, event);
+                // Write class waits for the audit attempt (the sink bounds itself); reads never do (G11).
+                if (event.access === 'write')
+                    await sent;
             }
+            return result;
         });
     }
     for (const prompt of prompts) {
@@ -85,5 +210,31 @@ export function buildServer(ctx, tools = allTools, prompts = allPrompts, resourc
             }
         });
     }
+    const apps = opts.apps;
+    for (const view of apps?.views ?? []) {
+        server.registerResource(view.name, appViewUri(view.name), { title: view.title, description: view.description, mimeType: RESOURCE_MIME_TYPE }, (uri) => {
+            try {
+                return {
+                    contents: [
+                        {
+                            uri: uri.href,
+                            mimeType: RESOURCE_MIME_TYPE,
+                            text: apps.loadHtml(view.name),
+                            _meta: {
+                                ui: {
+                                    csp: view.csp?.(ctx) ?? {},
+                                    ...(view.permissions ? { permissions: view.permissions } : {}),
+                                    prefersBorder: view.prefersBorder ?? true,
+                                },
+                            },
+                        },
+                    ],
+                };
+            }
+            catch (e) {
+                throw new Error(`app view "${view.name}" failed: ${errorText(e)}`);
+            }
+        });
+    }
     return server;
 }

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

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { KPI_TYPES } from '../../core/kpiTypes.js';
-import { runAnalyticsOrg, runAnalyticsInstance, runAnalyticsKpi, runAnalyticsEngagement, runAnalyticsPopularity, runAnalyticsUsers, runAnalyticsFiles, runAnalyticsCanvases, runAnalyticsViewers, runAnalyticsSessions, } from '../../commands/analytics.js';
+import { runAnalyticsOrg, runAnalyticsInstance, runAnalyticsKpi, runAnalyticsEngagement, runAnalyticsPopularity, runAnalyticsUsers, runAnalyticsFiles, runAnalyticsCanvases, runAnalyticsViewers, runAnalyticsSessions, runAnalyticsFileUsers, runAnalyticsFilePages, runAnalyticsCanvasUsers, runAnalyticsViewerVisits, } from '../../commands/analytics.js';
 export const analyticsTools = [
     {
         name: 'pitcher_analytics_org',
@@ -23,7 +23,7 @@ export const analyticsTools = [
         title: 'Instance KPI metrics',
         description: 'Read KPI metrics for an instance from the clickhouse analytics service (PIT-7647). ' +
             'Access follows the signed-in user’s own role; activity-metric types need start/end dates ' +
-            '(inventory counts like total-members do not).',
+            '(inventory counts like total-members do not). Every value and growth figure is a number.',
         inputShape: {
             instanceId: z.string().describe('Instance ID (required)'),
             type: z.enum(KPI_TYPES).describe('KPI type'),
@@ -97,7 +97,9 @@ export const analyticsTools = [
         name: 'pitcher_analytics_files',
         title: 'File usage analytics',
         description: 'File usage analytics for an instance (views/opens/engagement per file), summarized and capped to ' +
-            '`limit`. Requires an org-admin key. Defaults to a 30-day window when dates are omitted.',
+            '`limit`. Requires an org-admin key. Defaults to a 30-day window when dates are omitted. ' +
+            'Pass userEmails to answer "which files did this user open"; for "who opened this file" use ' +
+            'pitcher_analytics_file_users.',
         inputShape: {
             instanceId: z.string().describe('Instance ID (required)'),
             startDate: z.string().optional().describe('Window start, ISO date (defaults to 30 days ago)'),
@@ -173,4 +175,87 @@ export const analyticsTools = [
         run: runAnalyticsSessions,
         readOnly: true,
     },
+    {
+        name: 'pitcher_analytics_file_users',
+        title: 'Who opened a file',
+        description: 'Who opened ONE file in an instance: per user (email, name, role) the opens, seconds, days active and the ' +
+            'last day opened, sorted by opens and capped to `limit` (total_count/has_more state the cap). Internal users ' +
+            'only. pageNumber (0-based) narrows to one page of the file. Needs an instance editor, instance admin or org ' +
+            'admin. Defaults to a 30-day window. For time per page use pitcher_analytics_file_pages.',
+        inputShape: {
+            instanceId: z.string().describe('Instance ID (required)'),
+            fileId: z.string().describe('File ID (required)'),
+            startDate: z.string().optional().describe('Window start, ISO date (defaults to 30 days ago)'),
+            endDate: z.string().optional().describe('Window end, ISO date (defaults to today)'),
+            pageNumber: z.number().int().min(0).optional().describe('Only this page of the file (0-based)'),
+            groupIds: z.string().optional().describe('Comma-separated distribution-group IDs'),
+            userEmails: z.string().optional().describe('Comma-separated user emails to scope by'),
+            limit: z.number().int().optional().describe('Max rows to return (default 20, max 100)'),
+        },
+        run: runAnalyticsFileUsers,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_analytics_file_pages',
+        title: 'Time per page of a file',
+        description: 'Time per page of ONE file: per page (1-based page_number) the internal opens, internal seconds and mean ' +
+            'seconds, plus external (DSR) views. Pass a single userEmails value for one user\'s time per page. Every page ' +
+            'is returned. Needs an instance editor, instance admin or org admin. Defaults to a 30-day window.',
+        inputShape: {
+            instanceId: z.string().describe('Instance ID (required)'),
+            fileId: z.string().describe('File ID (required)'),
+            startDate: z.string().optional().describe('Window start, ISO date (defaults to 30 days ago)'),
+            endDate: z.string().optional().describe('Window end, ISO date (defaults to today)'),
+            groupIds: z.string().optional().describe('Comma-separated distribution-group IDs'),
+            userEmails: z.string().optional().describe('Comma-separated user emails to scope by (one email: that user)'),
+        },
+        run: runAnalyticsFilePages,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_analytics_canvas_users',
+        title: 'Per-user canvas usage',
+        description: 'Per-user canvas usage in an instance: one row per user and canvas (who, canvas_id, canvas_name, views = ' +
+            'visits, total_seconds, last_viewed_at), most visits first, `limit` rows per page with total_count/has_more. ' +
+            'With canvasId, each row also lists the pages (sections) of that canvas the user viewed with their seconds. ' +
+            'Internal users only (external DSR viewers: pitcher_analytics_viewer_visits); presentation time only, not ' +
+            'editing. Needs an instance editor, instance admin or org admin. Defaults to a 30-day window.',
+        inputShape: {
+            instanceId: z.string().describe('Instance ID (required)'),
+            canvasId: z.string().optional().describe("One canvas: adds each user's seconds per page (section)"),
+            startDate: z.string().optional().describe('Window start, ISO date (defaults to 30 days ago)'),
+            endDate: z.string().optional().describe('Window end, ISO date (defaults to today)'),
+            groupIds: z.string().optional().describe('Comma-separated distribution-group IDs'),
+            userEmails: z.string().optional().describe('Comma-separated user emails to scope by'),
+            page: z.number().int().optional().describe('Page number (default 1)'),
+            limit: z.number().int().optional().describe('Rows per page (default 20, max 100)'),
+        },
+        run: runAnalyticsCanvasUsers,
+        readOnly: true,
+    },
+    {
+        name: 'pitcher_analytics_viewer_visits',
+        title: 'DSR viewer visits and page time',
+        description: 'Per viewer of a DSR canvas: each visit (start, engaged seconds) and in it the sections, files and pages ' +
+            'viewed with views and seconds (`estimated: true` where an exit event was missing and the time is ' +
+            'inferred). One viewer (userEmail, verbatim from pitcher_analytics_viewers) or the most recently active ' +
+            'viewers (limit, default 10, max 25; viewers_total and truncated state the cap). format "csv" returns the ' +
+            'same as CSV text in `csv` (one row per viewer, visit and item) with a suggested filename, for export: hand ' +
+            'it to the user as a file. Works for any member. The server applies its own default window.',
+        inputShape: {
+            instanceId: z.string().describe('Instance ID (required)'),
+            canvasId: z.string().describe('DSR canvas ID (required)'),
+            userEmail: z
+                .string()
+                .optional()
+                .describe('One viewer: normalized_email (or email) from pitcher_analytics_viewers, VERBATIM'),
+            viewerType: z.string().optional().describe("Viewer type when listing: all, internal, external (default 'all')"),
+            startDate: z.string().optional().describe('Window start, ISO date (server default applies if omitted)'),
+            endDate: z.string().optional().describe('Window end, ISO date (server default applies if omitted)'),
+            limit: z.number().int().optional().describe('Viewers to read when no userEmail (default 10, max 25)'),
+            format: z.enum(['json', 'csv']).optional().describe('json (default) or csv for an export'),
+        },
+        run: runAnalyticsViewerVisits,
+        readOnly: true,
+    },
 ];

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

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

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

@@ -0,0 +1,135 @@
+import { z } from 'zod';
+import { ROLEPLAY_DIFFICULTIES, ROLEPLAY_GROUP_BY, ROLEPLAY_PATH_STATUSES, ROLEPLAY_SESSION_SORT, runRoleplayKpis, runRoleplayPathsList, runRoleplayRepSummary, runRoleplayScenariosList, runRoleplaySessionGet, runRoleplaySessions, runRoleplayTeam, } from '../../commands/roleplay.js';
+const instanceId = z.string().describe('Instance ID (required)');
+/** The shared roleplay_statements filters. Dates have NO default window: omitted means all time. */
+const filters = {
+    instanceId,
+    startDate: z.string().optional().describe('Window start, ISO date. Omitted = all time (no default window)'),
+    endDate: z.string().optional().describe('Window end, ISO date. Omitted = all time (no default window)'),
+    rep: z.string().optional().describe('Rep name or email contains (case-insensitive)'),
+    scenario: z.string().optional().describe('Scenario or persona name contains (case-insensitive)'),
+    difficulty: z.enum(ROLEPLAY_DIFFICULTIES).optional().describe('Scenario difficulty'),
+};
+const UNSCORED = 'A session without a score (score null: the AI evaluation failed or is pending) is UNSCORED, never 0: ' +
+    'never count it in an average or as a fail.';
+const CH_SOURCE = 'Reads the AI Roleplay analytics replica (ClickHouse roleplay_statements, the Admin Analytics tab). ' +
+    'Dates are optional and there is no default window: omitted means all time.';
+const ADMIN_ONLY = 'Instance or org admins only; anyone else gets an AUTH error, and a coaching manager should use pitcher_roleplay_team.';
+export const roleplayTools = [
+    {
+        name: 'pitcher_roleplay_kpis',
+        title: 'AI Roleplay KPIs',
+        description: 'AI Roleplay totals for an instance: total, scored and unscored sessions, the mean score of SCORED sessions, ' +
+            `mean duration and active reps, with optional rep/scenario/difficulty filters. ${UNSCORED} ${CH_SOURCE} ${ADMIN_ONLY}`,
+        inputShape: filters,
+        run: runRoleplayKpis,
+        readOnly: true,
+        group: 'roleplay',
+    },
+    {
+        name: 'pitcher_roleplay_sessions',
+        title: 'AI Roleplay sessions',
+        description: 'AI Roleplay session list for an instance, newest first: entry_id, session_at, rep_name, who (rep email), ' +
+            'scenario_name, persona_name, difficulty, score, evaluated, rating, duration_ms. Default 20 rows, max 100 per ' +
+            `page; total_count/has_more say when there are more. ${UNSCORED} ${CH_SOURCE} ${ADMIN_ONLY} ` +
+            'Open one session with pitcher_roleplay_session_get (its entry_id).',
+        inputShape: {
+            ...filters,
+            sortBy: z.enum(ROLEPLAY_SESSION_SORT).optional().describe('Sort field (default session_at)'),
+            sortOrder: z.enum(['asc', 'desc']).optional().describe('Sort direction (default desc); unscored sessions sort last'),
+            page: z.number().int().optional().describe('Page number (default 1)'),
+            limit: z.number().int().optional().describe('Rows per page (default 20, max 100)'),
+        },
+        run: runRoleplaySessions,
+        readOnly: true,
+        group: 'roleplay',
+    },
+    {
+        name: 'pitcher_roleplay_rep_summary',
+        title: 'AI Roleplay per-rep or per-scenario summary',
+        description: 'Per-rep (groupBy rep, keyed on the rep email) or per-scenario (groupBy scenario) session counts, scored ' +
+            'counts, mean score of scored sessions and last session, up to 50 groups with the most sessions. Exact up to ' +
+            '5000 sessions in the window (read newest first); `complete: false` means the figures cover only the newest ' +
+            `5000, so narrow the dates. ${UNSCORED} ${CH_SOURCE} ${ADMIN_ONLY}`,
+        inputShape: {
+            ...filters,
+            groupBy: z.enum(ROLEPLAY_GROUP_BY).optional().describe('Group by rep (default) or scenario'),
+        },
+        run: runRoleplayRepSummary,
+        readOnly: true,
+        group: 'roleplay',
+    },
+    {
+        name: 'pitcher_roleplay_team',
+        title: 'AI Roleplay assignment completion',
+        description: 'Roleplay assignment completion per rep, as the AI Roleplay manager app shows it: per assignment its passing ' +
+            'score and due date, each rep\'s status (passed, in_progress, not_started, overdue, needs_coaching), sessions, ' +
+            'scored sessions, best and mean score, trend, last session, plus per-skill mean scores. Instance or org admins ' +
+            'get every roleplay assignment on the instance (scope "instance"); a coaching manager gets the assignments ' +
+            'they coach (scope "coach"). Works for any member (an empty list when they coach nobody). ' +
+            `${UNSCORED} Reads Postgres appsDB through next-core (cch-assignment, cch-session-result), not ClickHouse. ` +
+            'The server returns at most the newest 1000 sessions; `complete: false` says the cap was hit. ' +
+            'Up to 50 assignments and 100 reps each; filter with assignmentId or status. ' +
+            'sessions and best_score count every attempt since the assignment started (server pass progress); ' +
+            'recent_only true means avg_score, scored_sessions and trend cover only the newest listed sessions; ' +
+            'coverage says whether pass progress was loaded; assignments are ordered active first, then by due date, ' +
+            'and reps most urgent first.',
+        inputShape: {
+            instanceId,
+            assignmentId: z.string().optional().describe('Only this assignment (its id from an earlier call)'),
+            status: z
+                .enum(['passed', 'in_progress', 'not_started', 'overdue', 'needs_coaching'])
+                .optional()
+                .describe('Only reps with this status'),
+        },
+        run: runRoleplayTeam,
+        readOnly: true,
+        group: 'roleplay',
+    },
+    {
+        name: 'pitcher_roleplay_session_get',
+        title: 'AI Roleplay session detail',
+        description: 'One AI Roleplay session: scenario, difficulty, time, duration, overall score (null = unscored, never 0), ' +
+            'evaluation status, and the evaluation summary, strengths, improvements and per-skill scores with feedback, ' +
+            'and the grading scale. ' +
+            'Never the transcript, messages or recordings. Opens to the rep, a coach of that rep, or an instance or org ' +
+            'admin; anyone else gets an AUTH error. Reads Postgres appsDB (cch-session-result) through next-core. ' +
+            'Takes entryId = entry_id from pitcher_roleplay_sessions (admins) or, where that tool is available, a session ' +
+            'id from pitcher_roleplay_rep_sessions (coaches).',
+        inputShape: {
+            instanceId,
+            entryId: z
+                .string()
+                .describe('Session entry ID (entry_id from pitcher_roleplay_sessions, or a session id from pitcher_roleplay_rep_sessions where available)'),
+        },
+        run: runRoleplaySessionGet,
+        readOnly: true,
+        group: 'roleplay',
+    },
+    {
+        name: 'pitcher_roleplay_scenarios_list',
+        title: 'AI Roleplay scenarios',
+        description: 'The AI Roleplay scenario catalog of an instance: id, kind, name, persona title, description, difficulty, ' +
+            'active, time limit and the skills it is graded on (title and weight). Never a prompt. Any member. ' +
+            'Reads the instance config (appsDB cch-config) through next-core.',
+        inputShape: { instanceId },
+        run: runRoleplayScenariosList,
+        readOnly: true,
+        group: 'roleplay',
+    },
+    {
+        name: 'pitcher_roleplay_paths_list',
+        title: 'AI Roleplay learning paths',
+        description: "The instance's AI Roleplay learning paths: id, name, status, version, stage and step counts, default passing " +
+            'score, last update. Default published only. Instance admins and editors and org admins; 404 when learning ' +
+            'paths are off on the instance or you are not a member.',
+        inputShape: {
+            instanceId,
+            status: z.enum(ROLEPLAY_PATH_STATUSES).optional().describe('published (default), draft or all'),
+        },
+        run: runRoleplayPathsList,
+        readOnly: true,
+        access: 'read',
+        group: 'roleplay',
+    },
+];

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

@@ -1,7 +1,27 @@
 import type { z } from 'zod';
 import type { Envelope } from '../../core/envelope.js';
 import type { CommonOpts } from '../../core/http.js';
+import type { ToolAccess, ToolGroup } from '../groups.js';
+import type { HostClient, ProposalSigner } from '../apps/confirm/types.js';
+export type { ToolAccess, ToolGroup } from '../groups.js';
 export type InjectedAuth = Pick<CommonOpts, 'apiKey' | 'credential' | 'org' | 'url'>;
+export type AppToolVisibility = 'model' | 'app';
+/** MCP Apps (PIT-10066): attach a view (`ui://pitcher/<view>.html`) to a tool's result. */
+export interface ToolUi {
+    /** AppViewDescriptor.name, e.g. 'content-picker' -> ui://pitcher/content-picker.html */
+    view: string;
+    /** Default ['model', 'app']. ['app'] = app-only helper, hidden from the model by UI hosts. */
+    visibility?: AppToolVisibility[];
+}
+/** Extra keys buildServer injects into a `ui` tool's run (and ONLY into those). */
+export interface AppInjected {
+    /** Names of the tools registered on THIS server (hosted: depends on the org's access mode). */
+    availableTools: ReadonlySet<string>;
+    /** PIT-10113: mints and opens proposal tokens for THIS request's caller and host client. Absent = no confirm tools. */
+    proposals?: ProposalSigner;
+    /** PIT-10113: the host client class of THIS request. Absent = `appsHost: false` (the 'host_prompt' text tail). */
+    hostClient?: HostClient;
+}
 export interface ToolDescriptor {
     name: string;
     title: string;
@@ -10,6 +30,21 @@ export interface ToolDescriptor {
     run: (opts: Record<string, unknown> & InjectedAuth, deps?: any) => Promise<Envelope<unknown>>;
     wraps?: (...a: any[]) => unknown;
     readOnly: boolean;
+    /** PIT-10114: the tool group. Set by registry.ts (inGroup) or on the descriptor (app and confirm tools). */
+    group?: ToolGroup;
+    /** PIT-10114: policy class. 'write' = changes data OR only leads to a change (PIT-10113 _propose and _commit). Required for every new tool. */
+    access?: ToolAccess;
+    /** PIT-10113 confirm tools (propose / commit pair); registered only when a proposal signer exists. */
+    confirm?: {
+        role: 'propose' | 'commit';
+        action: string;
+    };
     write?: boolean;
     alwaysDestructive?: boolean;
+    /** MCP Apps: render this tool's result in a view. Registered ONLY when buildServer gets opts.apps with this view enabled. */
+    ui?: ToolUi;
+    /** `ui` tools only: the text block for the model (short); `structuredContent` carries the full data. */
+    toText?: (data: unknown) => string;
+    /** `ui` tools only: byte budget of the `toText` line (default 8,000). Only PIT-10113 propose tools raise it. */
+    textMaxBytes?: number;
 }

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "@pitcher/cli-scripts",
-  "version": "3.1.1",
+  "version": "3.3.0",
   "description": "The Pitcher CLI for various tasks in its ecosystem.",
   "author": "Pitcher AG",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PitcherAG/web.git",
+    "directory": "packages/libs/cli-scripts"
+  },
   "keywords": [
     "pitcher",
     "cli",
@@ -51,6 +56,7 @@
     "vitest": "^5.0.1"
   },
   "dependencies": {
+    "@modelcontextprotocol/ext-apps": "1.7.5",
     "@modelcontextprotocol/sdk": "^1",
     "archiver": "^8.0.0",
     "axios": "^1.18.1",