@pitcher/cli-scripts 3.2.0 → 3.3.0

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

@@ -0,0 +1,42 @@
+/**
+ * PIT-10114: tool groups, the per-org policy and the access class of every tool.
+ *
+ * An org sets each group to off | read | read_write in `pitcher_organization.settings.mcp.groups`; `settings.mcp.access`
+ * stays the master switch and the ceiling (read_only caps every group at read). L&D is off unless the org turns it on.
+ * Inactive tools are absent from tools/list, and a call to one is refused and recorded.
+ */
+import type { ToolDescriptor } from './tools/types.js';
+export declare const TOOL_GROUPS: readonly ["content", "sharing", "analytics", "roleplay", "training_studio", "ld", "admin", "search", "developer"];
+export type ToolGroup = (typeof TOOL_GROUPS)[number];
+/** Policy class: 'write' = changes data OR exists only to lead to a change (PIT-10113 _propose and _commit). */
+export type ToolAccess = 'read' | 'write';
+export type GroupLevel = 'off' | 'read' | 'read_write';
+export type ToolPolicy = Readonly<Record<ToolGroup, GroupLevel>>;
+/**
+ * Groups an org may configure (developer is local-only). Django mirrors this list (`MCP_GROUPS` in
+ * ng-rest-api `pitcher/utils/validators.py`, which refuses unknown groups): add a group THERE FIRST.
+ */
+export declare const CONFIGURABLE_GROUPS: readonly ToolGroup[];
+export interface ResolvedPolicy {
+    policy: ToolPolicy;
+    /** Invalid or unknown keys ('groups' when malformed); logged once per fetch, never shown to users. */
+    warnings: string[];
+}
+export declare const OFF_POLICY: ToolPolicy;
+/** `settings.mcp` → per-group levels. Fails closed: no valid `access`, malformed `groups`, an invalid level. */
+export declare function resolveToolPolicy(mcp: unknown): ResolvedPolicy;
+type AccessFields = Pick<ToolDescriptor, 'access' | 'readOnly' | 'write' | 'alwaysDestructive'>;
+/** The policy class of a tool: explicit `access`, else the legacy read-only predicate (frozen for today's tools). */
+export declare function accessOf(t: AccessFields): ToolAccess;
+export type ToolVerdict = 'allowed' | 'GROUP_INACTIVE' | 'GROUP_READ_ONLY' | 'UNGROUPED';
+export declare function toolVerdict(policy: ToolPolicy, t: AccessFields & Pick<ToolDescriptor, 'group'>): ToolVerdict;
+/** A prompt drives a write tool unless flagged `readOnly`, so a group at `read` serves only the read-only ones. */
+export declare function allowsPrompt(policy: ToolPolicy, p: {
+    group?: ToolGroup;
+    readOnly?: true;
+}): boolean;
+/** Hard rules on every registered descriptor: a group, and no write tool classed `read`. */
+export declare function checkDescriptor(t: ToolDescriptor): ToolDescriptor;
+/** Assign a whole module to a group; a descriptor that already names another group throws. */
+export declare function inGroup(group: ToolGroup, tools: ToolDescriptor[]): ToolDescriptor[];
+export {};

package/dist/src/mcp/groups.js

@@ -0,0 +1,89 @@
+export const TOOL_GROUPS = [
+    'content',
+    'sharing',
+    'analytics',
+    'roleplay',
+    'training_studio',
+    'ld',
+    'admin',
+    'search',
+    'developer',
+];
+/**
+ * Groups an org may configure (developer is local-only). Django mirrors this list (`MCP_GROUPS` in
+ * ng-rest-api `pitcher/utils/validators.py`, which refuses unknown groups): add a group THERE FIRST.
+ */
+export const CONFIGURABLE_GROUPS = TOOL_GROUPS.filter((g) => g !== 'developer');
+const DEFAULT_OFF = new Set(['ld']); // N1 ruling, 2026-11-10
+const RANK = { off: 0, read: 1, read_write: 2 };
+const LEVELS = new Set(['off', 'read', 'read_write']);
+/** The keys `settings.mcp` may hold; mirrors `MCP_KEYS` in ng-rest-api `pitcher/utils/validators.py`. */
+const MCP_KEYS = new Set(['access', 'groups']);
+export const OFF_POLICY = Object.freeze(Object.fromEntries(TOOL_GROUPS.map((g) => [g, 'off'])));
+/** `settings.mcp` → per-group levels. Fails closed: no valid `access`, malformed `groups`, an invalid level. */
+export function resolveToolPolicy(mcp) {
+    const raw = (mcp && typeof mcp === 'object' && !Array.isArray(mcp) ? mcp : {});
+    if (raw.access !== 'full' && raw.access !== 'read_only')
+        return { policy: OFF_POLICY, warnings: [] };
+    const ceiling = raw.access === 'full' ? 'read_write' : 'read';
+    const g0 = raw.groups ?? {};
+    if (typeof g0 !== 'object' || Array.isArray(g0))
+        return { policy: OFF_POLICY, warnings: ['groups'] };
+    const groups = g0;
+    const warnings = [
+        // A top-level typo (`group`, `Groups`) leaves `groups` absent, so every group takes its default. Django refuses
+        // unknown keys at save (ng-rest-api#1809, `MCP_KEYS`); report any that reach us anyway, as `mcp.<key>`.
+        ...Object.keys(raw).filter((k) => !MCP_KEYS.has(k)).map((k) => `mcp.${k}`),
+        ...Object.keys(groups).filter((k) => !CONFIGURABLE_GROUPS.includes(k)),
+    ];
+    const policy = { ...OFF_POLICY };
+    for (const g of CONFIGURABLE_GROUPS) {
+        const v = groups[g];
+        let requested;
+        if (v === undefined)
+            requested = DEFAULT_OFF.has(g) ? 'off' : ceiling;
+        else if (typeof v === 'string' && LEVELS.has(v))
+            requested = v;
+        else {
+            requested = 'off';
+            warnings.push(g);
+        }
+        policy[g] = RANK[requested] <= RANK[ceiling] ? requested : ceiling;
+    }
+    return { policy: Object.freeze(policy), warnings };
+}
+/** The policy class of a tool: explicit `access`, else the legacy read-only predicate (frozen for today's tools). */
+export function accessOf(t) {
+    return t.access ?? (t.readOnly && !t.write && !t.alwaysDestructive ? 'read' : 'write');
+}
+export function toolVerdict(policy, t) {
+    if (!t.group)
+        return 'UNGROUPED'; // fail closed
+    const level = policy[t.group];
+    if (level === 'off')
+        return 'GROUP_INACTIVE';
+    return accessOf(t) === 'read' || level === 'read_write' ? 'allowed' : 'GROUP_READ_ONLY';
+}
+/** A prompt drives a write tool unless flagged `readOnly`, so a group at `read` serves only the read-only ones. */
+export function allowsPrompt(policy, p) {
+    if (!p.group)
+        return false;
+    const level = policy[p.group];
+    return level === 'read_write' || (level === 'read' && p.readOnly === true);
+}
+/** Hard rules on every registered descriptor: a group, and no write tool classed `read`. */
+export function checkDescriptor(t) {
+    if (!t.group)
+        throw new Error(`${t.name}: no tool group`);
+    if ((t.write || t.alwaysDestructive) && t.access === 'read')
+        throw new Error(`${t.name}: a write tool cannot be access 'read'`);
+    return t;
+}
+/** Assign a whole module to a group; a descriptor that already names another group throws. */
+export function inGroup(group, tools) {
+    return tools.map((t) => {
+        if (t.group && t.group !== group)
+            throw new Error(`${t.name}: group ${t.group} conflicts with ${group}`);
+        return checkDescriptor({ ...t, group });
+    });
+}

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

@@ -1,3 +1,6 @@
+import type { AppViewDescriptor } from './apps/types.js';
+import { type ToolPolicy } from './groups.js';
+import type { ResourceDescriptor } from './resources/types.js';
 import type { PromptDescriptor } from './prompts/types.js';
 import type { BuildServerOptions } from './server.js';
 import type { ToolDescriptor } from './tools/types.js';
@@ -32,5 +35,38 @@ export declare const hostedTools: ToolDescriptor[];
  * A write tool is never registered, so calling one is "unknown tool", not a refused write.
  */
 export declare const hostedReadOnlyTools: ToolDescriptor[];
+/** MCP Apps tools (PIT-10066), hosted-shaped: the same file/id runtime guards as every hosted tool. */
+export declare const hostedAppTools: ToolDescriptor[];
+/** A read-only server's app tool: read class, and never a PIT-10113 confirm tool, whatever its `access` says. */
+export declare const isHostedReadOnlyAppTool: (t: ToolDescriptor) => boolean;
+/** The app tools a read-only server serves (same rule as hostedReadOnlyTools). */
+export declare const hostedReadOnlyAppTools: ToolDescriptor[];
 /** The prompts a read-only server serves: only those flagged `readOnly` (the rest drive a write tool). */
 export declare const readOnlyPrompts: PromptDescriptor[];
+/** The CLI-backed hosted tools this policy serves. */
+export declare const hostedToolsFor: (p: ToolPolicy) => ToolDescriptor[];
+/** What decides app-tool registration besides the policy: the enabled views, and whether a PIT-10113 signer exists. */
+export interface HostedFeatures {
+    views: AppViewDescriptor[];
+    proposals: boolean;
+}
+/** The app tools this policy serves: allowed, their view enabled, and a confirm tool only with a proposal signer. */
+export declare const hostedAppToolsFor: (p: ToolPolicy, f: HostedFeatures) => ToolDescriptor[];
+/**
+ * Views worth serving: only those with at least one surviving app tool. App tools are filtered by their own group
+ * first, so a view whose group is off (analytics off hides dsr-engagement) is never served.
+ */
+export declare const viewsFor: (p: ToolPolicy, f: HostedFeatures) => AppViewDescriptor[];
+/** Exactly the names buildServer registers for this policy and these features (one filter, used by build and recording). */
+export declare const hostedRegisteredNames: (p: ToolPolicy, f: HostedFeatures) => Set<string>;
+export declare const promptsFor: (p: ToolPolicy) => PromptDescriptor[];
+export declare const resourcesFor: (p: ToolPolicy) => ResourceDescriptor[];
+/** The HOSTED descriptor (hosted inputShape, never a LOCAL_ONLY name) by name. */
+export declare function hostedToolByName(name: string): ToolDescriptor | undefined;
+/**
+ * Whether `args` pass the hosted tool's input schema: the same `inputShape` object `registerTool` receives, so the
+ * mcp-server pre-inspection sees exactly the calls the SDK rejects before the callback (recorded as INVALID_ARGS).
+ */
+export declare function hostedArgsValid(t: ToolDescriptor, args: unknown): boolean;
+/** On = at least one hosted tool survives; an empty group (training_studio) does not keep the connector on. */
+export declare const policyIsOn: (p: ToolPolicy) => boolean;

package/dist/src/mcp/hosted.js

@@ -1,6 +1,10 @@
+import { z } from 'zod';
 import { fail } from '../core/envelope.js';
 import { createCliError } from '../core/errors.js';
+import { allAppTools } from './apps/registry.js';
+import { accessOf, allowsPrompt, toolVerdict } from './groups.js';
 import { allPrompts } from './prompts/registry.js';
+import { allResources } from './resources/registry.js';
 import { allTools } from './registry.js';
 /**
  * The tool set served by the hosted (remote, OAuth) MCP server — PIT-8912.
@@ -110,6 +114,48 @@ export const hostedTools = allTools.filter((t) => !LOCAL_ONLY.has(t.name)).map(t
  * Read-only mode (the org's `settings.mcp.access` is `read_only`, PIT-9768): only the hosted tools that read.
  * A write tool is never registered, so calling one is "unknown tool", not a refused write.
  */
-export const hostedReadOnlyTools = hostedTools.filter((t) => t.readOnly && !t.write && !t.alwaysDestructive);
+export const hostedReadOnlyTools = hostedTools.filter((t) => accessOf(t) === 'read');
+/** MCP Apps tools (PIT-10066), hosted-shaped: the same file/id runtime guards as every hosted tool. */
+export const hostedAppTools = allAppTools.map(toHosted);
+/** A read-only server's app tool: read class, and never a PIT-10113 confirm tool, whatever its `access` says. */
+export const isHostedReadOnlyAppTool = (t) => accessOf(t) === 'read' && !t.confirm;
+/** The app tools a read-only server serves (same rule as hostedReadOnlyTools). */
+export const hostedReadOnlyAppTools = hostedAppTools.filter(isHostedReadOnlyAppTool);
 /** The prompts a read-only server serves: only those flagged `readOnly` (the rest drive a write tool). */
 export const readOnlyPrompts = allPrompts.filter((p) => p.readOnly === true);
+// ---------------------------------------------------------------------------------------------------------------------
+// PIT-10114: per-org tool groups. Every hosted list below is derived from the org's policy (`resolveToolPolicy`).
+const allowed = (p) => (t) => toolVerdict(p, t) === 'allowed';
+/** The CLI-backed hosted tools this policy serves. */
+export const hostedToolsFor = (p) => hostedTools.filter(allowed(p));
+/** The app tools this policy serves: allowed, their view enabled, and a confirm tool only with a proposal signer. */
+export const hostedAppToolsFor = (p, f) => {
+    const on = new Set(f.views.map((v) => v.name));
+    return hostedAppTools.filter((t) => allowed(p)(t) && (!t.ui || on.has(t.ui.view)) && (!t.confirm || f.proposals));
+};
+/**
+ * Views worth serving: only those with at least one surviving app tool. App tools are filtered by their own group
+ * first, so a view whose group is off (analytics off hides dsr-engagement) is never served.
+ */
+export const viewsFor = (p, f) => {
+    const used = new Set(hostedAppToolsFor(p, f).map((t) => t.ui.view));
+    return f.views.filter((v) => used.has(v.name));
+};
+/** Exactly the names buildServer registers for this policy and these features (one filter, used by build and recording). */
+export const hostedRegisteredNames = (p, f) => new Set([...hostedToolsFor(p), ...hostedAppToolsFor(p, f)].map((t) => t.name));
+export const promptsFor = (p) => allPrompts.filter((x) => allowsPrompt(p, x));
+export const resourcesFor = (p) => allResources.filter((r) => !r.group || p[r.group] !== 'off');
+const HOSTED_BY_NAME = new Map([...hostedTools, ...hostedAppTools].map((t) => [t.name, t]));
+/** The HOSTED descriptor (hosted inputShape, never a LOCAL_ONLY name) by name. */
+export function hostedToolByName(name) {
+    return HOSTED_BY_NAME.get(name);
+}
+/**
+ * Whether `args` pass the hosted tool's input schema: the same `inputShape` object `registerTool` receives, so the
+ * mcp-server pre-inspection sees exactly the calls the SDK rejects before the callback (recorded as INVALID_ARGS).
+ */
+export function hostedArgsValid(t, args) {
+    return z.object(t.inputShape).safeParse(args ?? {}).success;
+}
+/** On = at least one hosted tool survives; an empty group (training_studio) does not keep the connector on. */
+export const policyIsOn = (p) => hostedToolsFor(p).length > 0;

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

@@ -1,7 +1,13 @@
-export { buildServer, PITCHER_ICON, type McpRunContext, type BuildServerOptions } from './server.js';
-export { hostedTools, hostedReadOnlyTools, readOnlyPrompts, LOCAL_ONLY, FILE_KEY, ID_KEY, HOSTED_BUILD_OPTIONS, } from './hosted.js';
+export { buildServer, PITCHER_ICON, CLI_SCRIPTS_VERSION, toolCallEvent, type McpRunContext, type BuildServerOptions, type ToolCallEvent, type ToolCallSink, } from './server.js';
+export { TOOL_GROUPS, CONFIGURABLE_GROUPS, OFF_POLICY, resolveToolPolicy, toolVerdict, accessOf, allowsPrompt, type ToolGroup, type ToolAccess, type GroupLevel, type ToolPolicy, type ResolvedPolicy, type ToolVerdict, } from './groups.js';
+export { hostedTools, hostedReadOnlyTools, readOnlyPrompts, LOCAL_ONLY, FILE_KEY, ID_KEY, HOSTED_BUILD_OPTIONS, hostedAppTools, hostedReadOnlyAppTools, hostedToolsFor, hostedAppToolsFor, viewsFor, hostedRegisteredNames, promptsFor, resourcesFor, hostedToolByName, hostedArgsValid, policyIsOn, type HostedFeatures, } from './hosted.js';
+export { allAppViews, allAppTools } from './apps/registry.js';
+export { PROPOSAL_TTL_S, PROPOSAL_MAX_BYTES, PROPOSAL_TEXT_MAX_BYTES, TEXT_HOST_MODE, type ProposalClaims, type ProposalSigner, type HostClient, type Proposal, type CommitResult, } from './apps/confirm/types.js';
+export { APPS_RENDER_POLICY } from './renderPolicy.js';
+export { appViewUri, type AppViewDescriptor, type AppCsp } from './apps/types.js';
 export { allTools } from './registry.js';
 export { allPrompts } from './prompts/registry.js';
 export { allResources } from './resources/registry.js';
-export type { ToolDescriptor } from './tools/types.js';
+export type { ToolDescriptor, ToolUi, AppInjected } from './tools/types.js';
 export type { Credential } from '../core/credential.js';
+export { createCliError, isCliError, type CliError } from '../core/errors.js';

package/dist/src/mcp/index.js

@@ -1,6 +1,13 @@
 // Public entry `@pitcher/cli-scripts/mcp` — what the hosted MCP server (web/packages/mcp-server) consumes.
-export { buildServer, PITCHER_ICON } from './server.js';
-export { hostedTools, hostedReadOnlyTools, readOnlyPrompts, LOCAL_ONLY, FILE_KEY, ID_KEY, HOSTED_BUILD_OPTIONS, } from './hosted.js';
+export { buildServer, PITCHER_ICON, CLI_SCRIPTS_VERSION, toolCallEvent, } from './server.js';
+export { TOOL_GROUPS, CONFIGURABLE_GROUPS, OFF_POLICY, resolveToolPolicy, toolVerdict, accessOf, allowsPrompt, } from './groups.js';
+export { hostedTools, hostedReadOnlyTools, readOnlyPrompts, LOCAL_ONLY, FILE_KEY, ID_KEY, HOSTED_BUILD_OPTIONS, hostedAppTools, hostedReadOnlyAppTools, hostedToolsFor, hostedAppToolsFor, viewsFor, hostedRegisteredNames, promptsFor, resourcesFor, hostedToolByName, hostedArgsValid, policyIsOn, } from './hosted.js';
+export { allAppViews, allAppTools } from './apps/registry.js';
+export { PROPOSAL_TTL_S, PROPOSAL_MAX_BYTES, PROPOSAL_TEXT_MAX_BYTES, TEXT_HOST_MODE, } from './apps/confirm/types.js';
+export { APPS_RENDER_POLICY } from './renderPolicy.js';
+export { appViewUri } from './apps/types.js';
 export { allTools } from './registry.js';
 export { allPrompts } from './prompts/registry.js';
 export { allResources } from './resources/registry.js';
+// PIT-10113: the proposal signer (mcp-server) throws CliErrors so a commit maps them to the right code
+export { createCliError, isCliError } from '../core/errors.js';

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

@@ -4,12 +4,13 @@ import { dsrPrompts } from './dsr.js';
 import { announcementsPrompts } from './announcements.js';
 import { ldCanvasCoursePrompts } from './ldCanvasCourse.js';
 import { analyticsPrompts } from './analytics.js';
-// Every recipe prompt the server can expose. Mirrors mcp/registry.ts (allTools).
+const withGroup = (group, prompts) => prompts.map((p) => ({ ...p, group }));
+// Every recipe prompt the server can expose, each in the group of the tools it drives (PIT-10114). Mirrors mcp/registry.ts.
 export const allPrompts = [
-    ...emailTemplatePrompts,
-    ...dsrLandingPrompts,
-    ...dsrPrompts,
-    ...announcementsPrompts,
-    ...ldCanvasCoursePrompts,
-    ...analyticsPrompts,
+    ...withGroup('sharing', emailTemplatePrompts),
+    ...withGroup('sharing', dsrLandingPrompts),
+    ...withGroup('sharing', dsrPrompts),
+    ...withGroup('content', announcementsPrompts),
+    ...withGroup('ld', ldCanvasCoursePrompts),
+    ...withGroup('analytics', analyticsPrompts),
 ];

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

@@ -1,5 +1,6 @@
 import type { ZodOptional, ZodString } from 'zod';
 import type { PromptMessage } from '@modelcontextprotocol/sdk/types.js';
+import type { ToolGroup } from '../groups.js';
 export interface PromptDescriptor {
     name: string;
     title: string;
@@ -7,4 +8,6 @@ export interface PromptDescriptor {
     argsSchema: Record<string, ZodOptional<ZodString>>;
     build: (args: Record<string, string | undefined>) => PromptMessage[];
     readOnly?: true;
+    /** PIT-10114: served when its group is read_write, or at read when `readOnly`. Set in prompts/registry.ts. */
+    group?: ToolGroup;
 }

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

@@ -1,2 +1,6 @@
 import type { ToolDescriptor } from './tools/types.js';
+/**
+ * Every CLI-backed tool, each module assigned whole to one tool group (PIT-10114, spec "Group Taxonomy"). `inGroup`
+ * throws when a descriptor names another group or a write tool is classed `read` (checkDescriptor).
+ */
 export declare const allTools: ToolDescriptor[];

package/dist/src/mcp/registry.js

@@ -1,3 +1,4 @@
+import { inGroup } from './groups.js';
 import { analyticsTools } from './tools/analytics.js';
 import { announcementsTools } from './tools/announcements.js';
 import { canvasesTools } from './tools/canvases.js';
@@ -22,29 +23,33 @@ import { sharedLinksTools } from './tools/sharedLinks.js';
 import { tagsTools } from './tools/tags.js';
 import { themesTools } from './tools/themes.js';
 import { usersTools } from './tools/users.js';
+/**
+ * Every CLI-backed tool, each module assigned whole to one tool group (PIT-10114, spec "Group Taxonomy"). `inGroup`
+ * throws when a descriptor names another group or a write tool is classed `read` (checkDescriptor).
+ */
 export const allTools = [
-    ...canvasesTools,
-    ...filesTools,
-    ...foldersTools,
-    ...searchTools,
-    ...instancesTools,
-    ...sharedLinksTools,
-    ...tagsTools,
-    ...announcementsTools,
-    ...dsrLandingTools,
-    ...dsrTools,
-    ...emailTemplateTools,
-    ...themesTools,
-    ...usersTools,
-    ...invitationsTools,
-    ...rolesTools,
-    ...orgTools,
-    ...analyticsTools,
-    ...roleplayTools,
-    ...membershipsTools,
-    ...groupsTools,
-    ...metadataTemplateTools,
-    ...ldTools,
-    ...devSyncTools,
-    ...publishAppTools,
+    ...inGroup('content', canvasesTools),
+    ...inGroup('content', filesTools),
+    ...inGroup('content', foldersTools),
+    ...inGroup('search', searchTools),
+    ...inGroup('search', instancesTools),
+    ...inGroup('sharing', sharedLinksTools),
+    ...inGroup('content', tagsTools),
+    ...inGroup('content', announcementsTools),
+    ...inGroup('sharing', dsrLandingTools),
+    ...inGroup('sharing', dsrTools),
+    ...inGroup('sharing', emailTemplateTools),
+    ...inGroup('content', themesTools),
+    ...inGroup('admin', usersTools),
+    ...inGroup('admin', invitationsTools),
+    ...inGroup('admin', rolesTools),
+    ...inGroup('search', orgTools),
+    ...inGroup('analytics', analyticsTools),
+    ...inGroup('roleplay', roleplayTools),
+    ...inGroup('admin', membershipsTools),
+    ...inGroup('admin', groupsTools),
+    ...inGroup('content', metadataTemplateTools),
+    ...inGroup('ld', ldTools),
+    ...inGroup('developer', devSyncTools),
+    ...inGroup('developer', publishAppTools),
 ];

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

@@ -1 +1,2 @@
 export declare const ANALYTICS_RENDER_POLICY = "When answering Pitcher content-analytics or AI Roleplay questions (the pitcher_analytics_* and pitcher_roleplay_* tools), return the smallest sufficient representation. Answer in words first; a visual supports the sentence, it never replaces it. Default to prose and escalate ONLY when a trigger below fires.\n\nRendering tiers (evaluate top-down, stop at the first match):\n- A single fact / yes-no / \"who/what/how many is the single X\" (e.g. \"which canvas did I view?\", \"how many viewers?\") -> 1-2 sentences with the number inline. No table, no chart.\n- A ranking request (\"top\", \"most\", \"best\", \"rank\", or \"list the highest/lowest ...\") about content, files, users, or canvases -> a markdown TABLE of the ranked rows (default the top 5-8); columns = only the metric(s) asked for. Treat \"what's my top content?\" as a ranking (a table), NOT a single-item sentence. Lead with a one-line takeaway, then the table.\n- \"over time\" / \"trend\" / \"by week/month\" -> ONE line/area chart artifact (this rule wins over the generic comparison rule below for time series).\n- An explicit visualization request (\"show a chart\", \"chart\", \"visualize\", \"graph\", \"plot\") OR a comparison across a non-time dimension -> ONE focused chart as a single self-contained HTML artifact, only the asked-for series.\n- A broad overview (\"how's everything / my content / adoption doing\", \"give me the picture\", \"dashboard\", QBR) -> a multi-panel dashboard artifact. This is the ceiling \u2014 use it rarely, only for genuinely broad asks.\n\nGuardrails (every tier):\n1. Words first \u2014 even with a chart, lead with a one-sentence answer to the literal question.\n2. Mask names, emails, and user IDs by default (User A/B/...). Reveal an identity only when the analytics tool actually returned it for the authenticated role (the verbs are role-gated); never infer authorization from the user's wording.\n3. If data is empty or trivially small, say so in prose \u2014 do not render an empty chart.\n4. If results are capped/truncated, state the cap (\"top 15 of 118\").\n5. Never show a \"vs prior period\" delta unless the data actually contains prior-period numbers.\n6. Cite the source verb (\"via analytics popularity\").\n7. AI Roleplay: a session with no score (null) is unscored, never a 0; never fold it into an average, a pass rate or a ranking.\n\nDo not jump a tier without its trigger. The dashboard is opt-in by intent, never a default.";
+export declare const APPS_RENDER_POLICY = "When your host actually renders a Pitcher tool result in its own interactive view (MCP Apps: a Pitcher view), answer in one sentence and do not redraw the same data as a table, chart or artifact. If your host does not render the view, the text result is all the user gets: list the items for the user.\n\nConfirmed writes (tools ending in _propose): a propose call saves nothing. If your host shows the Pitcher confirm view, the user confirms or cancels there: say one sentence and do nothing else. Never call a _commit tool unless the proposal text tells you how and the user explicitly confirmed in this conversation; never change its arguments; never retry a commit the user cancelled.";

package/dist/src/mcp/renderPolicy.js

@@ -1,8 +1,9 @@
 // Connector-level MCP instructions surfaced to the host model (Claude Desktop, Cursor) via
 // InitializeResult.instructions. Governs how analytics answers are RENDERED so a natural-language
 // question gets a right-sized reply (a sentence, a table, one chart, or — rarely — a dashboard)
-// instead of a rigid full dashboard on every question. This constant is the single source of truth;
-// the Docs Portal spec (Product/Specs/2026-07-24-analytics-answer-rendering-policy.md) mirrors it.
+// instead of a rigid full dashboard on every question. This constant is the only copy of the policy:
+// edit it here. The Docs Portal spec (Product/Specs/2026-07-24-analytics-answer-rendering-policy.md)
+// points here and keeps only the background and decisions.
 export const ANALYTICS_RENDER_POLICY = `When answering Pitcher content-analytics or AI Roleplay questions (the pitcher_analytics_* and pitcher_roleplay_* tools), return the smallest sufficient representation. Answer in words first; a visual supports the sentence, it never replaces it. Default to prose and escalate ONLY when a trigger below fires.
 
 Rendering tiers (evaluate top-down, stop at the first match):
@@ -22,3 +23,8 @@ Guardrails (every tier):
 7. AI Roleplay: a session with no score (null) is unscored, never a 0; never fold it into an average, a pass rate or a ranking.
 
 Do not jump a tier without its trigger. The dashboard is opt-in by intent, never a default.`;
+// MCP Apps (PIT-10066): appended to the server instructions ONLY when at least one view is enabled, so a
+// server without apps keeps exactly ANALYTICS_RENDER_POLICY. The confirmed-writes paragraph is PIT-10113's (spec 8.2).
+export const APPS_RENDER_POLICY = `When your host actually renders a Pitcher tool result in its own interactive view (MCP Apps: a Pitcher view), answer in one sentence and do not redraw the same data as a table, chart or artifact. If your host does not render the view, the text result is all the user gets: list the items for the user.
+
+Confirmed writes (tools ending in _propose): a propose call saves nothing. If your host shows the Pitcher confirm view, the user confirms or cancels there: say one sentence and do nothing else. Never call a _commit tool unless the proposal text tells you how and the user explicitly confirmed in this conversation; never change its arguments; never retry a commit the user cancelled.`;

package/dist/src/mcp/resources/registry.js

@@ -4,6 +4,6 @@ import { analyticsCatalogResource } from './analyticsCatalog.js';
 // Every resource the server can expose. Mirrors mcp/registry.ts (allTools).
 export const allResources = [
     contentDesignResource,
-    ldCanvasDesignResource,
-    analyticsCatalogResource,
+    { ...ldCanvasDesignResource, group: 'ld' },
+    { ...analyticsCatalogResource, group: 'analytics' },
 ];

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

@@ -1,3 +1,4 @@
+import type { ToolGroup } from '../groups.js';
 export interface ResourceDescriptor {
     name: string;
     uri: string;
@@ -5,4 +6,6 @@ export interface ResourceDescriptor {
     description: string;
     mimeType: string;
     read: () => string;
+    /** PIT-10114: hidden when this group is off. Unset = always served (static text no group owns). */
+    group?: ToolGroup;
 }

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

@@ -10,5 +10,6 @@ export interface CallToolResultShape {
     [key: string]: unknown;
 }
 export declare const MAX_RESULT_BYTES = 900000;
+export declare const MAX_TEXT_BYTES = 8000;
 export declare function toErrorResult(code: string, message: string): CallToolResultShape;
-export declare function envelopeToToolResult(env: Envelope<unknown>, maxBytes?: number): CallToolResultShape;
+export declare function envelopeToToolResult(env: Envelope<unknown>, maxBytes?: number, toText?: (data: unknown) => string, textMaxBytes?: number): CallToolResultShape;

package/dist/src/mcp/result.js

@@ -3,9 +3,9 @@
 export const MAX_RESULT_BYTES = 900000;
 // Cap any single variable-length string (a server error message, a warning) so one huge value
 // can't blow the size budget regardless of which tier it lands in.
-const MAX_TEXT_BYTES = 8000;
-function clampText(s) {
-    return Buffer.byteLength(s, 'utf8') <= MAX_TEXT_BYTES ? s : `${s.slice(0, MAX_TEXT_BYTES)}… (truncated)`;
+export const MAX_TEXT_BYTES = 8000;
+function clampText(s, max = MAX_TEXT_BYTES) {
+    return Buffer.byteLength(s, 'utf8') <= max ? s : `${s.slice(0, max)}… (truncated)`;
 }
 function isPlainObject(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
@@ -21,7 +21,7 @@ function countItems(data) {
 export function toErrorResult(code, message) {
     return { content: [{ type: 'text', text: clampText(`${code}: ${message}`) }], isError: true };
 }
-export function envelopeToToolResult(env, maxBytes = MAX_RESULT_BYTES) {
+export function envelopeToToolResult(env, maxBytes = MAX_RESULT_BYTES, toText, textMaxBytes = MAX_TEXT_BYTES) {
     if (!env.ok) {
         return toErrorResult(env.error?.code ?? 'UNKNOWN', env.error?.message ?? 'unknown error');
     }
@@ -39,8 +39,10 @@ export function envelopeToToolResult(env, maxBytes = MAX_RESULT_BYTES) {
     // counted — rather than projecting from the raw data size. maxBytes keeps headroom under the
     // host cap for the outer JSON-RPC framing around this result.
     const fits = (candidate) => Buffer.byteLength(JSON.stringify(candidate), 'utf8') <= maxBytes;
-    // Tier 1: full payload with the default dual representation (text + structuredContent).
-    const dual = { content: withWarnings([{ type: 'text', text: full }]), isError: false };
+    // Tier 1: full payload with the default dual representation (text + structuredContent). An MCP Apps tool
+    // (`toText`) sends the model a short text instead of the full JSON, so the payload is not sent twice.
+    const text = toText ? clampText(toText(env.data), textMaxBytes) : full;
+    const dual = { content: withWarnings([{ type: 'text', text }]), isError: false };
     if (obj)
         dual.structuredContent = obj;
     if (fits(dual))

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;