@happyvertical/smrt-core 0.40.59 → 0.40.61

package/dist/generators/mcp.js

@@ -1,8 +1,9 @@
-import { SMRT_CUSTOM_ACTION_ERROR_METADATA_KEY, buildCustomActionInputSchema, buildCustomActionInvocationArgs, customActionParameterInputName, normalizeCustomActionFailure, resolveCustomActionMetadata } from "./custom-action.js";
+import { SMRT_CUSTOM_ACTION_ERROR_METADATA_KEY, buildCustomActionInvocationArgs, customActionParameterInputName, normalizeCustomActionFailure, resolveCustomActionMetadata } from "./custom-action.js";
 import { ObjectRegistry } from "../registry.js";
 import { SmrtCollection } from "../collection.js";
 import { runWithTenantGate } from "./tenant-gate.js";
 import { generateClaudeConfig, generateMCPDocumentation, generateMCPScript, generateRuntimeBootstrap } from "./mcp-runtime-template.js";
+import { buildToolInputSchema, fieldTypeToJsonSchema, finalizeMcpJsonSchema } from "./tool-schema.js";
 import { dirname, resolve } from "node:path";
 import { mkdir, writeFile } from "node:fs/promises";
 //#region src/generators/mcp.ts
@@ -11,6 +12,27 @@ import { mkdir, writeFile } from "node:fs/promises";
 *
 * Exposes smrt objects as AI tools for Claude, GPT, and other AI models
 */
+var MCP_STABLE_CATALOG_TTL_MS = 864e5;
+/**
+* Resolve the generated tools/list cache policy at generation time.
+*
+* A shared cache may otherwise serve one tenant's tool catalog to another, so
+* public caching is deliberately double opt-in and unavailable when a
+* generated server exposes any tenant-scoped object.
+*/
+function resolveMCPToolListCacheHint(options, hasTenantScopedTools) {
+	const ttlMs = options?.ttlMs ?? 864e5;
+	if (!Number.isSafeInteger(ttlMs) || ttlMs < 0) throw new RangeError("MCP tools/list cache ttlMs must be a non-negative safe integer.");
+	if (options?.cacheScope !== void 0 && options.cacheScope !== "private" && options.cacheScope !== "public") throw new RangeError("MCP tools/list cacheScope must be 'private' or 'public'.");
+	return {
+		ttlMs,
+		cacheScope: !hasTenantScopedTools && options?.cacheScope === "public" && options.publicCatalog === true ? "public" : "private"
+	};
+}
+/** Return a copied, canonical tool sequence for byte-stable tools/list output. */
+function sortMCPTools(tools) {
+	return [...tools].sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+}
 var CustomActionFailureError = class extends Error {
 	failure;
 	constructor(failure) {
@@ -83,7 +105,7 @@ var MCPGenerator = class {
 			const objectTools = await this.generateObjectTools(simpleName, shouldInclude);
 			tools.push(...objectTools);
 		}
-		return tools;
+		return sortMCPTools(tools);
 	}
 	/**
 	* Generate tools for a specific object
@@ -96,96 +118,32 @@ var MCPGenerator = class {
 		if (shouldInclude("list")) tools.push({
 			name: `${lowerName}_list`,
 			description: `List ${objectName} objects with optional filtering`,
-			inputSchema: {
-				type: "object",
-				properties: {
-					limit: {
-						type: "integer",
-						description: "Maximum number of items to return",
-						default: 50,
-						minimum: 1,
-						maximum: 1e3
-					},
-					offset: {
-						type: "integer",
-						description: "Number of items to skip",
-						default: 0,
-						minimum: 0
-					},
-					orderBy: {
-						type: "string",
-						description: "Field to order by (e.g., \"created_at DESC\")"
-					},
-					where: {
-						type: "object",
-						description: "Filter conditions as key-value pairs",
-						additionalProperties: true
-					}
-				}
-			}
+			inputSchema: this.buildInputSchema(objectName, "list", fields),
+			outputSchema: this.buildOutputSchema(objectName, "list", fields)
 		});
 		if (shouldInclude("get")) tools.push({
 			name: `${lowerName}_get`,
 			description: `Get a specific ${objectName} by ID or slug`,
-			inputSchema: {
-				type: "object",
-				properties: {
-					id: {
-						type: "string",
-						description: "Unique identifier of the object"
-					},
-					slug: {
-						type: "string",
-						description: "URL-friendly identifier of the object"
-					}
-				},
-				required: ["id"]
-			}
+			inputSchema: this.buildInputSchema(objectName, "get", fields),
+			outputSchema: this.buildOutputSchema(objectName, "get", fields)
+		});
+		if (shouldInclude("create")) tools.push({
+			name: `${lowerName}_create`,
+			description: `Create a new ${objectName}`,
+			inputSchema: this.buildInputSchema(objectName, "create", fields),
+			outputSchema: this.buildOutputSchema(objectName, "create", fields)
+		});
+		if (shouldInclude("update")) tools.push({
+			name: `${lowerName}_update`,
+			description: `Update an existing ${objectName}`,
+			inputSchema: this.buildInputSchema(objectName, "update", fields),
+			outputSchema: this.buildOutputSchema(objectName, "update", fields)
 		});
-		if (shouldInclude("create")) {
-			const properties = {};
-			const required = [];
-			for (const [fieldName, field] of fields) {
-				properties[fieldName] = this.fieldToMCPSchema(field);
-				if (field._meta?.required) required.push(fieldName);
-			}
-			tools.push({
-				name: `${lowerName}_create`,
-				description: `Create a new ${objectName}`,
-				inputSchema: {
-					type: "object",
-					properties,
-					required
-				}
-			});
-		}
-		if (shouldInclude("update")) {
-			const properties = { id: {
-				type: "string",
-				description: "ID of the object to update"
-			} };
-			for (const [fieldName, field] of fields) properties[fieldName] = this.fieldToMCPSchema(field);
-			tools.push({
-				name: `${lowerName}_update`,
-				description: `Update an existing ${objectName}`,
-				inputSchema: {
-					type: "object",
-					properties,
-					required: ["id"]
-				}
-			});
-		}
 		if (shouldInclude("delete")) tools.push({
 			name: `${lowerName}_delete`,
 			description: `Delete a ${objectName} by ID`,
-			inputSchema: {
-				type: "object",
-				properties: { id: {
-					type: "string",
-					description: "ID of the object to delete"
-				} },
-				required: ["id"]
-			}
+			inputSchema: this.buildInputSchema(objectName, "delete", fields),
+			outputSchema: this.buildOutputSchema(objectName, "delete", fields)
 		});
 		if (classInfo) {
 			const mcpConfig = ObjectRegistry.getConfig(objectName).mcp;
@@ -227,7 +185,8 @@ var MCPGenerator = class {
 		return {
 			name: `${lowerName}_${methodName}`.toLowerCase(),
 			description: `Execute ${methodName} action on ${objectName}`,
-			inputSchema: buildCustomActionInputSchema(metadata)
+			inputSchema: this.buildInputSchema(objectName, methodName, ObjectRegistry.getFields(objectName), metadata),
+			outputSchema: this.buildOutputSchema(objectName, methodName, ObjectRegistry.getFields(objectName))
 		};
 	}
 	resolveCustomActionMetadata(objectName, action, method, collectionReceiver = false) {
@@ -254,45 +213,193 @@ var MCPGenerator = class {
 			return false;
 		}
 	}
+	/** Normalize registry fields for the transport-neutral schema emitter. */
+	toToolFields(fields) {
+		return Array.from(fields, ([name, field]) => ({
+			name,
+			type: field.type,
+			required: field.required ?? field._meta?.required,
+			nullable: field._meta?.nullable === true,
+			description: typeof field._meta?.description === "string" ? field._meta.description : void 0,
+			default: field._meta?.default,
+			maxLength: field._meta?.maxLength,
+			minLength: field._meta?.minLength,
+			min: field._meta?.min,
+			max: field._meta?.max,
+			related: field.related
+		}));
+	}
 	/**
-	* Convert field definition to MCP schema
+	* Add the optional STI discriminator branches to write schemas. The legacy
+	* branch preserves existing base-class creates that let SMRT pick the base
+	* type; an explicit `_meta_type` selects a known child collection below.
 	*/
-	fieldToMCPSchema(field) {
-		const schema = { description: field._meta?.description || `${field.type} field` };
-		switch (field.type) {
-			case "text":
-				schema.type = "string";
-				if (field._meta?.maxLength) schema.maxLength = field._meta.maxLength;
-				if (field._meta?.minLength) schema.minLength = field._meta.minLength;
-				break;
-			case "integer":
-				schema.type = "integer";
-				if (field._meta?.min !== void 0) schema.minimum = field._meta.min;
-				if (field._meta?.max !== void 0) schema.maximum = field._meta.max;
-				break;
-			case "decimal":
-				schema.type = "number";
-				if (field._meta?.min !== void 0) schema.minimum = field._meta.min;
-				if (field._meta?.max !== void 0) schema.maximum = field._meta.max;
-				break;
-			case "boolean":
-				schema.type = "boolean";
-				break;
-			case "datetime":
-				schema.type = "string";
-				schema.format = "date-time";
-				break;
-			case "json":
-				schema.type = "object";
-				break;
-			case "foreignKey":
-				schema.type = "string";
-				if (!field._meta?.description) schema.description = `ID of related ${field.related || "object"}`;
-				break;
-			default: schema.type = "string";
+	buildInputSchema(objectName, action, fields, customAction) {
+		const schema = buildToolInputSchema(action, this.toToolFields(fields), customAction, ObjectRegistry.getConfig(objectName).idType);
+		if (action !== "create" && action !== "update") return schema;
+		const variants = this.getStiVariants(objectName);
+		if (variants.length === 0) return schema;
+		const properties = {
+			...schema.properties ?? {},
+			_meta_type: {
+				type: "string",
+				description: "Optional STI discriminator. When provided for create, selects the declared subtype."
+			}
+		};
+		return finalizeMcpJsonSchema({
+			...schema,
+			properties,
+			oneOf: [{ not: { required: ["_meta_type"] } }, ...variants.map(({ name, discriminator }) => {
+				const variantFields = ObjectRegistry.getFields(name);
+				return {
+					properties: {
+						...this.buildFieldSchemaProperties(variantFields),
+						_meta_type: { const: discriminator }
+					},
+					required: ["_meta_type", ...this.toToolFields(variantFields).filter((field) => field.required).map((field) => field.name)]
+				};
+			})]
+		});
+	}
+	/**
+	* Public output schemas follow the actual `toPublicJSON()` boundary: known
+	* non-sensitive fields are described, while `additionalProperties` keeps
+	* framework/system fields and application transforms honest.
+	*/
+	buildOutputSchema(objectName, action, fields) {
+		const errorSchema = {
+			type: "object",
+			properties: { error: {
+				type: "object",
+				additionalProperties: true
+			} },
+			required: ["error"]
+		};
+		if (![
+			"list",
+			"get",
+			"create",
+			"update",
+			"delete"
+		].includes(action)) return finalizeMcpJsonSchema({
+			type: "object",
+			anyOf: [{
+				type: "object",
+				properties: { data: {} },
+				required: ["data"]
+			}, { $ref: "#/$defs/error" }],
+			$defs: { error: errorSchema }
+		});
+		const itemSchema = this.buildPublicItemSchema(objectName, fields);
+		if (action === "list") return finalizeMcpJsonSchema({
+			type: "object",
+			anyOf: [{
+				type: "object",
+				properties: {
+					data: {
+						type: "array",
+						items: { $ref: "#/$defs/publicItem" }
+					},
+					meta: {
+						type: "object",
+						properties: {
+							total: {
+								type: "integer",
+								minimum: 0
+							},
+							limit: {
+								type: "integer",
+								minimum: 0
+							},
+							offset: {
+								type: "integer",
+								minimum: 0
+							},
+							count: {
+								type: "integer",
+								minimum: 0
+							}
+						},
+						required: [
+							"total",
+							"limit",
+							"offset",
+							"count"
+						]
+					}
+				},
+				required: ["data", "meta"]
+			}, { $ref: "#/$defs/error" }],
+			$defs: {
+				publicItem: itemSchema,
+				error: errorSchema
+			}
+		});
+		if (action === "delete") return finalizeMcpJsonSchema({
+			type: "object",
+			anyOf: [{
+				type: "object",
+				properties: {
+					success: { const: true },
+					message: { type: "string" }
+				},
+				required: ["success", "message"]
+			}, { $ref: "#/$defs/error" }],
+			$defs: { error: errorSchema }
+		});
+		return finalizeMcpJsonSchema({
+			type: "object",
+			anyOf: [itemSchema, { $ref: "#/$defs/error" }],
+			$defs: { error: errorSchema }
+		});
+	}
+	buildPublicItemSchema(objectName, fields) {
+		const properties = this.buildFieldSchemaProperties(fields, true);
+		const variants = this.getStiVariants(objectName);
+		if (variants.length > 0) return { oneOf: variants.map(({ name, discriminator }) => ({
+			type: "object",
+			properties: {
+				...this.buildFieldSchemaProperties(ObjectRegistry.getFields(name), true),
+				_meta_type: { const: discriminator }
+			},
+			required: ["_meta_type"],
+			additionalProperties: true
+		})) };
+		return {
+			type: "object",
+			properties,
+			additionalProperties: true
+		};
+	}
+	buildFieldSchemaProperties(fields, publicOnly = false) {
+		const properties = {};
+		for (const [name, field] of fields) {
+			if (publicOnly && (field._meta?.sensitive === true || field._meta?.transient === true)) continue;
+			const [toolField] = this.toToolFields(/* @__PURE__ */ new Map([[name, field]]));
+			if (!toolField) continue;
+			properties[name] = { ...fieldTypeToJsonSchema(toolField) };
 		}
-		if (field._meta?.default !== void 0) schema.default = field._meta.default;
-		return schema;
+		return properties;
+	}
+	getStiVariants(objectName) {
+		if (ObjectRegistry.getTableStrategy(objectName) !== "sti") return [];
+		const base = ObjectRegistry.getClass(objectName);
+		const baseNames = new Set([
+			objectName,
+			base?.name,
+			base?.qualifiedName
+		].filter((name) => typeof name === "string"));
+		const variants = /* @__PURE__ */ new Map();
+		for (const [key, info] of ObjectRegistry.getAllClasses()) {
+			const name = info.name || key;
+			if (!ObjectRegistry.getInheritanceChain(name).some((ancestor) => baseNames.has(ancestor))) continue;
+			const discriminator = info.qualifiedName || name;
+			variants.set(discriminator, {
+				name,
+				discriminator
+			});
+		}
+		return Array.from(variants.values()).sort((left, right) => left.discriminator.localeCompare(right.discriminator));
 	}
 	/**
 	* Handle MCP tool calls
@@ -319,25 +426,56 @@ var MCPGenerator = class {
 			if (!classInfo) throw new Error(`Object type '${objectName}' not found`);
 			const collection = await this.getCollection(actualObjectName, classInfo);
 			const result = await this.executeAction(collection, action, args, actualObjectName);
-			return { content: [{
-				type: "text",
-				text: JSON.stringify(result, null, 2)
-			}] };
+			const publicResult = this.toJsonValue(result);
+			const structuredContent = this.toStructuredContent(action, publicResult);
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify(publicResult, null, 2)
+				}],
+				structuredContent
+			};
 		} catch (error) {
-			if (error instanceof CustomActionFailureError) return {
+			if (error instanceof CustomActionFailureError) {
+				const structuredContent = { error: error.failure };
+				return {
+					content: [{
+						type: "text",
+						text: JSON.stringify(structuredContent)
+					}],
+					isError: true,
+					structuredContent,
+					_meta: { [SMRT_CUSTOM_ACTION_ERROR_METADATA_KEY]: error.failure }
+				};
+			}
+			const message = error instanceof Error ? error.message : "Unknown error";
+			return {
 				content: [{
 					type: "text",
-					text: JSON.stringify({ error: error.failure })
+					text: `Error: ${message}`
 				}],
 				isError: true,
-				_meta: { [SMRT_CUSTOM_ACTION_ERROR_METADATA_KEY]: error.failure }
+				structuredContent: { error: { message } }
 			};
-			return { content: [{
-				type: "text",
-				text: `Error: ${error instanceof Error ? error.message : "Unknown error"}`
-			}] };
 		}
 	}
+	/** Convert runtime values to the JSON values MCP structuredContent permits. */
+	toJsonValue(value) {
+		const serialized = JSON.stringify(value);
+		return serialized === void 0 ? null : JSON.parse(serialized);
+	}
+	/** Build the MCP-required object root without changing legacy text payloads. */
+	toStructuredContent(action, publicResult) {
+		if (![
+			"list",
+			"get",
+			"create",
+			"update",
+			"delete"
+		].includes(action)) return { data: publicResult };
+		if (publicResult === null || typeof publicResult !== "object" || Array.isArray(publicResult)) throw new Error(`Expected object result for MCP ${action} action`);
+		return publicResult;
+	}
 	/**
 	* Get or create collection for an object
 	*/
@@ -433,14 +571,24 @@ var MCPGenerator = class {
 		if (!this.context.user) throw new Error("Authentication required");
 	}
 	async executeAction(collection, action, args, objectName) {
+		let targetCollection = collection;
+		let targetObjectName = objectName;
+		if (action === "create" && objectName && typeof args._meta_type === "string") {
+			const variant = this.getStiVariants(objectName).find((candidate) => candidate.discriminator === args._meta_type);
+			if (!variant) throw new Error(`Unknown STI discriminator: ${args._meta_type}`);
+			const classInfo = ObjectRegistry.getClass(variant.name);
+			if (!classInfo) throw new Error(`STI subtype '${variant.name}' is not registered`);
+			targetCollection = await this.getCollection(variant.name, classInfo);
+			targetObjectName = variant.name;
+		}
 		const mutating = action !== "list" && action !== "get";
-		this.requireToolAuth(objectName, mutating);
+		this.requireToolAuth(targetObjectName, mutating);
 		return runWithTenantGate({
-			className: objectName,
+			className: targetObjectName,
 			tenantId: this.context.tenantId,
 			allowCrossTenant: this.context.allowCrossTenant,
 			surface: "MCP"
-		}, () => this.runAction(collection, action, args, objectName));
+		}, () => this.runAction(targetCollection, action, args, targetObjectName));
 	}
 	/**
 	* Derive the set of tenant-scoped object names (lowercased simple names) from
@@ -482,6 +630,29 @@ var MCPGenerator = class {
 		return Array.from(scoped);
 	}
 	/**
+	* Whether a catalog contains a tenant-scoped class for cache isolation.
+	*
+	* Unlike the emitted runtime tenant gate, cache visibility must also fail
+	* closed for core-declared `@smrt({ tenantScoped })` models when the optional
+	* tenancy package is not installed. The registry covers that form, while
+	* `tenantScopedObjectNames()` covers the tenancy-owned decorator form.
+	*/
+	async hasTenantScopedTools(tools) {
+		if ((await this.tenantScopedObjectNames(tools)).length > 0) return true;
+		for (const tool of tools) {
+			const [objectName] = tool.name.split("_");
+			if (!objectName) continue;
+			for (const [key, info] of ObjectRegistry.getAllClasses()) {
+				const simpleName = info.name || key;
+				if (simpleName.toLowerCase() === objectName.toLowerCase()) {
+					if (ObjectRegistry.isTenantScoped(simpleName)) return true;
+					break;
+				}
+			}
+		}
+		return false;
+	}
+	/**
 	* Execute a resolved MCP action (CRUD or custom) against a collection. Always
 	* invoked inside the tenant gate established by {@link executeAction}.
 	*/
@@ -638,6 +809,8 @@ var MCPGenerator = class {
 		if (modular) await this.generateModularServer(outputDir, serverName, serverVersion, debug);
 		else {
 			const tools = await this.generateTools();
+			const tenantScopedObjects = await this.tenantScopedObjectNames(tools);
+			const hasTenantScopedTools = tenantScopedObjects.length > 0 || await this.hasTenantScopedTools(tools);
 			await writeFile(resolvedPath, generateRuntimeBootstrap({
 				name: serverName,
 				version: serverVersion,
@@ -647,7 +820,9 @@ var MCPGenerator = class {
 				debug,
 				tools,
 				customActions: await this.runtimeCustomActions(tools),
-				tenantScopedObjects: await this.tenantScopedObjectNames(tools)
+				tenantScopedObjects,
+				stiTargets: this.runtimeStiTargets(tools),
+				toolListCacheHint: resolveMCPToolListCacheHint(this.config.cache?.toolsList, hasTenantScopedTools)
 			}), "utf-8");
 			console.log(`✅ Generated MCP server: ${resolvedPath}`);
 		}
@@ -703,6 +878,28 @@ var MCPGenerator = class {
 		return metadata;
 	}
 	/**
+	* Emit only the STI discriminator targets advertised by create-tool schemas.
+	* Generated processes start with an empty registry, so resolving the
+	* qualified target through `getCollection()` both validates the declaration
+	* and lets the public registry loader register the selected subtype.
+	*/
+	runtimeStiTargets(tools) {
+		const targets = {};
+		const classes = ObjectRegistry.getAllClasses();
+		for (const tool of tools) {
+			const separator = tool.name.indexOf("_");
+			if (separator === -1 || tool.name.slice(separator + 1) !== "create") continue;
+			const objectPrefix = tool.name.slice(0, separator);
+			const matched = Array.from(classes.entries()).find(([key, info]) => (info.name || key).toLowerCase() === objectPrefix);
+			if (!matched) continue;
+			const [key, classInfo] = matched;
+			const variants = this.getStiVariants(classInfo.name || key);
+			if (variants.length === 0) continue;
+			targets[objectPrefix] = Object.fromEntries(variants.map((variant) => [variant.discriminator, variant.discriminator]));
+		}
+		return targets;
+	}
+	/**
 	* Generate modular MCP server structure
 	*
 	* Creates separate files for tools, handlers, configuration, and main entry point.
@@ -721,15 +918,17 @@ var MCPGenerator = class {
 		const configPath = resolve(outputDir, "config.ts");
 		await writeFile(configPath, this.generateConfigFile(serverName, serverVersion, debug), "utf-8");
 		console.log(`✅ Generated config: ${configPath}`);
+		const generatedTools = await this.generateTools();
 		const toolsPath = resolve(toolsDir, "index.ts");
-		await writeFile(toolsPath, await this.generateToolsFile(), "utf-8");
+		await writeFile(toolsPath, this.generateToolsFile(generatedTools), "utf-8");
 		console.log(`✅ Generated tools: ${toolsPath}`);
 		const handlersPath = resolve(handlersDir, "index.ts");
-		const tenantScopedObjects = await this.tenantScopedObjectNames(await this.generateTools());
+		const tenantScopedObjects = await this.tenantScopedObjectNames(generatedTools);
+		const hasTenantScopedTools = tenantScopedObjects.length > 0 || await this.hasTenantScopedTools(generatedTools);
 		await writeFile(handlersPath, await this.generateHandlersFile(tenantScopedObjects), "utf-8");
 		console.log(`✅ Generated handlers: ${handlersPath}`);
 		const indexPath = resolve(outputDir, "index.js");
-		await writeFile(indexPath, this.generateModularIndex(), "utf-8");
+		await writeFile(indexPath, this.generateModularIndex(resolveMCPToolListCacheHint(this.config.cache?.toolsList, hasTenantScopedTools)), "utf-8");
 		console.log(`✅ Generated MCP server: ${indexPath}`);
 	}
 	/**
@@ -750,8 +949,7 @@ export const DEBUG = ${debug};
 	/**
 	* Generate tools definitions file for modular server
 	*/
-	async generateToolsFile() {
-		const tools = await this.generateTools();
+	generateToolsFile(tools) {
 		return `/**
  * MCP Tools Definitions
  * Auto-generated from SMRT objects
@@ -761,14 +959,15 @@ export const tools: Array<{
   name: string;
   description: string;
   inputSchema: any;
+  outputSchema: any;
 }> = ${JSON.stringify(tools, null, 2)};
 `;
 	}
 	/**
 	* Generate switch cases for tool execution
 	*/
-	async generateToolSwitchCases(indent = "    ") {
-		const tools = await this.generateTools();
+	async generateToolSwitchCases(indent = "    ", generatedTools) {
+		const tools = generatedTools ?? await this.generateTools();
 		const capitalize = (str) => str.charAt(0).toUpperCase() + str.slice(1);
 		return (await Promise.all(tools.map(async (tool) => {
 			const separator = tool.name.indexOf("_");
@@ -781,13 +980,17 @@ ${indent}  const offset = args.offset ?? 0;
 ${indent}  const where = args.where ?? {};
 
 ${indent}  const collection = await ObjectRegistry.getCollection('${capitalize(objectName)}', {
-${indent}    persistence: { type: 'sql', url: process.env.DATABASE_URL || ':memory:' },
+${indent}    persistence: { type: process.env.DATABASE_TYPE || 'sqlite', url: process.env.DATABASE_URL || ':memory:' },
 ${indent}    ai: aiConfig
 ${indent}  });
 
 ${indent}  const items = await collection.list({ where, limit, offset });
 ${indent}  const itemsPublic = items.map((item) => item.toPublicJSON(PUBLIC_JSON_OPTIONS));
-${indent}  return { content: [{ type: 'text', text: JSON.stringify(itemsPublic) }] };
+${indent}  const structuredContent = {
+${indent}    data: itemsPublic,
+${indent}    meta: { total: await collection.count({ where }), limit, offset, count: items.length },
+${indent}  };
+${indent}  return successResult(structuredContent, JSON.stringify(itemsPublic));
 ${indent}}`;
 				case "get": return `${indent}case '${tool.name}': {
 ${indent}  if (!args.id && !args.slug) {
@@ -795,7 +998,7 @@ ${indent}    throw new Error('Either id or slug is required');
 ${indent}  }
 
 ${indent}  const collection = await ObjectRegistry.getCollection('${capitalize(objectName)}', {
-${indent}    persistence: { type: 'sql', url: process.env.DATABASE_URL || ':memory:' },
+${indent}    persistence: { type: process.env.DATABASE_TYPE || 'sqlite', url: process.env.DATABASE_URL || ':memory:' },
 ${indent}    ai: aiConfig
 ${indent}  });
 
@@ -806,18 +1009,15 @@ ${indent}  if (!item) {
 ${indent}    throw new Error('Object not found');
 ${indent}  }
 
-${indent}  return { content: [{ type: 'text', text: JSON.stringify(item.toPublicJSON(PUBLIC_JSON_OPTIONS)) }] };
+${indent}  return successResult(item.toPublicJSON(PUBLIC_JSON_OPTIONS));
 ${indent}}`;
 				case "create": return `${indent}case '${tool.name}': {
-${indent}  const collection = await ObjectRegistry.getCollection('${capitalize(objectName)}', {
-${indent}    persistence: { type: 'sql', url: process.env.DATABASE_URL || ':memory:' },
-${indent}    ai: aiConfig
-${indent}  });
+${indent}  const { collection, objectName: targetObjectName } = await resolveCreateTarget('${objectName}', args, aiConfig);
 
-${indent}  const newItem = await collection.create(applyWritablePolicy('${capitalize(objectName)}', args));
+${indent}  const newItem = await collection.create(applyWritablePolicy(targetObjectName, args));
 ${indent}  await newItem.save();
 
-${indent}  return { content: [{ type: 'text', text: JSON.stringify(newItem.toPublicJSON(PUBLIC_JSON_OPTIONS)) }] };
+${indent}  return successResult(newItem.toPublicJSON(PUBLIC_JSON_OPTIONS));
 ${indent}}`;
 				case "update": return `${indent}case '${tool.name}': {
 ${indent}  const { id, ...updateData } = args;
@@ -826,7 +1026,7 @@ ${indent}    throw new Error('ID is required for update');
 ${indent}  }
 
 ${indent}  const collection = await ObjectRegistry.getCollection('${capitalize(objectName)}', {
-${indent}    persistence: { type: 'sql', url: process.env.DATABASE_URL || ':memory:' },
+${indent}    persistence: { type: process.env.DATABASE_TYPE || 'sqlite', url: process.env.DATABASE_URL || ':memory:' },
 ${indent}    ai: aiConfig
 ${indent}  });
 
@@ -838,7 +1038,7 @@ ${indent}  }
 ${indent}  Object.assign(existing, applyWritablePolicy('${capitalize(objectName)}', updateData));
 ${indent}  await existing.save();
 
-${indent}  return { content: [{ type: 'text', text: JSON.stringify(existing.toPublicJSON(PUBLIC_JSON_OPTIONS)) }] };
+${indent}  return successResult(existing.toPublicJSON(PUBLIC_JSON_OPTIONS));
 ${indent}}`;
 				case "delete": return `${indent}case '${tool.name}': {
 ${indent}  if (!args.id) {
@@ -846,7 +1046,7 @@ ${indent}    throw new Error('ID is required for delete');
 ${indent}  }
 
 ${indent}  const collection = await ObjectRegistry.getCollection('${capitalize(objectName)}', {
-${indent}    persistence: { type: 'sql', url: process.env.DATABASE_URL || ':memory:' },
+${indent}    persistence: { type: process.env.DATABASE_TYPE || 'sqlite', url: process.env.DATABASE_URL || ':memory:' },
 ${indent}    ai: aiConfig
 ${indent}  });
 
@@ -857,7 +1057,7 @@ ${indent}  }
 
 ${indent}  await toDelete.delete();
 
-${indent}  return { content: [{ type: 'text', text: JSON.stringify({ success: true, message: 'Object deleted successfully' }) }] };
+${indent}  return successResult({ success: true, message: 'Object deleted successfully' });
 ${indent}}`;
 				default: {
 					const matched = Array.from(ObjectRegistry.getAllClasses().entries()).find(([key, info]) => (info.name || key).toLowerCase() === objectName.toLowerCase());
@@ -878,7 +1078,7 @@ ${indent}    throw new Error('Custom action ${action} is collection-scoped and d
 ${indent}  }
 
 ${indent}  const collection = await ObjectRegistry.getCollection(${JSON.stringify(registeredName)}, {
-${indent}    persistence: { type: 'sql', url: process.env.DATABASE_URL || ':memory:' },
+${indent}    persistence: { type: process.env.DATABASE_TYPE || 'sqlite', url: process.env.DATABASE_URL || ':memory:' },
 ${indent}    ai: aiConfig
 ${indent}  });
 
@@ -900,14 +1100,15 @@ ${indent}  const methodArgs = ${methodArgs.startsWith("[") ? methodArgs : `[${me
 ${indent}  const result = await actionMethod.call(target, ...methodArgs);
 ${indent}  const failure = normalizeCustomActionFailure(result);
 ${indent}  if (failure) {
-${indent}    return {
-${indent}      content: [{ type: 'text', text: JSON.stringify({ error: failure }) }],
-${indent}      isError: true,
-${indent}      _meta: { [SMRT_CUSTOM_ACTION_ERROR_METADATA_KEY]: failure },
-${indent}    };
+${indent}    return errorResult(
+${indent}      { error: failure },
+${indent}      JSON.stringify({ error: failure }),
+${indent}      { [SMRT_CUSTOM_ACTION_ERROR_METADATA_KEY]: failure },
+${indent}    );
 ${indent}  }
 
-${indent}  return { content: [{ type: 'text', text: JSON.stringify(toPublicResult(result)) }] };
+${indent}  const publicResult = toPublicResult(result);
+${indent}  return successResult({ data: publicResult }, JSON.stringify(publicResult));
 ${indent}}`;
 				}
 			}
@@ -917,7 +1118,9 @@ ${indent}}`;
 	* Generate handlers file for modular server
 	*/
 	async generateHandlersFile(tenantScopedObjects = []) {
-		const switchCases = await this.generateToolSwitchCases("        ");
+		const tools = await this.generateTools();
+		const switchCases = await this.generateToolSwitchCases("        ", tools);
+		const stiTargets = this.runtimeStiTargets(tools);
 		const tenantScopedSet = Array.from(new Set(tenantScopedObjects.map((n) => n.toLowerCase())));
 		const hasTenantScoped = tenantScopedSet.length > 0;
 		return `/**
@@ -950,6 +1153,7 @@ const PUBLIC_JSON_OPTIONS = {
     .map((permission) => permission.trim())
     .filter(Boolean),
 };
+const STI_TARGETS: Record<string, Record<string, string>> = ${JSON.stringify(stiTargets)};
 
 /**
  * Mass-assignment guard (#1540): strip framework/server-managed and
@@ -984,6 +1188,23 @@ function applyWritablePolicy(objectName: string, data: any): Record<string, any>
   return result;
 }
 
+/** Resolve an advertised STI discriminator to its registered subtype collection. */
+async function resolveCreateTarget(baseObjectName: string, args: Record<string, any>, aiConfig: any) {
+  let objectName = baseObjectName;
+  const discriminator = args._meta_type;
+  const targets = STI_TARGETS[baseObjectName];
+  if (typeof discriminator === 'string' && targets) {
+    const target = targets[discriminator];
+    if (!target) throw new Error('Unknown STI discriminator: ' + discriminator);
+    objectName = target;
+  }
+  const collection = await ObjectRegistry.getCollection(objectName, {
+    persistence: { type: process.env.DATABASE_TYPE || 'sqlite', url: process.env.DATABASE_URL || ':memory:' },
+    ai: aiConfig,
+  });
+  return { collection, objectName };
+}
+
 /**
  * Sensitive-field-safe serialization for custom-action results (#1540).
  * Recurses through arrays and plain objects so nested SmrtObjects are stripped
@@ -1008,6 +1229,22 @@ function toPublicResult(value: any, seen: WeakSet<object> = new WeakSet()): any
   return out;
 }
 
+function successResult(structuredContent: any, text = JSON.stringify(structuredContent)) {
+  return {
+    content: [{ type: 'text', text }],
+    structuredContent,
+  };
+}
+
+function errorResult(structuredContent: any, text: string, _meta?: Record<string, any>) {
+  return {
+    content: [{ type: 'text', text }],
+    isError: true,
+    structuredContent,
+    ...(_meta ? { _meta } : {}),
+  };
+}
+
 /**
  * Handle tool call request
  */
@@ -1043,15 +1280,10 @@ ${hasTenantScoped ? `
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : 'Unknown error';
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: \`Error executing tool \${name}: \${errorMessage}\`,
-        },
-      ],
-      isError: true,
-    };
+    return errorResult(
+      { error: { message: errorMessage } },
+      \`Error executing tool \${name}: \${errorMessage}\`,
+    );
   }
 }
 `;
@@ -1059,7 +1291,7 @@ ${hasTenantScoped ? `
 	/**
 	* Generate modular index file (main entry point)
 	*/
-	generateModularIndex() {
+	generateModularIndex(toolListCacheHint) {
 		return `#!/usr/bin/env node
 /**
  * Auto-generated MCP Server
@@ -1070,7 +1302,10 @@ ${hasTenantScoped ? `
 
 import { Server } from '@modelcontextprotocol/server';
 import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { ObjectRegistry } from '@happyvertical/smrt-core';
 import { loadConfig } from '@happyvertical/smrt-config';
 import { getDatabase } from '@happyvertical/sql';
 import { getAI } from '@happyvertical/ai';
@@ -1079,6 +1314,8 @@ import { SERVER_NAME, SERVER_VERSION, DEBUG } from './config.js';
 import { tools } from './tools/index.js';
 import { handleToolCall } from './handlers/index.js';
 
+const TOOL_LIST_CACHE_HINT = ${JSON.stringify(toolListCacheHint)};
+
 /**
  * Main server startup function
  */
@@ -1088,6 +1325,17 @@ export async function createServer() {
       console.error(\`[MCP] Available tools:\`, tools.map(t => t.name).join(', '));
     }
 
+    // Register the application package manifest before resolving generated
+    // object names. Generated servers are commonly run from the application
+    // package itself, which is not a node_modules dependency of its process.
+    const localManifestPaths = [
+      resolve(process.cwd(), 'dist', 'manifest.json'),
+      resolve(process.cwd(), '.smrt', 'manifest.json'),
+    ].filter(existsSync);
+    if (localManifestPaths.length > 0) {
+      ObjectRegistry.loadAllManifests({ manifestPaths: localManifestPaths });
+    }
+
     // Load configuration from environment and .smrt.config files
     const appConfig = await loadConfig();
     const aiConfig = appConfig?.ai || {};
@@ -1102,6 +1350,9 @@ export async function createServer() {
         capabilities: {
           tools: {},
         },
+        cacheHints: {
+          'tools/list': TOOL_LIST_CACHE_HINT,
+        },
       }
     );
 
@@ -1112,10 +1363,11 @@ export async function createServer() {
       }
 
       return {
-        tools: tools.map(tool => ({
+        tools: [...tools].sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0).map(tool => ({
           name: tool.name,
           description: tool.description,
           inputSchema: tool.inputSchema,
+          outputSchema: tool.outputSchema,
         })),
       };
     });
@@ -1163,6 +1415,6 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
 	}
 };
 //#endregion
-export { MCPGenerator };
+export { MCPGenerator, MCP_STABLE_CATALOG_TTL_MS, resolveMCPToolListCacheHint, sortMCPTools };
 
 //# sourceMappingURL=mcp.js.map