@questpie/mcp 3.28.11 → 3.29.0

package/README.md

@@ -94,6 +94,42 @@ export default mcpTool("publish-summary", {
 });
 ```
 
+## Prompts
+
+A prompt provider answers `prompts/list` and `prompts/get` per request, so the
+prompts a caller sees can depend on who they are. Clients such as Claude Code
+show them as slash commands. Prompts do not add to the `tools/list` catalogue.
+
+```ts
+// mcp-prompts/playbooks.ts
+import { mcpPrompts } from "@questpie/mcp";
+
+export default mcpPrompts("playbooks", {
+	access: ({ session }) => !!session,
+	scopes: "playbooks:read",
+	list: async ({ ctx }) =>
+		(await ctx.collections.playbooks.find({})).docs.map((doc) => ({
+			name: doc.slug,
+			description: doc.summary,
+		})),
+	get: async ({ ctx, name }) => {
+		const doc = await ctx.collections.playbooks.findOne({
+			where: { slug: name },
+		});
+		if (!doc) return null;
+		return {
+			messages: [{ role: "user", content: { type: "text", text: doc.body } }],
+		};
+	},
+});
+```
+
+`access` and `scopes` are required and gate the whole provider, exactly like a
+custom tool. `get` returns `null` for a name the caller cannot use; the client
+receives the same not-found error as for an unknown name. The server advertises
+the `prompts` capability only when at least one provider is released. Prompts
+are never served to remote workloads.
+
 ## Remote Workloads
 
 Remote workload execution uses a separate public factory.
@@ -201,12 +237,12 @@ output, credentials, authorization envelopes, or workload attribution.
 
 ## Exports
 
-| Entry Point                 | Purpose                              |
-| --------------------------- | ------------------------------------ |
-| `@questpie/mcp`             | Config, plugin, server, tool factory |
-| `@questpie/mcp/modules/mcp` | `mcpModule` for `modules.ts`         |
-| `@questpie/mcp/plugin`      | Codegen plugin export                |
-| `@questpie/mcp/stdio`       | Stdio server entry                   |
+| Entry Point                 | Purpose                                           |
+| --------------------------- | ------------------------------------------------- |
+| `@questpie/mcp`             | Config, plugin, server, tool and prompt factories |
+| `@questpie/mcp/modules/mcp` | `mcpModule` for `modules.ts`                      |
+| `@questpie/mcp/plugin`      | Codegen plugin export                             |
+| `@questpie/mcp/stdio`       | Stdio server entry                                |
 
 ## License
 

package/dist/{create-server-5Eo4QP3q.mjs → create-server-DzTo-3Wy.mjs}

@@ -1,63 +1,11 @@
 import { createAdapterContext, createContextFactory, defaultOperationScope, evaluateRouteAccess, executeJsonRoute, extractAppServices, introspectCollection, introspectGlobal, introspectRoutes, isJsonRoute, umbrellaScopeFor } from "questpie";
+import { ErrorCode, GetPromptRequestSchema, GetPromptResultSchema, ListPromptsRequestSchema, ListToolsRequestSchema, McpError, PromptSchema, ToolSchema } from "@modelcontextprotocol/sdk/types.js";
 import { randomUUID } from "node:crypto";
 import { types } from "node:util";
 import { snapshotBoundedBrokerValue } from "questpie/executor";
 import { z } from "zod";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { ListToolsRequestSchema, ToolSchema } from "@modelcontextprotocol/sdk/types.js";
 
-//#region src/server/mcp-tool.ts
-var McpToolBuilder = class {
-	constructor(name, config) {
-		this.name = name;
-		this.config = config;
-	}
-	handler(handler) {
-		return Object.freeze({
-			__brand: "mcpTool",
-			name: this.name,
-			config: this.config,
-			handler
-		});
-	}
-};
-/**
-* Define a custom MCP tool, contributed by a module the same way collections and
-* routes are (via `ModuleDefinition.mcpTools`). `mcpTool(name, config).handler(fn)`
-* returns a frozen, branded {@link McpToolDefinition}; the CRUD/route tools the
-* framework auto-generates are the same shape.
-*
-* `config` mirrors the MCP tool contract: `inputSchema`/`outputSchema` (Zod),
-* `title`/`description`/`annotations` for discovery, plus the two QUESTPIE
-* authorization hooks that compose exactly like the built-in tools:
-* - `access` — required explicit opt-in and an {@link McpAccessRule} run against the caller's transport /
-*   accessMode / session (and, for an OAuth caller, its scopes). Same RBAC-style
-*   gate the CRUD tools use.
-* - `scopes` — the OAuth scopes an `oauth` caller must hold ({@link McpToolConfig.scopes}).
-*   Custom tools have no default scope mapping (unlike CRUD, there is no
-*   resource/operation to derive one from), so it is required; use `false` for
-*   an explicit no-OAuth-scope policy. The shipped scope gate ({@link scopeGateAllows}) enforces this at both
-*   `tools/list` (hidden) and `tools/call` (denied); `system`/`user` callers
-*   carry no scopes and skip it, so the effective bound is always `scopes ∩ RBAC`.
-*
-* @example
-* ```ts
-* export const ping = mcpTool("ops.ping", {
-*   access: ({ session }) => !!session,
-*   description: "Health probe",
-*   inputSchema: z.object({}),
-*   scopes: "routes:ops/ping:invoke", // only OAuth callers holding this scope
-* }).handler(async () => ({ content: [{ type: "text", text: "pong" }] }));
-* ```
-*/
-function mcpTool(name, config) {
-	return new McpToolBuilder(name, config);
-}
-function isMcpTool(value) {
-	return !!value && typeof value === "object" && value["__brand"] === "mcpTool" && typeof value.handler === "function";
-}
-
-//#endregion
 //#region src/server/principal.ts
 const hasOwnData = (descriptors, key) => {
 	const descriptor = descriptors[key];
@@ -363,6 +311,206 @@ async function evaluateMcpRule(rule, options) {
 	});
 }
 
+//#endregion
+//#region src/server/mcp-prompts.ts
+/**
+* Define an MCP prompt provider, contributed by a module the same way custom
+* tools are (via `ModuleDefinition.mcpPrompts`, file convention
+* `mcp-prompts/*.ts`). A provider answers `prompts/list` and `prompts/get`
+* per request, so the prompts a caller sees can depend on who the caller is.
+*
+* `access` and `scopes` compose exactly like a custom tool's: a caller the
+* provider denies sees none of its prompts, and `prompts/get` of any of them
+* answers not-found. `list` and `get` then run with that caller's context and
+* must apply their own row-level rules; returning `null` from `get` for a
+* prompt the caller cannot read keeps it indistinguishable from an unknown
+* name. Prompts are served on the `http` and `stdio` transports only, never to
+* remote workloads.
+*
+* @example
+* ```ts
+* export default mcpPrompts("playbooks", {
+*   access: ({ session }) => !!session,
+*   scopes: "playbooks:read",
+*   list: async ({ ctx }) =>
+*     (await ctx.collections.playbooks.find({})).docs.map((doc) => ({
+*       name: doc.slug,
+*       description: doc.summary,
+*     })),
+*   get: async ({ ctx, name }) => {
+*     const doc = await ctx.collections.playbooks.findOne({ where: { slug: name } });
+*     if (!doc) return null;
+*     return { messages: [{ role: "user", content: { type: "text", text: doc.body } }] };
+*   },
+* });
+* ```
+*/
+function mcpPrompts(name, config) {
+	return Object.freeze({
+		__brand: "mcpPrompts",
+		name,
+		config: Object.freeze({
+			...config,
+			scopes: Array.isArray(config.scopes) ? [...config.scopes] : config.scopes
+		})
+	});
+}
+function isMcpPromptProvider(value) {
+	if (!value || typeof value !== "object") return false;
+	const candidate = value;
+	return candidate.__brand === "mcpPrompts" && typeof candidate.config?.list === "function" && typeof candidate.config?.get === "function";
+}
+async function promptProviderAllows(scope, provider, ctx) {
+	return await evaluateMcpRule(provider.config.access, {
+		transport: scope.transport,
+		accessMode: scope.accessMode,
+		ctx
+	}) && scopeGateAllows(scopesFromContext(ctx), normalizeRequiredScopes(provider.config.scopes));
+}
+const MAX_INVALID_PARAMS_MESSAGE_CHARS = 512;
+/**
+* A provider's own `McpError(ErrorCode.InvalidParams, …)` is the one error
+* that reaches the client as itself: it states what was wrong with the
+* caller's arguments, which the provider authored for the caller. Every other
+* throw stays the boundary's opaque `internal`.
+*/
+function providerInvalidParams(error) {
+	if (!(error instanceof McpError) || error.code !== ErrorCode.InvalidParams) return;
+	const message = error.message.replace(/^MCP error -?\d+: /, "").slice(0, MAX_INVALID_PARAMS_MESSAGE_CHARS);
+	return new McpError(ErrorCode.InvalidParams, message);
+}
+/**
+* Install `prompts/list` and `prompts/get` over the released providers. The
+* caller must declare the `prompts` capability on the server beforehand.
+*/
+function registerPromptProviders(server, scope, catalog) {
+	if (scope.workload || catalog.promptProviders.size === 0) return;
+	const providers = [...catalog.promptProviders.values()].map((entry) => entry.provider);
+	server.server.setRequestHandler(ListPromptsRequestSchema, (request, extra) => {
+		if (request.params?.cursor) throw new McpError(ErrorCode.InvalidParams, "Invalid cursor");
+		return scope.execution.execute({
+			operation: "prompts/list",
+			transport: scope.transport,
+			accessMode: scope.accessMode,
+			input: request.params ?? {},
+			extra,
+			authorize: () => scope.getContext(),
+			invoke: async (control) => {
+				const handlerArgs = {
+					...control,
+					transport: scope.transport,
+					accessMode: scope.accessMode,
+					request: scope.request
+				};
+				const prompts = [];
+				const names = /* @__PURE__ */ new Set();
+				for (const provider of providers) {
+					if (!await promptProviderAllows(scope, provider, control.ctx)) continue;
+					for (const candidate of await provider.config.list(handlerArgs)) {
+						const parsed = PromptSchema.safeParse(candidate);
+						if (!parsed.success) throw new Error("MCP prompt provider listed an invalid prompt");
+						if (names.has(parsed.data.name)) continue;
+						names.add(parsed.data.name);
+						prompts.push(parsed.data);
+					}
+				}
+				return { prompts };
+			}
+		});
+	});
+	server.server.setRequestHandler(GetPromptRequestSchema, async (request, extra) => {
+		let invalidParams;
+		const rendered = await scope.execution.execute({
+			operation: "prompts/get",
+			transport: scope.transport,
+			accessMode: scope.accessMode,
+			input: request.params,
+			extra,
+			authorize: () => scope.getContext(),
+			invoke: async (control) => {
+				for (const provider of providers) {
+					if (!await promptProviderAllows(scope, provider, control.ctx)) continue;
+					let result;
+					try {
+						result = await provider.config.get({
+							...control,
+							transport: scope.transport,
+							accessMode: scope.accessMode,
+							request: scope.request,
+							name: request.params.name,
+							arguments: { ...request.params.arguments }
+						});
+					} catch (error) {
+						invalidParams = providerInvalidParams(error);
+						if (!invalidParams) throw error;
+						return null;
+					}
+					if (result === null || result === void 0) continue;
+					const parsed = GetPromptResultSchema.safeParse(result);
+					if (!parsed.success) throw new Error("MCP prompt provider rendered an invalid prompt");
+					return parsed.data;
+				}
+				return null;
+			}
+		});
+		if (invalidParams) throw invalidParams;
+		if (!rendered) throw new McpError(ErrorCode.InvalidParams, "Prompt not found");
+		return rendered;
+	});
+}
+
+//#endregion
+//#region src/server/mcp-tool.ts
+var McpToolBuilder = class {
+	constructor(name, config) {
+		this.name = name;
+		this.config = config;
+	}
+	handler(handler) {
+		return Object.freeze({
+			__brand: "mcpTool",
+			name: this.name,
+			config: this.config,
+			handler
+		});
+	}
+};
+/**
+* Define a custom MCP tool, contributed by a module the same way collections and
+* routes are (via `ModuleDefinition.mcpTools`). `mcpTool(name, config).handler(fn)`
+* returns a frozen, branded {@link McpToolDefinition}; the CRUD/route tools the
+* framework auto-generates are the same shape.
+*
+* `config` mirrors the MCP tool contract: `inputSchema`/`outputSchema` (Zod),
+* `title`/`description`/`annotations` for discovery, plus the two QUESTPIE
+* authorization hooks that compose exactly like the built-in tools:
+* - `access` — required explicit opt-in and an {@link McpAccessRule} run against the caller's transport /
+*   accessMode / session (and, for an OAuth caller, its scopes). Same RBAC-style
+*   gate the CRUD tools use.
+* - `scopes` — the OAuth scopes an `oauth` caller must hold ({@link McpToolConfig.scopes}).
+*   Custom tools have no default scope mapping (unlike CRUD, there is no
+*   resource/operation to derive one from), so it is required; use `false` for
+*   an explicit no-OAuth-scope policy. The shipped scope gate ({@link scopeGateAllows}) enforces this at both
+*   `tools/list` (hidden) and `tools/call` (denied); `system`/`user` callers
+*   carry no scopes and skip it, so the effective bound is always `scopes ∩ RBAC`.
+*
+* @example
+* ```ts
+* export const ping = mcpTool("ops.ping", {
+*   access: ({ session }) => !!session,
+*   description: "Health probe",
+*   inputSchema: z.object({}),
+*   scopes: "routes:ops/ping:invoke", // only OAuth callers holding this scope
+* }).handler(async () => ({ content: [{ type: "text", text: "pong" }] }));
+* ```
+*/
+function mcpTool(name, config) {
+	return new McpToolBuilder(name, config);
+}
+function isMcpTool(value) {
+	return !!value && typeof value === "object" && value["__brand"] === "mcpTool" && typeof value.handler === "function";
+}
+
 //#endregion
 //#region src/server/catalog.ts
 const COLLECTION_OPERATION_KINDS = {
@@ -547,6 +695,15 @@ function resolveMcpCatalog(app, config) {
 		customTools.set(name, Object.freeze({ tool }));
 		addRequiredScopes(oauthScopes, tool.config.scopes);
 	}
+	const promptProviders = /* @__PURE__ */ new Map();
+	const configuredPromptProviders = app.state?.mcpPrompts ?? {};
+	for (const [key, candidate] of Object.entries(configuredPromptProviders)) {
+		if (!isMcpPromptProvider(candidate) || candidate.config.access === void 0 || candidate.config.access === false || candidate.config.scopes === void 0) continue;
+		const name = candidate.name || key;
+		if (promptProviders.has(name)) throw new Error(`Duplicate MCP prompt provider name: ${name}`);
+		promptProviders.set(name, Object.freeze({ provider: candidate }));
+		addRequiredScopes(oauthScopes, candidate.config.scopes);
+	}
 	const resourceConfig = ownSection(config, "resources");
 	const configuredResourceCollections = ownSection(resourceConfig, "collections");
 	const configuredResourceGlobals = ownSection(resourceConfig, "globals");
@@ -563,6 +720,7 @@ function resolveMcpCatalog(app, config) {
 		globals: readonlyMap(globals),
 		routes: readonlyMap(routes),
 		customTools: readonlyMap(customTools),
+		promptProviders: readonlyMap(promptProviders),
 		resources: Object.freeze({
 			collections: readonlySet(resourceCollections),
 			globals: readonlySet(resourceGlobals),
@@ -2553,12 +2711,14 @@ async function createServer(app, options, workload) {
 		version: config.version ?? "0.0.0"
 	}, { capabilities: {
 		tools: {},
-		...catalog.resources.collections.size > 0 || catalog.resources.globals.size > 0 || catalog.resources.routes.size > 0 ? { resources: {} } : {}
+		...catalog.resources.collections.size > 0 || catalog.resources.globals.size > 0 || catalog.resources.routes.size > 0 ? { resources: {} } : {},
+		...!workload && catalog.promptProviders.size > 0 ? { prompts: {} } : {}
 	} });
 	await registerCrudTools(server, scope, config, catalog);
 	await registerRouteTools(server, scope, catalog);
 	registerSchemaResources(server, scope, catalog);
 	await registerCustomTools(server, scope, catalog);
+	registerPromptProviders(server, scope, catalog);
 	if (workload) server.server.setRequestHandler(ListToolsRequestSchema, (_request, extra) => listWorkloadTools(workload, release.execution, extra));
 	else if ([...catalog.collections.values()].every((entry) => entry.operations.length === 0) && [...catalog.globals.values()].every((entry) => entry.operations.length === 0) && catalog.routes.size === 0 && catalog.customTools.size === 0) server.server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: [] }));
 	else installSchemaDietListToolsHandler(server);
@@ -2585,4 +2745,4 @@ async function createWorkloadMcpServer(app, options) {
 }
 
 //#endregion
-export { validateMcpPrincipal as C, scopesFromContext as S, resolveMcpCatalog as _, customToolWorkloadIdentity as a, requiredScopesForOperation as b, createWorkloadMcpBoundary as c, getAppMcpRelease as d, McpAccessDeniedError as f, toMcpToolError as g, mcpPublicErrorCode as h, customToolDescriptor as i, createRuntimeScope as l, assertBoundedMcpValue as m, createWorkloadMcpServer as n, executeCustomToolCall as o, McpPublicError as p, customToolAllows as r, authorizeWorkload as s, createMcpServer as t, createWorkloadMcpRelease as u, defaultOperationScope as v, mcpTool as w, scopeGateAllows as x, normalizeRequiredScopes as y };
+export { scopeGateAllows as C, requiredScopesForOperation as S, validateMcpPrincipal as T, resolveMcpCatalog as _, customToolWorkloadIdentity as a, defaultOperationScope as b, createWorkloadMcpBoundary as c, getAppMcpRelease as d, McpAccessDeniedError as f, toMcpToolError as g, mcpPublicErrorCode as h, customToolDescriptor as i, createRuntimeScope as l, assertBoundedMcpValue as m, createWorkloadMcpServer as n, executeCustomToolCall as o, McpPublicError as p, customToolAllows as r, authorizeWorkload as s, createMcpServer as t, createWorkloadMcpRelease as u, mcpTool as v, scopesFromContext as w, normalizeRequiredScopes as x, mcpPrompts as y };

package/dist/{index-C3gm6ar5.d.mts → index-CLEEqMqK.d.mts}

@@ -37,6 +37,7 @@ type McpRoutes = {
 };
 type McpFieldTypes = Record<never, never>;
 type McpMcpTools = Record<never, never>;
+type McpMcpPrompts = Record<never, never>;
 //#endregion
 //#region src/server/modules/mcp/index.d.ts
 type McpModule = typeof mcpModule;
@@ -52,6 +53,7 @@ declare const mcpModule: {
   readonly jobs: McpJobs;
   readonly fieldTypes: McpFieldTypes;
   readonly mcpTools: McpMcpTools;
+  readonly mcpPrompts: McpMcpPrompts;
   readonly messages: Record<never, never>;
   readonly services: Record<never, never>;
   readonly emailTemplates: Record<never, never>;

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { n as mcpModule } from "./index-C3gm6ar5.mjs";
-import { A as McpWorkloadAuthorizer, B as WorkloadMcpServerOptions, C as McpToolConfig, D as McpWorkloadAuditEvent, E as McpTransportKind, F as McpWorkloadHandoffInput, I as McpWorkloadRequirement, L as McpWorkloadToolFacts, M as McpWorkloadContextBindingInput, N as McpWorkloadExecutionControl, O as McpWorkloadAuthorization, P as McpWorkloadHandoff, R as McpWorkloadToolKind, S as McpStdioConfig, T as McpToolHandlerArgs, _ as McpProgrammaticToolResult, a as McpAccessRule, b as McpResourcesConfig, c as McpCrudConfig, d as McpExecutionDiagnosticEvent, f as McpExecutionLimits, g as McpProgrammaticTool, h as McpProgrammaticRequestOptions, i as McpAccessMode, j as McpWorkloadContextBinder, k as McpWorkloadAuthorizationRequest, l as McpEntityPolicy, m as McpHttpConfig, n as QuestpieApp, o as McpAccessRuleContext, p as McpExecutionOptions, r as mcpPublicErrorCode, s as McpConfig, t as startStdioServer, u as McpExecutionConfig, v as McpPublicErrorCode, w as McpToolDefinition, x as McpRoutesConfig, y as McpRequiredScopes, z as McpWorkloadToolPort } from "./stdio-C3663EKG.mjs";
+import { n as mcpModule } from "./index-CLEEqMqK.mjs";
+import { A as McpTransportKind, B as McpWorkloadRequirement, C as McpRequiredScopes, D as McpToolConfig, E as McpStdioConfig, F as McpWorkloadContextBinder, H as McpWorkloadToolKind, I as McpWorkloadContextBindingInput, L as McpWorkloadExecutionControl, M as McpWorkloadAuthorization, N as McpWorkloadAuthorizationRequest, O as McpToolDefinition, P as McpWorkloadAuthorizer, R as McpWorkloadHandoff, S as McpPublicErrorCode, T as McpRoutesConfig, U as McpWorkloadToolPort, V as McpWorkloadToolFacts, W as WorkloadMcpServerOptions, _ as McpProgrammaticToolResult, a as McpAccessRule, b as McpPromptProviderConfig, c as McpCrudConfig, d as McpExecutionDiagnosticEvent, f as McpExecutionLimits, g as McpProgrammaticTool, h as McpProgrammaticRequestOptions, i as McpAccessMode, j as McpWorkloadAuditEvent, k as McpToolHandlerArgs, l as McpEntityPolicy, m as McpHttpConfig, n as QuestpieApp, o as McpAccessRuleContext, p as McpExecutionOptions, r as mcpPublicErrorCode, s as McpConfig, t as startStdioServer, u as McpExecutionConfig, v as McpPromptGetArgs, w as McpResourcesConfig, x as McpPromptProviderDefinition, y as McpPromptHandlerArgs, z as McpWorkloadHandoffInput } from "./stdio-C2V13-vP.mjs";
 import { t as mcpPlugin } from "./plugin-CMR-wkeP.mjs";
 import { AppContext, Questpie, RequestContext, ScopeOperationKind, defaultOperationScope, introspectRoutes } from "questpie";
 import { z } from "zod";
@@ -100,11 +100,15 @@ interface ResolvedMcpRouteCatalogEntry extends ResolvedMcpEntityCatalogEntry {
 interface ResolvedMcpCustomToolCatalogEntry {
   tool: McpToolDefinition;
 }
+interface ResolvedMcpPromptProviderCatalogEntry {
+  provider: McpPromptProviderDefinition;
+}
 interface ResolvedMcpCatalog {
   collections: ReadonlyMap<string, ResolvedMcpEntityCatalogEntry>;
   globals: ReadonlyMap<string, ResolvedMcpEntityCatalogEntry>;
   routes: ReadonlyMap<string, ResolvedMcpRouteCatalogEntry>;
   customTools: ReadonlyMap<string, ResolvedMcpCustomToolCatalogEntry>;
+  promptProviders: ReadonlyMap<string, ResolvedMcpPromptProviderCatalogEntry>;
   resources: {
     collections: ReadonlySet<string>;
     globals: ReadonlySet<string>;
@@ -118,6 +122,7 @@ interface ResolvedMcpCatalog {
 type CatalogApp = Pick<Questpie<any>, "getCollections" | "getGlobals"> & {
   state?: {
     mcpTools?: Record<string, unknown>;
+    mcpPrompts?: Record<string, unknown>;
   } & Record<string, unknown>;
   config?: Questpie<any>["config"];
 };
@@ -164,4 +169,39 @@ declare class McpToolBuilder<TInputSchema extends z.ZodTypeAny, TOutputSchema ex
  */
 declare function mcpTool<TInputSchema extends z.ZodTypeAny = z.ZodTypeAny, TOutputSchema extends z.ZodTypeAny = z.ZodTypeAny>(name: string, config: McpToolConfig<TInputSchema, TOutputSchema>): McpToolBuilder<TInputSchema, TOutputSchema>;
 //#endregion
-export { type McpAccessMode, type McpAccessRule, type McpAccessRuleContext, type McpConfig, type McpCrudConfig, type McpEntityPolicy, type McpExecutionConfig, type McpExecutionDiagnosticEvent, type McpExecutionLimits, type McpExecutionOptions, type McpHttpConfig, type McpProgrammaticRequestOptions, type McpProgrammaticTool, type McpProgrammaticToolResult, type McpPublicErrorCode, type McpRequiredScopes, type McpResourcesConfig, type McpRoutesConfig, type McpStdioConfig, type McpToolConfig, type McpToolDefinition, type McpToolHandlerArgs, type McpTransportKind, type McpWorkloadAuditEvent, type McpWorkloadAuthorization, type McpWorkloadAuthorizationRequest, type McpWorkloadAuthorizer, type McpWorkloadContextBinder, type McpWorkloadContextBindingInput, type McpWorkloadExecutionControl, type McpWorkloadHandoff, type McpWorkloadHandoffInput, type McpWorkloadRequirement, type McpWorkloadToolFacts, type McpWorkloadToolKind, type McpWorkloadToolPort, type ResolvedMcpCatalog, type ResolvedMcpCustomToolCatalogEntry, type ResolvedMcpEntityCatalogEntry, type ResolvedMcpRouteCatalogEntry, type ScopeOperationKind, type WorkloadMcpServerOptions, createMcpServer, createWorkloadMcpServer, createWorkloadMcpToolPort, mcpModule as default, mcpModule, defaultOperationScope, mcpConfig, mcpPlugin, mcpPublicErrorCode, mcpTool, normalizeRequiredScopes, requiredScopesForOperation, resolveMcpCatalog, scopeGateAllows, scopesFromContext, startStdioServer };
+//#region src/server/mcp-prompts.d.ts
+/**
+ * Define an MCP prompt provider, contributed by a module the same way custom
+ * tools are (via `ModuleDefinition.mcpPrompts`, file convention
+ * `mcp-prompts/*.ts`). A provider answers `prompts/list` and `prompts/get`
+ * per request, so the prompts a caller sees can depend on who the caller is.
+ *
+ * `access` and `scopes` compose exactly like a custom tool's: a caller the
+ * provider denies sees none of its prompts, and `prompts/get` of any of them
+ * answers not-found. `list` and `get` then run with that caller's context and
+ * must apply their own row-level rules; returning `null` from `get` for a
+ * prompt the caller cannot read keeps it indistinguishable from an unknown
+ * name. Prompts are served on the `http` and `stdio` transports only, never to
+ * remote workloads.
+ *
+ * @example
+ * ```ts
+ * export default mcpPrompts("playbooks", {
+ *   access: ({ session }) => !!session,
+ *   scopes: "playbooks:read",
+ *   list: async ({ ctx }) =>
+ *     (await ctx.collections.playbooks.find({})).docs.map((doc) => ({
+ *       name: doc.slug,
+ *       description: doc.summary,
+ *     })),
+ *   get: async ({ ctx, name }) => {
+ *     const doc = await ctx.collections.playbooks.findOne({ where: { slug: name } });
+ *     if (!doc) return null;
+ *     return { messages: [{ role: "user", content: { type: "text", text: doc.body } }] };
+ *   },
+ * });
+ * ```
+ */
+declare function mcpPrompts(name: string, config: McpPromptProviderConfig): McpPromptProviderDefinition;
+//#endregion
+export { type McpAccessMode, type McpAccessRule, type McpAccessRuleContext, type McpConfig, type McpCrudConfig, type McpEntityPolicy, type McpExecutionConfig, type McpExecutionDiagnosticEvent, type McpExecutionLimits, type McpExecutionOptions, type McpHttpConfig, type McpProgrammaticRequestOptions, type McpProgrammaticTool, type McpProgrammaticToolResult, type McpPromptGetArgs, type McpPromptHandlerArgs, type McpPromptProviderConfig, type McpPromptProviderDefinition, type McpPublicErrorCode, type McpRequiredScopes, type McpResourcesConfig, type McpRoutesConfig, type McpStdioConfig, type McpToolConfig, type McpToolDefinition, type McpToolHandlerArgs, type McpTransportKind, type McpWorkloadAuditEvent, type McpWorkloadAuthorization, type McpWorkloadAuthorizationRequest, type McpWorkloadAuthorizer, type McpWorkloadContextBinder, type McpWorkloadContextBindingInput, type McpWorkloadExecutionControl, type McpWorkloadHandoff, type McpWorkloadHandoffInput, type McpWorkloadRequirement, type McpWorkloadToolFacts, type McpWorkloadToolKind, type McpWorkloadToolPort, type ResolvedMcpCatalog, type ResolvedMcpCustomToolCatalogEntry, type ResolvedMcpEntityCatalogEntry, type ResolvedMcpPromptProviderCatalogEntry, type ResolvedMcpRouteCatalogEntry, type ScopeOperationKind, type WorkloadMcpServerOptions, createMcpServer, createWorkloadMcpServer, createWorkloadMcpToolPort, mcpModule as default, mcpModule, defaultOperationScope, mcpConfig, mcpPlugin, mcpPrompts, mcpPublicErrorCode, mcpTool, normalizeRequiredScopes, requiredScopesForOperation, resolveMcpCatalog, scopeGateAllows, scopesFromContext, startStdioServer };

package/dist/index.mjs

@@ -1,7 +1,7 @@
-import { S as scopesFromContext, _ as resolveMcpCatalog, a as customToolWorkloadIdentity, b as requiredScopesForOperation, c as createWorkloadMcpBoundary, f as McpAccessDeniedError, g as toMcpToolError, h as mcpPublicErrorCode, i as customToolDescriptor, l as createRuntimeScope, m as assertBoundedMcpValue, n as createWorkloadMcpServer, o as executeCustomToolCall, p as McpPublicError, r as customToolAllows, s as authorizeWorkload, t as createMcpServer, u as createWorkloadMcpRelease, v as defaultOperationScope, w as mcpTool, x as scopeGateAllows, y as normalizeRequiredScopes } from "./create-server-5Eo4QP3q.mjs";
-import { n as mcp_default, t as mcpModule } from "./mcp-i0Kqu_bB.mjs";
-import { t as mcpPlugin } from "./plugin-BZQe1pji.mjs";
-import { t as startStdioServer } from "./stdio-37bSPka9.mjs";
+import { C as scopeGateAllows, S as requiredScopesForOperation, _ as resolveMcpCatalog, a as customToolWorkloadIdentity, b as defaultOperationScope, c as createWorkloadMcpBoundary, f as McpAccessDeniedError, g as toMcpToolError, h as mcpPublicErrorCode, i as customToolDescriptor, l as createRuntimeScope, m as assertBoundedMcpValue, n as createWorkloadMcpServer, o as executeCustomToolCall, p as McpPublicError, r as customToolAllows, s as authorizeWorkload, t as createMcpServer, u as createWorkloadMcpRelease, v as mcpTool, w as scopesFromContext, x as normalizeRequiredScopes, y as mcpPrompts } from "./create-server-DzTo-3Wy.mjs";
+import { n as mcp_default, t as mcpModule } from "./mcp-C55EQ-yd.mjs";
+import { t as mcpPlugin } from "./plugin-BgwWI9S8.mjs";
+import { t as startStdioServer } from "./stdio-Bq7nzR79.mjs";
 import { randomUUID } from "node:crypto";
 
 //#region src/server/workload-tool-port.ts
@@ -96,4 +96,4 @@ function mcpConfig(config) {
 }
 
 //#endregion
-export { createMcpServer, createWorkloadMcpServer, createWorkloadMcpToolPort, mcp_default as default, defaultOperationScope, mcpConfig, mcpModule, mcpPlugin, mcpPublicErrorCode, mcpTool, normalizeRequiredScopes, requiredScopesForOperation, resolveMcpCatalog, scopeGateAllows, scopesFromContext, startStdioServer };
+export { createMcpServer, createWorkloadMcpServer, createWorkloadMcpToolPort, mcp_default as default, defaultOperationScope, mcpConfig, mcpModule, mcpPlugin, mcpPrompts, mcpPublicErrorCode, mcpTool, normalizeRequiredScopes, requiredScopesForOperation, resolveMcpCatalog, scopeGateAllows, scopesFromContext, startStdioServer };

package/dist/{mcp-i0Kqu_bB.mjs → mcp-C55EQ-yd.mjs}

@@ -1,5 +1,5 @@
-import { C as validateMcpPrincipal, d as getAppMcpRelease, m as assertBoundedMcpValue, t as createMcpServer } from "./create-server-5Eo4QP3q.mjs";
-import { t as mcpPlugin } from "./plugin-BZQe1pji.mjs";
+import { T as validateMcpPrincipal, d as getAppMcpRelease, m as assertBoundedMcpValue, t as createMcpServer } from "./create-server-DzTo-3Wy.mjs";
+import { t as mcpPlugin } from "./plugin-BgwWI9S8.mjs";
 import { route } from "questpie";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 
@@ -325,6 +325,7 @@ const _module = {
 	seeds: [],
 	fieldTypes: {},
 	mcpTools: {},
+	mcpPrompts: {},
 	plugin: plugin_default
 };
 var module_default = _module;

package/dist/modules/mcp.d.mts

@@ -1,2 +1,2 @@
-import { n as mcpModule, t as McpModule } from "../index-C3gm6ar5.mjs";
+import { n as mcpModule, t as McpModule } from "../index-CLEEqMqK.mjs";
 export { type McpModule, mcpModule };

package/dist/modules/mcp.mjs

@@ -1,3 +1,3 @@
-import { t as mcpModule } from "../mcp-i0Kqu_bB.mjs";
+import { t as mcpModule } from "../mcp-C55EQ-yd.mjs";
 
 export { mcpModule };

package/dist/{plugin-BZQe1pji.mjs → plugin-BgwWI9S8.mjs}

@@ -5,15 +5,26 @@ function mcpPlugin() {
 		targets: { server: {
 			root: ".",
 			outputFile: "index.ts",
-			categories: { mcpTools: {
-				dirs: ["mcp-tools"],
-				prefix: "mcpTool",
-				factoryFunctions: ["mcpTool"],
-				registryKey: true,
-				includeInAppState: true,
-				extractFromModules: true,
-				typeEmit: "standard"
-			} },
+			categories: {
+				mcpTools: {
+					dirs: ["mcp-tools"],
+					prefix: "mcpTool",
+					factoryFunctions: ["mcpTool"],
+					registryKey: true,
+					includeInAppState: true,
+					extractFromModules: true,
+					typeEmit: "standard"
+				},
+				mcpPrompts: {
+					dirs: ["mcp-prompts"],
+					prefix: "mcpPrompts",
+					factoryFunctions: ["mcpPrompts"],
+					registryKey: true,
+					includeInAppState: true,
+					extractFromModules: true,
+					typeEmit: "standard"
+				}
+			},
 			discover: { mcpConfig: {
 				pattern: "config/mcp.ts",
 				configKey: "mcp"

package/dist/plugin.mjs

@@ -1,3 +1,3 @@
-import { t as mcpPlugin } from "./plugin-BZQe1pji.mjs";
+import { t as mcpPlugin } from "./plugin-BgwWI9S8.mjs";
 
 export { mcpPlugin };

package/dist/{stdio-37bSPka9.mjs → stdio-Bq7nzR79.mjs}

@@ -1,4 +1,4 @@
-import { t as createMcpServer } from "./create-server-5Eo4QP3q.mjs";
+import { t as createMcpServer } from "./create-server-DzTo-3Wy.mjs";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 //#region src/server/stdio.ts

package/dist/{stdio-C3663EKG.d.mts → stdio-C2V13-vP.d.mts}

@@ -1,7 +1,7 @@
 import { AppContext, RequestContext, createContextFactory } from "questpie";
+import { CallToolResult, GetPromptResult, Prompt, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 import "questpie/executor";
 import { z } from "zod";
-import { CallToolResult, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 import * as _modelcontextprotocol_sdk_server_mcp0 from "@modelcontextprotocol/sdk/server/mcp";
 
 //#region src/server/types.d.ts
@@ -303,12 +303,58 @@ interface McpToolDefinition<TInputSchema extends z.ZodTypeAny = z.ZodTypeAny, TO
   readonly config: McpToolConfig<TInputSchema, TOutputSchema>;
   readonly handler: (args: McpToolHandlerArgs<z.infer<TInputSchema>>) => CallToolResult | Promise<CallToolResult>;
 }
+/** Per-request arguments shared by a prompt provider's `list` and `get`. */
+interface McpPromptHandlerArgs {
+  ctx: AppContext & Partial<RequestContext>;
+  transport: McpTransportKind;
+  accessMode: McpAccessMode;
+  request?: Request;
+  signal: AbortSignal;
+  requestId: string | number;
+  correlationId: string;
+}
+interface McpPromptGetArgs extends McpPromptHandlerArgs {
+  /** The prompt name the client asked for, exactly as sent. */
+  name: string;
+  /** The client's string arguments; `{}` when the client sent none. */
+  arguments: Record<string, string>;
+}
+interface McpPromptProviderConfig {
+  /**
+   * Required explicit opt-in, evaluated per request against the same caller
+   * context the tools get. A denied caller sees none of this provider's prompts
+   * and a `prompts/get` of any of them answers not-found.
+   */
+  access: McpAccessRule;
+  /**
+   * Scopes an OAuth caller must hold (all required — AND), or `false` for an
+   * explicit no-OAuth-scope policy. Required, like a custom tool's `scopes`.
+   */
+  scopes: McpRequiredScopes;
+  /**
+   * The prompts this caller can use right now. Runs on every `prompts/list`;
+   * the list may differ per caller and per request.
+   */
+  list: (args: McpPromptHandlerArgs) => Prompt[] | Promise<Prompt[]>;
+  /**
+   * Render one prompt, or return `null` when this caller has no prompt of
+   * that name. `null` is answered as not-found, the same as an unknown name,
+   * so a prompt the caller cannot read is indistinguishable from none.
+   */
+  get: (args: McpPromptGetArgs) => GetPromptResult | null | Promise<GetPromptResult | null>;
+}
+interface McpPromptProviderDefinition {
+  readonly __brand: "mcpPrompts";
+  readonly name: string;
+  readonly config: McpPromptProviderConfig;
+}
 declare module "questpie" {
   interface AppStateConfig {
     mcp?: McpConfig;
   }
   interface ModuleDefinition {
     mcpTools?: Record<string, McpToolDefinition>;
+    mcpPrompts?: Record<string, McpPromptProviderDefinition>;
   }
 }
 //#endregion
@@ -322,4 +368,4 @@ type QuestpieApp = Parameters<typeof createContextFactory>[0];
 //#region src/server/stdio.d.ts
 declare function startStdioServer(app: QuestpieApp, options?: Omit<McpExecutionOptions, "transport">): Promise<_modelcontextprotocol_sdk_server_mcp0.McpServer>;
 //#endregion
-export { McpWorkloadAuthorizer as A, WorkloadMcpServerOptions as B, McpToolConfig as C, McpWorkloadAuditEvent as D, McpTransportKind as E, McpWorkloadHandoffInput as F, McpWorkloadRequirement as I, McpWorkloadToolFacts as L, McpWorkloadContextBindingInput as M, McpWorkloadExecutionControl as N, McpWorkloadAuthorization as O, McpWorkloadHandoff as P, McpWorkloadToolKind as R, McpStdioConfig as S, McpToolHandlerArgs as T, McpProgrammaticToolResult as _, McpAccessRule as a, McpResourcesConfig as b, McpCrudConfig as c, McpExecutionDiagnosticEvent as d, McpExecutionLimits as f, McpProgrammaticTool as g, McpProgrammaticRequestOptions as h, McpAccessMode as i, McpWorkloadContextBinder as j, McpWorkloadAuthorizationRequest as k, McpEntityPolicy as l, McpHttpConfig as m, QuestpieApp as n, McpAccessRuleContext as o, McpExecutionOptions as p, mcpPublicErrorCode as r, McpConfig as s, startStdioServer as t, McpExecutionConfig as u, McpPublicErrorCode as v, McpToolDefinition as w, McpRoutesConfig as x, McpRequiredScopes as y, McpWorkloadToolPort as z };
+export { McpTransportKind as A, McpWorkloadRequirement as B, McpRequiredScopes as C, McpToolConfig as D, McpStdioConfig as E, McpWorkloadContextBinder as F, McpWorkloadToolKind as H, McpWorkloadContextBindingInput as I, McpWorkloadExecutionControl as L, McpWorkloadAuthorization as M, McpWorkloadAuthorizationRequest as N, McpToolDefinition as O, McpWorkloadAuthorizer as P, McpWorkloadHandoff as R, McpPublicErrorCode as S, McpRoutesConfig as T, McpWorkloadToolPort as U, McpWorkloadToolFacts as V, WorkloadMcpServerOptions as W, McpProgrammaticToolResult as _, McpAccessRule as a, McpPromptProviderConfig as b, McpCrudConfig as c, McpExecutionDiagnosticEvent as d, McpExecutionLimits as f, McpProgrammaticTool as g, McpProgrammaticRequestOptions as h, McpAccessMode as i, McpWorkloadAuditEvent as j, McpToolHandlerArgs as k, McpEntityPolicy as l, McpHttpConfig as m, QuestpieApp as n, McpAccessRuleContext as o, McpExecutionOptions as p, mcpPublicErrorCode as r, McpConfig as s, startStdioServer as t, McpExecutionConfig as u, McpPromptGetArgs as v, McpResourcesConfig as w, McpPromptProviderDefinition as x, McpPromptHandlerArgs as y, McpWorkloadHandoffInput as z };

package/dist/stdio.d.mts

@@ -1,2 +1,2 @@
-import { t as startStdioServer } from "./stdio-C3663EKG.mjs";
+import { t as startStdioServer } from "./stdio-C2V13-vP.mjs";
 export { startStdioServer };

package/dist/stdio.mjs

@@ -1,3 +1,3 @@
-import { t as startStdioServer } from "./stdio-37bSPka9.mjs";
+import { t as startStdioServer } from "./stdio-Bq7nzR79.mjs";
 
 export { startStdioServer };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@questpie/mcp",
-	"version": "3.28.11",
+	"version": "3.29.0",
 	"description": "Model Context Protocol server for QUESTPIE apps, under the app's own access rules",
 	"repository": {
 		"type": "git",
@@ -70,7 +70,7 @@
 	},
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "^1.29.0",
-		"questpie": "^3.28.11",
+		"questpie": "^3.29.0",
 		"zod": "^4.2.1"
 	},
 	"devDependencies": {
@@ -80,6 +80,6 @@
 		"tsdown": "^0.18.3"
 	},
 	"peerDependencies": {
-		"questpie": "^3.28.11"
+		"questpie": "^3.29.0"
 	}
 }