@pitcher/cli-scripts 3.2.0 → 3.3.0

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/roleplay.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { ROLEPLAY_DIFFICULTIES, ROLEPLAY_GROUP_BY, ROLEPLAY_SESSION_SORT, runRoleplayKpis, runRoleplayRepSummary, runRoleplayScenariosList, runRoleplaySessionGet, runRoleplaySessions, runRoleplayTeam, } from '../../commands/roleplay.js';
+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 = {
@@ -24,6 +24,7 @@ export const roleplayTools = [
         inputShape: filters,
         run: runRoleplayKpis,
         readOnly: true,
+        group: 'roleplay',
     },
     {
         name: 'pitcher_roleplay_sessions',
@@ -41,6 +42,7 @@ export const roleplayTools = [
         },
         run: runRoleplaySessions,
         readOnly: true,
+        group: 'roleplay',
     },
     {
         name: 'pitcher_roleplay_rep_summary',
@@ -55,6 +57,7 @@ export const roleplayTools = [
         },
         run: runRoleplayRepSummary,
         readOnly: true,
+        group: 'roleplay',
     },
     {
         name: 'pitcher_roleplay_team',
@@ -66,7 +69,11 @@ export const roleplayTools = [
             '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.',
+            '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)'),
@@ -77,21 +84,27 @@ export const roleplayTools = [
         },
         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. ' +
+            '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.',
+            '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)'),
+            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',
@@ -102,5 +115,21 @@ export const roleplayTools = [
         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,6 +1,6 @@
 {
   "name": "@pitcher/cli-scripts",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "The Pitcher CLI for various tasks in its ecosystem.",
   "author": "Pitcher AG",
   "license": "MIT",
@@ -56,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",