@happyvertical/smrt-core 0.51.36 → 0.51.38

package/dist/generators/mcp.js

@@ -5,8 +5,9 @@ import { ObjectRegistry } from "../registry.js";
 import { SmrtCollection } from "../collection.js";
 import { generatedSiblingExtension, renderGeneratedSource, resolveGeneratedSourceLanguage } from "./mcp-emit.js";
 import { generateClaudeConfig, generateMCPDocumentation, generateMCPScript, generateRuntimeBootstrap } from "./mcp-runtime-template.js";
+import { canonicalMcpToolNames } from "./mcp-tool-name.js";
 import { runWithTenantGate } from "./tenant-gate.js";
-import { buildToolInputSchema, fieldTypeToJsonSchema, finalizeMcpJsonSchema, isCrudAction } from "./tool-schema.js";
+import { assertMcpJsonSchemaSafety, buildToolInputSchema, fieldTypeToJsonSchema, finalizeMcpJsonSchema, isCrudAction, resolveToolSemantics } from "./tool-schema.js";
 import { dirname, resolve } from "node:path";
 import { mkdir, writeFile } from "node:fs/promises";
 //#region src/generators/mcp.ts
@@ -45,6 +46,20 @@ function resolveMCPToolListCacheHint(options, hasTenantScopedTools) {
 		cacheScope: !hasTenantScopedTools && options?.cacheScope === "public" && options.publicCatalog === true ? "public" : "private"
 	};
 }
+/** Map a canonical effect classification into inert MCP capability hints. */
+function mcpToolAnnotations(action, customAction) {
+	const semantics = resolveToolSemantics(action, customAction);
+	return mcpToolAnnotationsFor(semantics.effect, semantics.idempotent, semantics.openWorld);
+}
+/** Map an explicitly declared canonical classification into inert MCP hints. */
+function mcpToolAnnotationsFor(effect, idempotent, openWorld) {
+	return {
+		readOnlyHint: effect === "read",
+		destructiveHint: effect === "destructive",
+		idempotentHint: idempotent,
+		openWorldHint: openWorld
+	};
+}
 /** 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);
@@ -104,6 +119,24 @@ function buildTaskActionInvocationArgs(metadata, args) {
 * Generate MCP server from smrt objects
 */
 var MCPGenerator = class {
+	toolTargets = /* @__PURE__ */ new WeakMap();
+	toolTarget(tool) {
+		const target = this.toolTargets.get(tool);
+		if (!target) throw new Error(`Missing MCP tool target: ${tool.name}`);
+		return target;
+	}
+	/** Return the validated source identity for a tool returned by this generator. */
+	getToolIdentity(tool) {
+		const target = this.toolTarget(tool);
+		return {
+			objectName: target.objectName,
+			action: target.action,
+			originalName: target.originalName ?? tool.name
+		};
+	}
+	runtimeToolTargets(tools) {
+		return Object.fromEntries(tools.map((tool) => [tool.name, this.toolTarget(tool)]));
+	}
 	config;
 	context;
 	collections = /* @__PURE__ */ new Map();
@@ -153,6 +186,13 @@ var MCPGenerator = class {
 			const objectTools = await this.generateObjectTools(simpleName, shouldInclude);
 			tools.push(...objectTools);
 		}
+		const names = canonicalMcpToolNames(tools.map((tool) => ({
+			name: tool.name,
+			target: this.toolTarget(tool)
+		})));
+		tools.forEach((tool, index) => {
+			tool.name = names[index];
+		});
 		return sortMCPTools(tools);
 	}
 	/**
@@ -167,31 +207,36 @@ var MCPGenerator = class {
 			name: `${lowerName}_list`,
 			description: `List ${objectName} objects with optional filtering`,
 			inputSchema: this.buildInputSchema(objectName, "list", fields),
-			outputSchema: this.buildOutputSchema(objectName, "list", fields)
+			outputSchema: this.buildOutputSchema(objectName, "list", fields),
+			annotations: mcpToolAnnotations("list")
 		});
 		if (shouldInclude("get")) tools.push({
 			name: `${lowerName}_get`,
 			description: `Get a specific ${objectName} by ID or slug`,
 			inputSchema: this.buildInputSchema(objectName, "get", fields),
-			outputSchema: this.buildOutputSchema(objectName, "get", fields)
+			outputSchema: this.buildOutputSchema(objectName, "get", fields),
+			annotations: mcpToolAnnotations("get")
 		});
 		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)
+			outputSchema: this.buildOutputSchema(objectName, "create", fields),
+			annotations: mcpToolAnnotations("create")
 		});
 		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)
+			outputSchema: this.buildOutputSchema(objectName, "update", fields),
+			annotations: mcpToolAnnotations("update")
 		});
 		if (shouldInclude("delete")) tools.push({
 			name: `${lowerName}_delete`,
 			description: `Delete a ${objectName} by ID`,
 			inputSchema: this.buildInputSchema(objectName, "delete", fields),
-			outputSchema: this.buildOutputSchema(objectName, "delete", fields)
+			outputSchema: this.buildOutputSchema(objectName, "delete", fields),
+			annotations: mcpToolAnnotations("delete")
 		});
 		if (classInfo) {
 			const mcpConfig = ObjectRegistry.getConfig(objectName).mcp;
@@ -234,6 +279,11 @@ var MCPGenerator = class {
 				tools.push(tool);
 			}
 		}
+		for (const tool of tools) this.toolTargets.set(tool, {
+			objectName,
+			action: tool.name.slice(lowerName.length + 1),
+			originalName: tool.name
+		});
 		return tools;
 	}
 	buildCustomActionTool(objectName, lowerName, methodName, methodDef, collectionReceiver = false) {
@@ -242,7 +292,8 @@ var MCPGenerator = class {
 			name: `${lowerName}_${methodName}`.toLowerCase(),
 			description: `Execute ${methodName} action on ${objectName}`,
 			inputSchema: this.buildInputSchema(objectName, methodName, ObjectRegistry.getFields(objectName), metadata),
-			outputSchema: this.buildOutputSchema(objectName, methodName, ObjectRegistry.getFields(objectName))
+			outputSchema: this.buildOutputSchema(objectName, methodName, ObjectRegistry.getFields(objectName)),
+			annotations: mcpToolAnnotations(methodName, metadata)
 		};
 	}
 	resolveCustomActionMetadata(objectName, action, method, collectionReceiver = false) {
@@ -457,11 +508,9 @@ var MCPGenerator = class {
 	async handleToolCall(request) {
 		const { name, arguments: args } = request.params;
 		try {
-			if (!(await this.generateTools()).some((t) => t.name === name)) throw new Error(`Unknown tool: ${name}`);
-			const firstUnderscore = name.indexOf("_");
-			const objectName = firstUnderscore === -1 ? "" : name.slice(0, firstUnderscore);
-			const action = firstUnderscore === -1 ? "" : name.slice(firstUnderscore + 1);
-			if (!objectName || !action) throw new Error(`Invalid tool name format: ${name}`);
+			const tool = (await this.generateTools()).find((candidate) => candidate.name === name);
+			if (!tool) throw new Error(`Unknown tool: ${name}`);
+			const { objectName, action } = this.toolTarget(tool);
 			const registeredClasses = ObjectRegistry.getAllClasses();
 			let classInfo = null;
 			let actualObjectName = "";
@@ -536,10 +585,10 @@ var MCPGenerator = class {
 		};
 	}
 	async resolveTaskAction(toolName, args) {
-		const separator = toolName.indexOf("_");
-		if (separator <= 0) return null;
-		const objectPrefix = toolName.slice(0, separator);
-		const action = toolName.slice(separator + 1);
+		const tools = await this.generateTools();
+		const tool = tools.find((candidate) => candidate.name === toolName);
+		if (!tool) return null;
+		const { objectName: objectPrefix, action } = this.toolTarget(tool);
 		if (isCrudToolAction(action)) return null;
 		const classEntry = Array.from(ObjectRegistry.getAllClasses().entries()).find(([key, info]) => (info.name || key).toLowerCase() === objectPrefix.toLowerCase());
 		if (!classEntry) return null;
@@ -548,7 +597,7 @@ var MCPGenerator = class {
 		const mcpConfig = ObjectRegistry.getConfig(objectName).mcp;
 		const configuredTasks = typeof mcpConfig === "object" ? mcpConfig.tasks : void 0;
 		if (configuredTasks !== true && (!Array.isArray(configuredTasks) || !configuredTasks.some((method) => method.toLowerCase() === action.toLowerCase()))) return null;
-		if (!(await this.generateTools()).some((tool) => tool.name === toolName)) return null;
+		if (!tools.some((tool) => tool.name === toolName)) return null;
 		const [resolvedMethodName, method] = resolveCustomActionMethod(await ObjectRegistry.getAllMethods(objectName), action);
 		const methodName = method ? resolvedMethodName : resolveRuntimeMethodName(classInfo.constructor, action);
 		const metadata = this.resolveCustomActionMetadata(objectName, methodName, method, this.hasCollectionReceiver(classInfo));
@@ -712,7 +761,7 @@ var MCPGenerator = class {
 		if (typeof isTenantScopedClass !== "function") return [];
 		const scoped = /* @__PURE__ */ new Set();
 		for (const tool of tools) {
-			const [objectName] = tool.name.split("_");
+			const { objectName } = this.toolTarget(tool);
 			if (!objectName) continue;
 			for (const [key, info] of ObjectRegistry.getAllClasses()) {
 				const simpleName = info.name || key;
@@ -735,7 +784,7 @@ var MCPGenerator = class {
 	async hasTenantScopedTools(tools) {
 		if ((await this.tenantScopedObjectNames(tools)).length > 0) return true;
 		for (const tool of tools) {
-			const [objectName] = tool.name.split("_");
+			const { objectName } = this.toolTarget(tool);
 			if (!objectName) continue;
 			for (const [key, info] of ObjectRegistry.getAllClasses()) {
 				const simpleName = info.name || key;
@@ -915,6 +964,7 @@ var MCPGenerator = class {
 				context: this.context,
 				debug,
 				tools,
+				toolTargets: this.runtimeToolTargets(tools),
 				customActions: await this.runtimeCustomActions(tools),
 				taskActions: await this.runtimeTaskActions(tools),
 				tenantScopedObjects,
@@ -944,10 +994,9 @@ var MCPGenerator = class {
 		const metadata = {};
 		const classes = ObjectRegistry.getAllClasses();
 		for (const tool of tools) {
-			const separator = tool.name.indexOf("_");
-			if (separator === -1) continue;
-			const objectPrefix = tool.name.slice(0, separator);
-			const action = tool.name.slice(separator + 1);
+			const target = this.toolTarget(tool);
+			const objectPrefix = target.objectName.toLowerCase();
+			const action = target.action;
 			if (isCrudToolAction(action)) continue;
 			const matched = Array.from(classes.entries()).find(([key, info]) => (info.name || key).toLowerCase() === objectPrefix);
 			if (!matched) continue;
@@ -974,9 +1023,7 @@ var MCPGenerator = class {
 		const classes = ObjectRegistry.getAllClasses();
 		for (const tool of tools) {
 			if (!await this.supportsTaskTool(tool.name)) continue;
-			const separator = tool.name.indexOf("_");
-			if (separator <= 0) continue;
-			const objectPrefix = tool.name.slice(0, separator).toLowerCase();
+			const objectPrefix = this.toolTarget(tool).objectName.toLowerCase();
 			const matched = Array.from(classes.entries()).find(([key, info]) => (info.name || key).toLowerCase() === objectPrefix);
 			if (!matched) continue;
 			const [key, classInfo] = matched;
@@ -1020,9 +1067,9 @@ var MCPGenerator = class {
 		const orderings = {};
 		const classes = ObjectRegistry.getAllClasses();
 		for (const tool of tools) {
-			const separator = tool.name.indexOf("_");
-			if (separator === -1 || tool.name.slice(separator + 1) !== "list") continue;
-			const objectPrefix = tool.name.slice(0, separator);
+			const target = this.toolTarget(tool);
+			if (target.action !== "list") continue;
+			const objectPrefix = target.objectName.toLowerCase();
 			if (orderings[objectPrefix]) continue;
 			const matched = Array.from(classes.entries()).find(([key, info]) => (info.name || key).toLowerCase() === objectPrefix);
 			if (!matched) continue;
@@ -1034,9 +1081,9 @@ var MCPGenerator = class {
 		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 target = this.toolTarget(tool);
+			if (target.action !== "create") continue;
+			const objectPrefix = target.objectName.toLowerCase();
 			const matched = Array.from(classes.entries()).find(([key, info]) => (info.name || key).toLowerCase() === objectPrefix);
 			if (!matched) continue;
 			const [key, classInfo] = matched;
@@ -1113,6 +1160,15 @@ export const tools: Array<{
   description: string;
   inputSchema: any;
   outputSchema: any;
+  annotations?: {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+  };
+  title?: string;
+  icons?: Array<{ src: string; mimeType?: string; sizes?: string[]; theme?: 'light' | 'dark' }>;
+  _meta?: Record<string, unknown>;
 }> = ${JSON.stringify(tools, null, 2)};
 `;
 	}
@@ -1121,18 +1177,17 @@ export const tools: Array<{
 	*/
 	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("_");
-			const objectName = tool.name.slice(0, separator);
-			const action = tool.name.slice(separator + 1);
+			const target = this.toolTarget(tool);
+			const objectName = target.objectName.toLowerCase();
+			const action = target.action;
 			switch (action) {
 				case "list": return `${indent}case '${tool.name}': {
 ${indent}  const limit = args.limit ?? 50;
 ${indent}  const offset = args.offset ?? 0;
 ${indent}  const where = args.where ?? {};
 
-${indent}  const collection = await ObjectRegistry.getCollection('${capitalize(objectName)}', {
+${indent}  const collection = await ObjectRegistry.getCollection(${JSON.stringify(target.objectName)}, {
 ${indent}    persistence: { type: process.env.DATABASE_TYPE || 'sqlite', url: process.env.DATABASE_URL || ':memory:' },
 ${indent}    ai: aiConfig
 ${indent}  });
@@ -1150,7 +1205,7 @@ ${indent}  if (!args.id && !args.slug) {
 ${indent}    throw new Error('Either id or slug is required');
 ${indent}  }
 
-${indent}  const collection = await ObjectRegistry.getCollection('${capitalize(objectName)}', {
+${indent}  const collection = await ObjectRegistry.getCollection(${JSON.stringify(target.objectName)}, {
 ${indent}    persistence: { type: process.env.DATABASE_TYPE || 'sqlite', url: process.env.DATABASE_URL || ':memory:' },
 ${indent}    ai: aiConfig
 ${indent}  });
@@ -1165,7 +1220,7 @@ ${indent}  }
 ${indent}  return successResult(item.toPublicJSON(PUBLIC_JSON_OPTIONS));
 ${indent}}`;
 				case "create": return `${indent}case '${tool.name}': {
-${indent}  const { collection, objectName: targetObjectName } = await resolveCreateTarget('${objectName}', args, aiConfig);
+${indent}  const { collection, objectName: targetObjectName } = await resolveCreateTarget(${JSON.stringify(objectName)}, args, aiConfig);
 
 ${indent}  const newItem = await collection.create(applyWritablePolicy(targetObjectName, args));
 ${indent}  await newItem.save();
@@ -1178,7 +1233,7 @@ ${indent}  if (!id) {
 ${indent}    throw new Error('ID is required for update');
 ${indent}  }
 
-${indent}  const collection = await ObjectRegistry.getCollection('${capitalize(objectName)}', {
+${indent}  const collection = await ObjectRegistry.getCollection(${JSON.stringify(target.objectName)}, {
 ${indent}    persistence: { type: process.env.DATABASE_TYPE || 'sqlite', url: process.env.DATABASE_URL || ':memory:' },
 ${indent}    ai: aiConfig
 ${indent}  });
@@ -1188,7 +1243,7 @@ ${indent}  if (!existing) {
 ${indent}    throw new Error('Object not found');
 ${indent}  }
 
-${indent}  Object.assign(existing, applyWritablePolicy('${capitalize(objectName)}', updateData));
+${indent}  Object.assign(existing, applyWritablePolicy(${JSON.stringify(target.objectName)}, updateData));
 ${indent}  await existing.save();
 
 ${indent}  return successResult(existing.toPublicJSON(PUBLIC_JSON_OPTIONS));
@@ -1198,7 +1253,7 @@ ${indent}  if (!args.id) {
 ${indent}    throw new Error('ID is required for delete');
 ${indent}  }
 
-${indent}  const collection = await ObjectRegistry.getCollection('${capitalize(objectName)}', {
+${indent}  const collection = await ObjectRegistry.getCollection(${JSON.stringify(target.objectName)}, {
 ${indent}    persistence: { type: process.env.DATABASE_TYPE || 'sqlite', url: process.env.DATABASE_URL || ':memory:' },
 ${indent}    ai: aiConfig
 ${indent}  });
@@ -1224,10 +1279,10 @@ ${indent}}`;
 ${indent}  const { id, options, ...directArgs } = args;
 
 ${indent}  if (${JSON.stringify(metadata.scope)} === 'item' && !id) {
-${indent}    throw new Error('ID is required for custom action ${action}');
+${indent}    throw new Error(${JSON.stringify(`ID is required for custom action ${action}`)});
 ${indent}  }
 ${indent}  if (${JSON.stringify(metadata.scope)} === 'collection' && id) {
-${indent}    throw new Error('Custom action ${action} is collection-scoped and does not accept an ID');
+${indent}    throw new Error(${JSON.stringify(`Custom action ${action} is collection-scoped and does not accept an ID`)});
 ${indent}  }
 
 ${indent}  const collection = await ObjectRegistry.getCollection(${JSON.stringify(registeredName)}, {
@@ -1246,7 +1301,7 @@ ${indent}  }
 
 ${indent}  const actionMethod = target[${JSON.stringify(methodName)}];
 ${indent}  if (typeof actionMethod !== 'function') {
-${indent}    throw new Error('Method ${methodName} not found on custom action target');
+${indent}    throw new Error(${JSON.stringify(`Method ${methodName} not found on custom action target`)});
 ${indent}  }
 
 ${indent}  const methodArgs = ${methodArgs.startsWith("[") ? methodArgs : `[${methodArgs}]`};
@@ -1274,6 +1329,7 @@ ${indent}}`;
 		const tools = await this.generateTools();
 		const switchCases = await this.generateToolSwitchCases("        ", tools);
 		const stiTargets = this.runtimeStiTargets(tools);
+		const toolTargets = this.runtimeToolTargets(tools);
 		const tenantScopedSet = Array.from(new Set(tenantScopedObjects.map((n) => n.toLowerCase())));
 		const hasTenantScoped = tenantScopedSet.length > 0;
 		return `/**
@@ -1301,6 +1357,7 @@ const MCP_TENANT_ID = process.env.SMRT_MCP_TENANT_ID || undefined;
 const MCP_ALLOW_CROSS_TENANT = process.env.SMRT_MCP_ALLOW_CROSS_TENANT === 'true';
 ` : ""}
 
+const TOOL_TARGETS: Record<string, { objectName: string; action: string }> = ${JSON.stringify(toolTargets)};
 const PUBLIC_JSON_OPTIONS = {
   permissions: (process.env.SMRT_MCP_PERMISSIONS || '')
     .split(',')
@@ -1420,7 +1477,7 @@ ${switchCases}
     };
 ${hasTenantScoped ? `
     // Fail-closed tenant context for tenant-scoped tools (#1554).
-    const [toolObject] = name.split('_');
+    const toolObject = TOOL_TARGETS[name]?.objectName;
     const result =
       toolObject && TENANT_SCOPED.has(toolObject.toLowerCase())
         ? await runTenantScopedEntryPoint(
@@ -1518,12 +1575,7 @@ export async function createServer() {
       }
 
       return {
-        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,
-        })),
+        tools: [...tools].sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0),
       };
     });
 
@@ -1570,6 +1622,6 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
 	}
 };
 //#endregion
-export { MCPGenerator, MCP_STABLE_CATALOG_TTL_MS, resolveMCPToolListCacheHint, sortMCPTools };
+export { MCPGenerator, MCP_STABLE_CATALOG_TTL_MS, assertMcpJsonSchemaSafety, mcpToolAnnotations, mcpToolAnnotationsFor, resolveMCPToolListCacheHint, sortMCPTools };
 
 //# sourceMappingURL=mcp.js.map