@questpie/mcp 3.15.2 → 3.17.0

package/dist/stdio-YoM70-42.d.mts

@@ -0,0 +1,323 @@
+import { AppContext, RequestContext, createContextFactory } from "questpie";
+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
+type McpTransportKind = "http" | "stdio" | "workload";
+type McpAccessMode = "user" | "system";
+interface McpAccessRuleContext {
+  transport: McpTransportKind;
+  accessMode: McpAccessMode;
+  session?: RequestContext["session"];
+  /**
+   * The consented OAuth scopes carried by the caller, when the request was
+   * authenticated by an OAuth access token (`ctx.principal.kind === "oauth"`).
+   * `undefined` for the `user` (first-party) and `system` (stdio/trusted)
+   * principals, which carry no scopes. This is the model input the scope gate
+   * (`scopeGateAllows`) reads when deciding whether a tool is visible/callable.
+   */
+  scopes?: string[];
+  ctx: AppContext & Partial<RequestContext>;
+}
+type McpAccessRule = boolean | ((ctx: McpAccessRuleContext) => boolean | Promise<boolean>);
+/**
+ * OAuth scope requirement declaration. A single scope string, a list (all
+ * required — AND), or `false` to explicitly require no scope (public even to
+ * scoped OAuth callers). `undefined` means "fall back to the default mapping".
+ */
+type McpRequiredScopes = string | string[] | false;
+interface McpWorkloadRequirement {
+  /** Named facts interpreted exclusively by the consumer-supplied authorizer. */
+  capabilities: readonly string[];
+  /** Optional named capability delegated to the opaque execution handoff. */
+  handoff?: string;
+}
+type McpEntityPolicy = boolean | {
+  expose?: boolean;
+  operations?: Record<string, boolean | McpAccessRule>;
+  /**
+   * Scopes an OAuth caller must hold to reach this entity. Declarable at
+   * the entity level (applies to every operation) and/or per operation via
+   * {@link McpEntityPolicy.operationScopes}. When omitted, the default
+   * operation→scope mapping is derived from the operation kind (e.g.
+   * `collections:<name>:read`). Resolved by `requiredScopesForOperation`
+   * and enforced by the scope gate (`scopeGateAllows`) at both
+   * `tools/list` and `tools/call`.
+   */
+  requiredScopes?: McpRequiredScopes;
+  /**
+   * Per-operation scope requirements, keyed by operation name
+   * (`list`/`get`/`create`/`update`/`delete`/`invoke`/…). Overrides both
+   * {@link McpEntityPolicy.requiredScopes} and the default mapping for the
+   * named operation.
+   */
+  operationScopes?: Record<string, McpRequiredScopes>;
+  workload?: McpWorkloadRequirement;
+  operationWorkloads?: Record<string, McpWorkloadRequirement>;
+  fields?: {
+    include?: string[];
+    exclude?: string[];
+  };
+  description?: string;
+};
+interface McpCrudConfig {
+  collections?: Record<string, McpEntityPolicy>;
+  globals?: Record<string, McpEntityPolicy>;
+  maxLimit?: number;
+}
+interface McpRoutesConfig {
+  routes?: Record<string, McpEntityPolicy>;
+}
+interface McpResourcesConfig {
+  collections?: Record<string, boolean>;
+  globals?: Record<string, boolean>;
+  routes?: Record<string, boolean>;
+}
+interface McpTransportConfig {
+  accessMode?: McpAccessMode;
+}
+interface McpHttpConfig extends McpTransportConfig {
+  allowedOrigins?: string[];
+  allowedHosts?: string[];
+  enableJsonResponse?: boolean;
+}
+interface McpStdioConfig {
+  /**
+   * Explicitly grants this local stdio process maintenance authority. Without
+   * this flag, stdio requires an exact user-mode `ctx`.
+   */
+  trustedMaintenance?: boolean;
+}
+interface McpExecutionLimits {
+  /** Maximum serialized tool input accepted after protocol decoding. */
+  maxInputBytes?: number;
+  /** Maximum object/array nesting accepted in decoded operation input. */
+  maxInputDepth?: number;
+  /** Maximum object/array nesting accepted in operation output. */
+  maxOutputDepth?: number;
+  /** Maximum object properties and array entries visited per value. */
+  maxValueNodes?: number;
+  /** Maximum serialized tool result returned to a caller. */
+  maxOutputBytes?: number;
+  /** Wall-clock budget for authorization plus execution. */
+  timeoutMs?: number;
+  /** Maximum in-flight operations for one released app snapshot. */
+  maxConcurrency?: number;
+  /** Maximum in-flight operations for one resolved caller principal. */
+  maxConcurrencyPerPrincipal?: number;
+  /** Maximum released tools across custom, CRUD, and route catalogs. */
+  maxTools?: number;
+  /** Maximum released schema resources. */
+  maxResources?: number;
+}
+type McpPublicErrorCode = "access_denied" | "invalid_input" | "input_too_large" | "output_too_large" | "timeout" | "cancelled" | "busy" | "internal";
+interface McpExecutionDiagnosticEvent {
+  correlationId: string;
+  requestId?: string | number;
+  transport: McpTransportKind;
+  operation: string;
+  durationMs: number;
+  outcome: "completed" | "rejected";
+  code?: McpPublicErrorCode;
+  /**
+   * Bounded and credential-redacted. Inputs, outputs, sessions, authorization
+   * envelopes, and workload attribution are never included.
+   */
+  internalError?: {
+    kind: "Error" | "Unknown";
+  };
+}
+interface McpExecutionConfig extends McpExecutionLimits {
+  /**
+   * Trusted server-side diagnostics sink. At most one unresolved callback is
+   * retained; subsequent events are dropped until it settles.
+   */
+  onDiagnostic?: (event: Readonly<McpExecutionDiagnosticEvent>) => void | Promise<void>;
+}
+interface McpConfig {
+  name?: string;
+  version?: string;
+  crud?: McpCrudConfig;
+  routes?: McpRoutesConfig;
+  resources?: McpResourcesConfig;
+  http?: McpHttpConfig;
+  stdio?: McpStdioConfig;
+  execution?: McpExecutionConfig;
+}
+interface McpExecutionOptions {
+  transport?: McpTransportKind;
+  accessMode?: McpAccessMode;
+  ctx?: AppContext & Partial<RequestContext>;
+  request?: Request;
+  config?: McpConfig;
+}
+interface McpWorkloadAuthorizationRequest {
+  phase: "discovery" | "call";
+  envelope: unknown;
+  tool: McpWorkloadToolFacts;
+}
+type McpWorkloadToolKind = "custom" | "collection" | "global" | "route";
+interface McpWorkloadToolFacts {
+  kind: McpWorkloadToolKind;
+  name: string;
+  operation: string;
+  intent: "read" | "effect";
+  transport: "workload";
+  capabilities: readonly string[];
+  handoff?: string;
+}
+interface McpWorkloadAuthorization {
+  context: unknown;
+  attribution?: unknown;
+}
+interface McpWorkloadExecutionControl {
+  signal: AbortSignal;
+  requestId: string | number;
+  correlationId: string;
+}
+interface McpWorkloadAuthorizer {
+  authorize(request: McpWorkloadAuthorizationRequest, control?: McpWorkloadExecutionControl): McpWorkloadAuthorization | null | Promise<McpWorkloadAuthorization | null>;
+}
+interface McpWorkloadContextBindingInput {
+  authorizationContext: unknown;
+  attribution?: unknown;
+  tool: McpWorkloadToolFacts;
+}
+interface McpWorkloadContextBinder {
+  /**
+   * Bind opaque authorization to the exact user-mode QUESTPIE context used for
+   * access rechecks and execution. System-mode contexts fail closed.
+   */
+  bind(input: McpWorkloadContextBindingInput, control?: McpWorkloadExecutionControl): (AppContext & Partial<RequestContext>) | Promise<AppContext & Partial<RequestContext>>;
+}
+/**
+ * Remote workload execution is intentionally not an {@link McpExecutionOptions}
+ * variant. It cannot inherit HTTP request identity, cookies, OAuth, requester
+ * sessions, access-mode overrides, or the stdio system default.
+ */
+interface WorkloadMcpServerOptions {
+  envelope: unknown;
+  /**
+   * Stable, non-secret consumer/tenant key for per-principal concurrency.
+   * Independent workload boundaries with different keys cannot exhaust one
+   * another's per-principal bucket. Omitted keys are isolated per boundary.
+   */
+  concurrencyKey?: string;
+  authorizer: McpWorkloadAuthorizer;
+  contextBinder: McpWorkloadContextBinder;
+  config?: McpConfig;
+  audit?: (event: McpWorkloadAuditEvent) => void | Promise<void>;
+  handoff?: McpWorkloadHandoff;
+}
+interface McpWorkloadHandoffInput {
+  authorizationContext: unknown;
+  attribution?: unknown;
+  toolName: string;
+  capability: string;
+  tool: McpWorkloadToolFacts;
+  metadata: unknown;
+  signal: AbortSignal;
+  requestId: string | number;
+  correlationId: string;
+  invoke: () => CallToolResult | Promise<CallToolResult>;
+}
+interface McpWorkloadHandoff {
+  execute(input: McpWorkloadHandoffInput): CallToolResult | Promise<CallToolResult>;
+}
+interface McpWorkloadAuditEvent {
+  phase: "discovery" | "call";
+  decision: "allowed" | "denied";
+  toolName?: string;
+  reason?: "authorization_denied" | "authorization_invalid" | "context_invalid";
+  attribution?: unknown;
+}
+interface McpToolHandlerArgs<TInput = unknown> {
+  input: TInput;
+  ctx: AppContext & Partial<RequestContext>;
+  transport: McpTransportKind;
+  accessMode: McpAccessMode;
+  request?: Request;
+  signal: AbortSignal;
+  requestId: string | number;
+  correlationId: string;
+}
+interface McpProgrammaticRequestOptions {
+  signal?: AbortSignal;
+  requestId?: string | number;
+}
+interface McpProgrammaticTool {
+  name: string;
+  title?: string;
+  description?: string;
+  inputSchema: Record<string, unknown>;
+  outputSchema?: Record<string, unknown>;
+  annotations?: ToolAnnotations;
+  _meta?: Record<string, unknown>;
+}
+interface McpProgrammaticToolResult {
+  content: Array<{
+    type: string;
+    [key: string]: unknown;
+  }>;
+  structuredContent?: Record<string, unknown>;
+  isError?: boolean;
+  _meta?: Record<string, unknown>;
+}
+interface McpWorkloadToolPort {
+  listCustomTools(options?: McpProgrammaticRequestOptions): Promise<{
+    tools: McpProgrammaticTool[];
+  }>;
+  callCustomTool(input: {
+    name: string;
+    input: unknown;
+    signal?: AbortSignal;
+    requestId?: string | number;
+  }): Promise<McpProgrammaticToolResult>;
+}
+interface McpToolConfig<TInputSchema extends z.ZodTypeAny = z.ZodTypeAny, TOutputSchema extends z.ZodTypeAny = z.ZodTypeAny> {
+  title?: string;
+  description?: string;
+  inputSchema?: TInputSchema;
+  outputSchema?: TOutputSchema;
+  annotations?: ToolAnnotations;
+  access: McpAccessRule;
+  /**
+   * Scopes an OAuth caller must hold to reach this custom tool (all required —
+   * AND), or `false` as an explicit no-OAuth-scope policy. Custom tools have no
+   * default mapping, so omission keeps the tool out of the released catalog. Enforced by the
+   * scope gate (`scopeGateAllows`) at both `tools/list` (hidden) and
+   * `tools/call` (denied); `system`/`user` callers carry no scopes and skip it.
+   */
+  scopes: McpRequiredScopes;
+  /** Explicit, fail-closed authority contract for remote workload execution. */
+  workload?: McpWorkloadRequirement;
+  _meta?: Record<string, unknown>;
+}
+interface McpToolDefinition<TInputSchema extends z.ZodTypeAny = z.ZodTypeAny, TOutputSchema extends z.ZodTypeAny = z.ZodTypeAny> {
+  readonly __brand: "mcpTool";
+  readonly name: string;
+  readonly config: McpToolConfig<TInputSchema, TOutputSchema>;
+  readonly handler: (args: McpToolHandlerArgs<z.infer<TInputSchema>>) => CallToolResult | Promise<CallToolResult>;
+}
+declare module "questpie" {
+  interface AppStateConfig {
+    mcp?: McpConfig;
+  }
+  interface ModuleDefinition {
+    mcpTools?: Record<string, McpToolDefinition>;
+  }
+}
+//#endregion
+//#region src/server/execution-boundary.d.ts
+/** Read a public boundary code without touching an error message or accessor. */
+declare function mcpPublicErrorCode(error: unknown): McpPublicErrorCode | undefined;
+//#endregion
+//#region src/server/runtime.d.ts
+type QuestpieApp = Parameters<typeof createContextFactory>[0];
+//#endregion
+//#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 };

package/dist/stdio.d.mts

@@ -1,2 +1,2 @@
-import { t as startStdioServer } from "./stdio-t_9rKayH.mjs";
+import { t as startStdioServer } from "./stdio-YoM70-42.mjs";
 export { startStdioServer };

package/dist/stdio.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@questpie/mcp",
-	"version": "3.15.2",
+	"version": "3.17.0",
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/questpie/questpie.git",
@@ -64,11 +64,12 @@
 	"scripts": {
 		"build": "tsdown",
 		"check-types": "tsc --noEmit",
-		"questpie:generate": "bun questpie generate --verbose"
+		"questpie:generate": "bun questpie generate --verbose",
+		"test": "bun test ./test"
 	},
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "^1.29.0",
-		"questpie": "^3.15.2",
+		"questpie": "^3.17.0",
 		"zod": "^4.2.1"
 	},
 	"devDependencies": {
@@ -78,6 +79,6 @@
 		"tsdown": "^0.18.3"
 	},
 	"peerDependencies": {
-		"questpie": "^3.0.0"
+		"questpie": "^3.17.0"
 	}
 }