@nextsparkjs/core 0.1.0-beta.184 → 0.1.0-beta.185

package/dist/lib/mcp/types.d.ts

@@ -0,0 +1,184 @@
+/**
+ * MCP Engine — shared types.
+ *
+ * The engine is registry-driven: it reads the entity registry passed into
+ * createMcpEngine() and never imports theme files directly. Theme extensions
+ * (overrides, extra tools, translations) are injected via McpEngineOptions,
+ * which the default route template assembles from the generated
+ * MCP_OVERRIDES registry.
+ */
+import type { z } from 'zod';
+import type { EntityConfig } from '../entities/types';
+export type McpOperation = 'list' | 'get' | 'create' | 'update' | 'delete';
+/**
+ * Mutable shape used while building tool input schemas. Assignable to the
+ * SDK's ZodRawShape (zod 4 declares it Readonly<Record<string, $ZodType>>).
+ */
+export type McpShape = Record<string, z.ZodTypeAny>;
+export declare const MUTATION_OPERATIONS: McpOperation[];
+/** Resolved per-request identity, injected into every tool handler. */
+export interface ToolExecutionContext {
+    userId: string;
+    userRole: string;
+    teamId: string;
+    /** Raw Authorization header, forwarded verbatim to in-process handlers. */
+    authHeader: string;
+    /** api_key.id of the caller — required for audit logging. */
+    apiKeyId: string | null;
+    scopes: string[];
+}
+export interface McpToolAnnotations {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
+export interface McpToolResultContent {
+    type: 'text';
+    text: string;
+}
+export interface McpToolResult {
+    content: McpToolResultContent[];
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+export interface McpToolDefinition {
+    name: string;
+    title: string;
+    description: string;
+    /** Raw shape passed to the SDK for tools/list JSON Schema generation. */
+    inputSchema: McpShape;
+    /**
+     * Strict validator run inside the handler before executing. The SDK builds
+     * a non-strict object from inputSchema; this one rejects unknown keys and
+     * enforces cross-field rules (e.g. from/to require dateField).
+     */
+    strictSchema: z.ZodTypeAny;
+    annotations?: McpToolAnnotations;
+    handler: (args: Record<string, unknown>, ctx: ToolExecutionContext) => Promise<McpToolResult>;
+    /** Metadata for audit entries. */
+    meta?: {
+        entitySlug?: string;
+        operation?: McpOperation | 'workflow';
+    };
+}
+/** Thrown by overrides/handlers to short-circuit with an actionable message. */
+export declare class McpToolError extends Error {
+    constructor(message: string);
+}
+/** Result of an in-process entity API invocation. */
+export interface EntityApiResult {
+    status: number;
+    body: {
+        success: boolean;
+        data?: unknown;
+        info?: Record<string, unknown>;
+        error?: string;
+        code?: string;
+        details?: unknown;
+    };
+}
+export interface ExecuteEntityArgs {
+    slug: string;
+    operation: McpOperation;
+    id?: string;
+    query?: Record<string, string>;
+    body?: unknown;
+}
+export type EntityExecutor = (args: ExecuteEntityArgs, ctx: ToolExecutionContext) => Promise<EntityApiResult>;
+/**
+ * API handed to override extraTools factories.
+ *
+ * `execute` and `entitySchemas` are the ENGINE's own wired versions: output
+ * normalization (dates, transformOutput) and schema context (i18n option
+ * labels, overrides) are applied there, so a workflow tool behaves exactly
+ * like a generated one. Building schemas or calling handlers directly from an
+ * override would silently skip both.
+ */
+export interface EngineApi {
+    execute: EntityExecutor;
+    /** Schemas for an entity, built with the engine's i18n + override context. */
+    entitySchemas: (slug: string) => {
+        createShape: McpShape;
+        updateShape: McpShape;
+    };
+    toolPrefix: string;
+    defaultTimezone: string;
+    registry: Record<string, EntityConfig>;
+    translateApiError: (result: EntityApiResult, context: {
+        slug: string;
+        operation: string;
+        hints?: string[];
+    }) => string;
+}
+export interface McpEntityOverride {
+    /** Hide the whole entity from the MCP surface. */
+    exclude?: boolean;
+    /** Hide specific generated tools. First-class security mechanism. */
+    excludeOperations?: McpOperation[];
+    /** Field names that become optional in the MCP input schema even if the API requires them (pair with transformInput enforcement). */
+    relaxRequired?: string[];
+    describe?: {
+        entity?: string;
+        fields?: Record<string, string>;
+        tools?: Partial<Record<McpOperation, string>>;
+    };
+    /** Appended to 500-with-no-code errors (core swallows CHECK violations). */
+    errorHints?: string[];
+    /** May throw McpToolError to reject with an actionable message. */
+    transformInput?: (operation: McpOperation, input: Record<string, unknown>, ctx: ToolExecutionContext) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    transformOutput?: (operation: McpOperation, output: unknown) => unknown;
+    extraTools?: (api: EngineApi) => McpToolDefinition[];
+}
+export interface AuditEntry {
+    apiKeyId: string | null;
+    userId: string;
+    tool: string;
+    entitySlug?: string;
+    operation?: string;
+    recordId?: string;
+    teamId: string;
+    statusCode: number;
+    requestSummary: Record<string, unknown>;
+    responseTimeMs: number;
+}
+export interface EntityPresetInfo {
+    summary?: string;
+    presets: Array<{
+        id: string;
+        title?: string;
+        method?: string;
+        description?: string;
+        params?: Record<string, unknown>;
+        payload?: Record<string, unknown>;
+    }>;
+}
+export interface McpEngineOptions {
+    /** e.g. 'acme' → acme_list_customers. Comes from app/theme config. */
+    toolPrefix: string;
+    serverInfo?: {
+        name: string;
+        version: string;
+    };
+    /** Core/reserved slugs never exposed (e.g. 'patterns'). */
+    excludeSlugs?: string[];
+    /** Operations generated by default for every entity. */
+    defaultOperations?: McpOperation[];
+    overrides?: Record<string, McpEntityOverride>;
+    /**
+     * Per-entity description material harvested from api/presets.ts
+     * (summary → entity description, presets → few-shot examples).
+     */
+    presets?: Record<string, EntityPresetInfo>;
+    /** Resolve the localized label of a select option ("dairy" → "Lácteos"). */
+    translateOption?: (slug: string, fieldName: string, value: string) => string | undefined;
+    /** IANA timezone used to resolve relative dates ("this_week"). */
+    defaultTimezone?: string;
+    /** Extra tools not attached to an entity (e.g. list_team_members). */
+    utilityTools?: (api: EngineApi) => McpToolDefinition[];
+    /** Injectable for tests. Defaults to the api_audit_log writer. */
+    audit?: (entry: AuditEntry) => Promise<void>;
+    /** Injectable for tests. Defaults to the in-process executor. */
+    executor?: EntityExecutor;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/mcp/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/mcp/types.ts"],"names":[],"mappings":"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"}

package/dist/lib/mcp/types.js

@@ -0,0 +1,11 @@
+const MUTATION_OPERATIONS = ["create", "update", "delete"];
+class McpToolError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "McpToolError";
+  }
+}
+export {
+  MUTATION_OPERATIONS,
+  McpToolError
+};

package/dist/styles/classes.json

@@ -1,5 +1,5 @@
 {
-  "generated": "2026-08-06T23:38:43.156Z",
+  "generated": "2026-09-01T15:13:00.302Z",
   "totalClasses": 1087,
   "classes": [
     "!text-2xl",