@enfyra/mcp-server 0.1.6 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "MCP server for Enfyra - manage Enfyra instances from MCP-compatible coding tools",
   "type": "module",
   "license": "MIT",

package/src/lib/mcp-examples.js

@@ -1597,26 +1597,14 @@ ensure_page_extension({
           'Use enfyra_menu.label, not title.',
           'Sensitive admin menus should include a permission condition at creation time.',
           'For page extensions, create the menu first with ensure_menu and pass its id to ensure_page_extension.',
-          'Call get_extension_theme_contract before writing or reviewing page/widget/global extension UI.',
+          'Call get_extension_theme_contract before writing or reviewing page/widget/global extension UI; that tool is the authority for theme, color, layout, modal, drawer, and shell registry details.',
           'Call get_enfyra_required_knowledge before saving extension code, pass globalRulesAckKey as globalRulesAckKey, and pass extensionAckKey as extensionKnowledgeAckKey.',
           'Page extensions must register the app-shell PageHeader with usePageHeaderRegistry instead of rendering a custom top header.',
-          'Use variant: "minimal" for operational pages unless a larger header is intentionally needed.',
-          'Do not put ordinary KPI cards in PageHeader.stats; render metrics in the extension body.',
           'Put page-level actions in useHeaderActionRegistry or useSubHeaderActionRegistry, destructure register first, then call it with one action or an array.',
-          'Page extensions should be full-bleed by default and responsive from the first version.',
-          'The extension root is already inside Enfyra admin page main; do not add root-level page padding.',
-          'Use eApp theme class tokens for panels, rows, badges, borders, controls, radius, and text. Generated extension templates should prefer eapp-surface-*, eapp-text-*, eapp-radius-*, eapp-divide-y, and eapp-primary-* over raw CSS variable utilities.',
-          'Treat primary color as runtime-configurable by the app color picker. For Nuxt UI components, choose color="primary" by semantic intent. For custom extension UI, decide whether each element is neutral surface, runtime-primary identity, or status: regular panels/KPI cards/list rows use eapp-surface-card/eapp-surface-muted/eapp-surface-hover/eapp-divide-y and eapp-text-* classes, while selected/current identity blocks, primary tiles, progress fills, primary icons, and primary CTA fills use eapp-primary-surface, eapp-primary-soft, eapp-primary-subtle, eapp-primary-solid, or eapp-primary-text so the color picker controls them. eapp-primary-surface supplies selected identity color but does not replace card chrome; keep border/radius classes on selected blocks.',
-          'Decision cases: normal decorative accents, feature icons, non-state tiles, active tabs, progress fills, selected segments, and primary actions use runtime primary/identity classes; true semantic states use their matching status colors such as error, warning, success, or info; large ordinary surfaces stay neutral and carry only small badges/icons for status; selected/current entity blocks may use eapp-primary-surface.',
-          'Pattern examples: KPI/metric cards should be eapp-surface-card with a small icon tile using eapp-primary-soft eapp-icon-tile; selected/current entity cards may use eapp-primary-surface; progress bars use eapp-surface-muted tracks plus eapp-primary-solid fills; list rows use eapp-surface-card/eapp-divide-y/eapp-surface-hover and only small chips inside; primary scope actions use UButton color="primary" variant="solid"; secondary actions use neutral variants.',
-          'Status colors belong only in UBadge/UAlert semantic colors or eapp-status-*-soft/text/border classes for badges, small icons, or short status text. Do not read --badge-* variables directly in extension templates. Do not color large panels, alert-like success blocks, KPI cards, list containers, or attention/reconciliation blocks green/yellow/red because of state; keep the block neutral and place the status badge/icon inside.',
-          'Use PageHeader gradient: "none" for generated operational pages unless the user explicitly asks for a decorative page accent; do not hardcode cyan/violet/purple/blue/green gradients.',
-          'For general card grids inside the shell, use md:grid-cols-2 xl:grid-cols-3 instead of lg:grid-cols-3 because the desktop sidebar leaves tablet-width content at 1024px.',
-          'Do not use Nuxt UI neutral semantic classes such as bg-default, text-muted, text-dimmed, border-default, or divide-default inside extension code; use eApp class tokens instead. Do not write text-[var(...)], bg-[var(...)], or border-[var(...)] in generated extension templates unless no class token exists for that exact primitive.',
-          'Do not pass ui.content: "eapp-surface-card" to UModal/CommonModal; modal content uses the app modal surface and caller content classes should only append z-index or width.',
-          'CommonModal and CommonDrawer own action-only footers through cancelAction, primaryAction, dangerAction, leadingActions, and footerHint. Pass action intent through props instead of styling footer buttons manually; cancelAction defaults to neutral outline, dangerAction is for irreversible destructive work, and Keep editing should use tone: "primary" in discard dialogs.',
-          'Use UTabs for page sections instead of custom tab bars so the app-level active/inactive indicators, spacing, focus rings, and theme contrast stay consistent.',
-          'Do not inject global CSS, create theme guards, redefine the app palette, or solve one extension by overriding the whole app shell.',
+          'Page extensions should be full-bleed and responsive from the first version; the extension root is already inside the Enfyra admin page main.',
+          'Render ordinary metrics and lists in the body, not PageHeader.stats, unless the user explicitly wants a compact overview header.',
+          'Use app theme tokens and Nuxt UI semantic colors by intent; do not hard-code concrete palettes or redefine the app palette inside extension code.',
+          'Use app-owned primitives such as UTabs, CommonModal, CommonDrawer, Widget, useMenuNotificationRegistry, and useAccountPanelRegistry when the workflow matches them.',
           'Keep list selection local and fetch detail rows only; do not refetch the whole list after a row click unless the list data changed.',
           'Page extension paths are admin app UI routes. Do not verify them with test_rest_endpoint against ENFYRA_API_URL unless inspect_route shows an API route with the same path.',
           'After saving, open Enfyra admin tabs should update through the server/Enfyra admin UI realtime reload contract; do not tell the user to refresh unless that contract is proven broken.',

package/src/lib/platform-operation-tools.js

@@ -1441,7 +1441,8 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
     'create_api_endpoint',
     [
       'Business operation: create or update a custom REST endpoint with a handler in one safe operation.',
-      'Use this when the user asks for a new route/endpoint/API path that computes or orchestrates behavior, such as GET /sum or POST /webhook.',
+      'Prefer api_endpoint_workflow when route access, role/user permissions, overwrite decisions, or multi-step planning matter.',
+      'Use this one-shot helper only when the endpoint contract is already clear and no authenticated route-permission step is needed in the same operation, such as a simple public webhook or private admin-only utility that will be granted separately.',
       'It creates the route without mainTableId, ensures the method is available, validates sourceCode, creates or overwrites the route handler, optionally makes the method public, reloads routes, and can smoke-test the endpoint.',
       'Use table/schema tools separately when the user needs persisted data. This tool is for custom behavior endpoints.',
     ].join(' '),
@@ -1591,8 +1592,10 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       message: z.string().optional().describe('Custom validation error message.'),
       description: z.string().optional().describe('Admin note.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable the rule.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
-    async ({ tableName, columnName, ruleType, value, message, description, isEnabled }) => {
+    async ({ tableName, columnName, ruleType, value, message, description, isEnabled, globalRulesAckKey }) => {
+      assertGlobalRulesAck(globalRulesAckKey);
       const table = resolveTable(await getMetadataTables(ENFYRA_API_URL), tableName);
       const column = resolveColumn(table, columnName);
       const existing = await findRecord(ENFYRA_API_URL, 'enfyra_column_rule', {
@@ -1632,8 +1635,10 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       condition: z.string().optional().describe('Condition JSON object using field permission DSL.'),
       description: z.string().optional().describe('Admin note.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable the permission.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
-    async ({ tableName, columnName, relationName, action, effect, roleId, roleName, allowedUserIds, condition, description, isEnabled }) => {
+    async ({ tableName, columnName, relationName, action, effect, roleId, roleName, allowedUserIds, condition, description, isEnabled, globalRulesAckKey }) => {
+      assertGlobalRulesAck(globalRulesAckKey);
       if (!!columnName === !!relationName) throw new Error('Provide exactly one of columnName or relationName.');
       assertOneScope({ roleId, roleName, allowedUserIds });
       const [tables, role] = await Promise.all([
@@ -1691,8 +1696,10 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
       description: z.string().optional().describe('Admin note.'),
       rules: z.string().optional().describe('Rules JSON array: [{type, config, priority, isEnabled, description, userIds}].'),
       rulesMode: z.enum(['append', 'replace', 'none']).optional().default('append').describe('append creates rules, replace disables existing rules first, none leaves rules unchanged.'),
+      globalRulesAckKey: globalRulesAckParam(z),
     },
-    async ({ name, guardId, position, routeId, path, methods, combinator, priority, isGlobal, isEnabled, description, rules, rulesMode }) => {
+    async ({ name, guardId, position, routeId, path, methods, combinator, priority, isGlobal, isEnabled, description, rules, rulesMode, globalRulesAckKey }) => {
+      assertGlobalRulesAck(globalRulesAckKey);
       if (path && routeId) throw new Error('Provide path or routeId, not both.');
       const ruleInputs = parseJsonArrayArg('rules', rules, []);
       if (position === 'pre_auth') {

package/src/lib/required-knowledge.js

@@ -49,7 +49,7 @@ export function assertExtensionKnowledgeAckIf(condition, key) {
 export function buildRequiredKnowledgePayload() {
   return {
     version: REQUIRED_KNOWLEDGE_VERSION,
-    purpose: 'Read this before mutating Enfyra metadata, schema, routes, permissions, dynamic server code, or extension UI through MCP.',
+    purpose: 'Read this before mutating Enfyra metadata, schema, routes, permissions, menus, packages, cache state, dynamic server code, or extension UI through MCP.',
     globalRulesAckKey: GLOBAL_RULES_ACK_KEY,
     dynamicCodeAckKey: DYNAMIC_CODE_KNOWLEDGE_ACK_KEY,
     extensionAckKey: EXTENSION_KNOWLEDGE_ACK_KEY,

package/src/lib/table-tools.js

@@ -313,7 +313,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     return withSchemaQueue(async () => {
     const tableData = await fetchTableWithDetails(ENFYRA_API_URL, args.tableId);
     if (!tableData) {
-      return { content: [{ type: 'text', text: `Error: Table with ID ${args.tableId} not found.` }] };
+      throw new Error(`Table with ID ${args.tableId} not found.`);
     }
 
     const existingColumns = getPatchableColumns(tableData.columns);
@@ -325,9 +325,12 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       columnName: args.name,
     });
 
-    return {
-      content: [{ type: 'text', text: `Column "${args.name}" added to table ${args.tableId}.\n\n${JSON.stringify(result, null, 2)}` }],
-    };
+    return jsonContent({
+      action: 'column_created',
+      tableId: args.tableId,
+      columnName: args.name,
+      result,
+    });
     });
   }
 
@@ -341,7 +344,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     const resolvedTargetTableId = resolveTableIdentifierFromMetadata(metadata, targetTableId, 'targetTableId');
     const tableData = await fetchTableWithDetails(ENFYRA_API_URL, resolvedSourceTableId);
     if (!tableData) {
-      return { content: [{ type: 'text', text: `Error: Table ${sourceTableId} not found.` }] };
+      throw new Error(`Table ${sourceTableId} not found.`);
     }
     const existingRelations = (tableData.relations || []).map(sanitizeExistingRelationForTablePatch);
     const beforeIds = existingRelations.map((relation) => String(getId(relation))).filter((id) => id !== 'null');
@@ -356,9 +359,11 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       action: 'create',
       propertyName,
     });
-    return {
-      content: [{ type: 'text', text: `Relation created: ${propertyName} (${type}) from table ${resolvedSourceTableId} → ${resolvedTargetTableId}.\n\nFull result:\n${JSON.stringify(result, null, 2)}` }],
-    };
+    return jsonContent({
+      action: 'relation_created',
+      relation: { propertyName, type, sourceTableId: resolvedSourceTableId, targetTableId: resolvedTargetTableId },
+      result,
+    });
     });
   }
 
@@ -366,7 +371,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     return withSchemaQueue(async () => {
     const tableData = await fetchTableWithDetails(ENFYRA_API_URL, tableId);
     if (!tableData) {
-      return { content: [{ type: 'text', text: `Error: Table with ID ${tableId} not found.` }] };
+      throw new Error(`Table with ID ${tableId} not found.`);
     }
 
     const existingColumns = getPatchableColumns(tableData.columns);
@@ -399,9 +404,12 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       columnId,
     });
 
-    return {
-      content: [{ type: 'text', text: `Column ${columnId} deleted from table ${tableId}.\n\n${JSON.stringify(result, null, 2)}` }],
-    };
+    return jsonContent({
+      action: 'column_deleted',
+      tableId,
+      columnId,
+      result,
+    });
     });
   }
 
@@ -409,7 +417,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     return withSchemaQueue(async () => {
     const tableData = await fetchTableWithDetails(ENFYRA_API_URL, tableId);
     if (!tableData) {
-      return { content: [{ type: 'text', text: `Error: Table with ID ${tableId} not found.` }] };
+      throw new Error(`Table with ID ${tableId} not found.`);
     }
 
     const existingRelations = (tableData.relations || []).map(sanitizeExistingRelationForTablePatch);
@@ -442,9 +450,12 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       relationId,
     });
 
-    return {
-      content: [{ type: 'text', text: `Relation ${relationId} deleted from table ${tableId}.\n\n${JSON.stringify(result, null, 2)}` }],
-    };
+    return jsonContent({
+      action: 'relation_deleted',
+      tableId,
+      relationId,
+      result,
+    });
     });
   }
 
@@ -613,9 +624,25 @@ export function registerTableTools(server, ENFYRA_API_URL) {
         indexes.length ? `Index group(s): ${indexes.length}.` : null,
         uniques.length ? `Unique group(s): ${uniques.length}.` : null,
       ].filter(Boolean).join(' ');
-      return {
-        content: [{ type: 'text', text: `${colHint}\n${relHint}${constraintHint ? `\n${constraintHint}` : ''}\n${restHint}\n\nFull result:\n${JSON.stringify(result, null, 2)}` }],
-      };
+      return jsonContent({
+        action: 'table_created',
+        table: { id: createdTableId, name, routePath },
+        summary: {
+          columnCount: userColumns.length + 1,
+          createdColumnCount: userColumns.length,
+          relationCount: userRelations.length,
+          indexGroupCount: indexes.length,
+          uniqueGroupCount: uniques.length,
+        },
+        rest: {
+          base,
+          routePath,
+          operations: ['GET /<table>', 'POST /<table>', 'PATCH /<table>/:id', 'DELETE /<table>/:id'],
+          noGetById: true,
+        },
+        message: [colHint, relHint, constraintHint, restHint].filter(Boolean).join('\n'),
+        result,
+      });
     })
   );
 
@@ -652,9 +679,11 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       if (uniquesJson !== undefined) body.uniques = normalizeConstraintGroups('uniques', parseJsonArrayParam('uniques', uniquesJson));
 
       const result = await patchTableAutoConfirm(ENFYRA_API_URL, tableId, body);
-      return {
-        content: [{ type: 'text', text: `Table ${tableId} updated.\n\n${JSON.stringify(result, null, 2)}` }],
-      };
+      return jsonContent({
+        action: 'table_updated',
+        tableId,
+        result,
+      });
     })
   );
 
@@ -691,9 +720,11 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       const result = await fetchAPI(ENFYRA_API_URL, `/enfyra_table/${tableId}`, {
         method: 'DELETE',
       });
-      return {
-        content: [{ type: 'text', text: `Table ${tableId} deleted.\n\n${JSON.stringify(result, null, 2)}` }],
-      };
+      return jsonContent({
+        action: 'table_deleted',
+        tableId,
+        result,
+      });
     })
   );
 
@@ -741,7 +772,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       assertGlobalRulesAck(globalRulesAckKey);
       const tableData = await fetchTableWithDetails(ENFYRA_API_URL, tableId);
       if (!tableData) {
-        return { content: [{ type: 'text', text: `Error: Table with ID ${tableId} not found.` }] };
+        throw new Error(`Table with ID ${tableId} not found.`);
       }
 
       const existingColumns = getPatchableColumns(tableData.columns);
@@ -771,9 +802,12 @@ export function registerTableTools(server, ENFYRA_API_URL) {
         columnId,
       });
 
-      return {
-        content: [{ type: 'text', text: `Column ${columnId} updated on table ${tableId}.\n\n${JSON.stringify(result, null, 2)}` }],
-      };
+      return jsonContent({
+        action: 'column_updated',
+        tableId,
+        columnId,
+        result,
+      });
     })
   );
 

package/src/mcp-server-entry.mjs

@@ -331,7 +331,7 @@ function summarizeRoutes(routesResult) {
   }));
 }
 
-function summarizeMetadata(metadata, { search, limit } = {}) {
+function summarizeMetadata(metadata, { search, limit, all = false } = {}) {
   const tables = normalizeTables(metadata);
   const q = search ? search.toLowerCase() : null;
   const summarized = tables.map((table) => ({
@@ -346,11 +346,13 @@ function summarizeMetadata(metadata, { search, limit } = {}) {
   const matched = q
     ? summarized.filter((table) => JSON.stringify(table).toLowerCase().includes(q))
     : summarized;
-  const outputLimit = limit || 30;
+  const outputLimit = all ? matched.length : (limit || 30);
   return {
     tableCount: tables.length,
     matchedTableCount: matched.length,
     returnedTableCount: Math.min(matched.length, outputLimit),
+    complete: all || outputLimit >= matched.length,
+    hardCap: all ? null : outputLimit,
     search: search || null,
     tables: matched.slice(0, outputLimit),
   };
@@ -807,15 +809,21 @@ server.tool('get_all_metadata', 'Get concise metadata summary for all tables. Us
   includeFull: z.boolean().optional().default(false).describe('Return full raw metadata. Default false to keep MCP context small.'),
   search: z.string().optional().describe('Optional table-name/alias substring filter.'),
   limit: z.number().optional().describe('Maximum tables returned after search. Default 30.'),
-}, async ({ includeFull, search, limit }) => {
+  all: z.boolean().optional().default(false).describe('Return every matched table summary. Use when a complete table list is required.'),
+}, async ({ includeFull, search, limit, all }) => {
+  if (all && limit !== undefined) {
+    throw new Error('get_all_metadata accepts either all=true or limit, not both.');
+  }
   const result = await fetchAPI(ENFYRA_API_URL, '/metadata');
   const payload = includeFull
     ? result
     : {
         statusCode: result?.statusCode,
         success: result?.success,
-        ...summarizeMetadata(result, { search, limit }),
-        detailHint: 'Default response is capped and minimal. Call get_table_metadata({ tableName }) or inspect_table({ tableName }) for columns, relations, and route context.',
+        ...summarizeMetadata(result, { search, limit, all }),
+        detailHint: all
+          ? 'Complete summary returned. Call get_table_metadata({ tableName }) or inspect_table({ tableName }) for columns, relations, and route context.'
+          : 'Default response is capped and minimal. Pass all=true for a complete summary, or call get_table_metadata({ tableName }) / inspect_table({ tableName }) for detail.',
       };
   return jsonContent(payload);
 });
@@ -2109,16 +2117,11 @@ server.tool(
     tableName: z.string().describe('Table name or alias to inspect'),
   },
   async ({ tableName }) => {
-    let state = await collectRestDefinitionState();
-    let table = state.tables.find((item) => item?.name === tableName || item?.alias === tableName);
+    const state = await collectRestDefinitionState();
+    const table = state.tables.find((item) => item?.name === tableName || item?.alias === tableName);
     if (!table) {
-      await fetchAPI(ENFYRA_API_URL, '/admin/reload/metadata', { method: 'POST' }).catch(() => {});
-      await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' }).catch(() => {});
-      await new Promise((resolve) => setTimeout(resolve, 150));
-      state = await collectRestDefinitionState();
-      table = state.tables.find((item) => item?.name === tableName || item?.alias === tableName);
+      throw new Error(`Unknown table "${tableName}". Use get_all_tables({ search, limit }) or get_all_metadata({ search, all: true }) to confirm the table name. If a just-created table is missing, verify the create response/reload event before calling manual reload tools.`);
     }
-    if (!table) throw new Error(`Unknown table "${tableName}"`);
     const tableId = getId(table);
     const columnIds = new Set((table.columns || []).map((column) => String(getId(column))));
     const relationIds = new Set((table.relations || []).map((relation) => String(getId(relation))));
@@ -2420,7 +2423,7 @@ server.tool('get_all_routes', 'List route definitions with minimal fields. Every
   const queryParams = new URLSearchParams({
     filter: JSON.stringify(filter),
     fields: 'id,path,mainTable.name,availableMethods.*,publicMethods.*,isEnabled',
-    limit: '1000',
+    limit: all ? '0' : '1000',
   });
   const result = await fetchAPI(ENFYRA_API_URL, `/enfyra_route?${queryParams.toString()}`);
   const q = search ? search.toLowerCase() : null;
@@ -2439,6 +2442,8 @@ server.tool('get_all_routes', 'List route definitions with minimal fields. Every
     matchedRouteCount: matchedRoutes.length,
     returnedRouteCount: Math.min(matchedRoutes.length, routeLimit),
     all: !!all,
+    complete: all || routeLimit >= matchedRoutes.length,
+    hardCap: all ? null : routeLimit,
     search: search || null,
     routes: matchedRoutes.slice(0, routeLimit),
     detailHint: matchedRoutes.length > routeLimit
@@ -2885,7 +2890,7 @@ server.tool('reload_all', 'Reload all caches (metadata, routes, GraphQL)', {
 }, async ({ globalRulesAckKey }) => {
   assertGlobalRulesAck(globalRulesAckKey);
   const result = await fetchAPI(ENFYRA_API_URL, '/admin/reload', { method: 'POST' });
-  return { content: [{ type: 'text', text: `System reloaded:\n${JSON.stringify(result, null, 2)}` }] };
+  return jsonContent({ action: 'reloaded_all', result });
 });
 
 server.tool('reload_metadata', 'Reload metadata cache only', {
@@ -2893,7 +2898,7 @@ server.tool('reload_metadata', 'Reload metadata cache only', {
 }, async ({ globalRulesAckKey }) => {
   assertGlobalRulesAck(globalRulesAckKey);
   const result = await fetchAPI(ENFYRA_API_URL, '/admin/reload/metadata', { method: 'POST' });
-  return { content: [{ type: 'text', text: `Metadata reloaded:\n${JSON.stringify(result, null, 2)}` }] };
+  return jsonContent({ action: 'reloaded_metadata', result });
 });
 
 server.tool('reload_routes', 'Reload routes cache only', {
@@ -2901,7 +2906,7 @@ server.tool('reload_routes', 'Reload routes cache only', {
 }, async ({ globalRulesAckKey }) => {
   assertGlobalRulesAck(globalRulesAckKey);
   const result = await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' });
-  return { content: [{ type: 'text', text: `Routes reloaded:\n${JSON.stringify(result, null, 2)}` }] };
+  return jsonContent({ action: 'reloaded_routes', result });
 });
 
 server.tool('reload_graphql', 'Reload GraphQL schema', {
@@ -2909,7 +2914,7 @@ server.tool('reload_graphql', 'Reload GraphQL schema', {
 }, async ({ globalRulesAckKey }) => {
   assertGlobalRulesAck(globalRulesAckKey);
   const result = await fetchAPI(ENFYRA_API_URL, '/admin/reload/graphql', { method: 'POST' });
-  return { content: [{ type: 'text', text: `GraphQL reloaded:\n${JSON.stringify(result, null, 2)}` }] };
+  return jsonContent({ action: 'reloaded_graphql', result });
 });
 
 // ============================================================================
@@ -3080,12 +3085,15 @@ server.tool(
     const checkFilter = JSON.stringify({ name: { _eq: name }, type: { _eq: type } });
     const existing = await fetchAPI(ENFYRA_API_URL, `/enfyra_package?filter=${encodeURIComponent(checkFilter)}&limit=1`);
     if (existing.data && existing.data.length > 0) {
-      return {
-        content: [{
-          type: 'text',
-          text: `Package "${name}" is already installed (version: ${existing.data[0].version}, type: ${existing.data[0].type}).\n${JSON.stringify(existing.data[0], null, 2)}`,
-        }],
-      };
+      return jsonContent({
+        action: 'package_already_installed',
+        package: {
+          name,
+          version: existing.data[0].version,
+          type: existing.data[0].type,
+        },
+        record: existing.data[0],
+      });
     }
 
     // Step 3: Get current user for installedBy
@@ -3107,12 +3115,11 @@ server.tool(
       body: JSON.stringify(body),
     });
 
-    return {
-      content: [{
-        type: 'text',
-        text: `Package "${name}@${pkgVersion}" installed successfully (type: ${type}).\n${JSON.stringify(result, null, 2)}`,
-      }],
-    };
+    return jsonContent({
+      action: 'package_installed',
+      package: { name, version: pkgVersion, type },
+      result,
+    });
   },
 );