@enfyra/mcp-server 0.0.56 → 0.0.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.0.56",
+  "version": "0.0.58",
   "description": "MCP server for Enfyra - manage your Enfyra instance via Claude Code",
   "type": "module",
   "license": "MIT",

package/src/lib/mcp-examples.js

@@ -203,10 +203,21 @@ create_column({
   defaultValue: "pending",
   isPublished: true,
   description: "Email verification state controlled by server hooks."
+})
+
+create_column({
+  tableId: "<project_env_table_id>",
+  name: "value",
+  type: "text",
+  isNullable: false,
+  isPublished: false,
+  isEncrypted: true,
+  description: "Encrypted environment value."
 })`,
         notes: [
           'Run schema-changing calls sequentially. Do not parallelize create_column calls.',
           'create_column fetches table_definition and patches only real persisted columns with id/_id; generated metadata projections such as createdAt, updatedAt, or relation FK display fields are skipped.',
+          'Use isEncrypted=true for encryption at rest. Add isUpdatable=false separately only when the field should be immutable.',
           'Use hooks or field permissions to prevent clients from updating server-owned fields.',
         ],
       },
@@ -361,7 +372,7 @@ if (value && value.slice(0, 7) !== "enc:v1:") {
           'Do not call raw create_record with a code field for pre_hook_definition or post_hook_definition; backend CRUD rejects code.',
           'Use Enfyra pre-hooks for request-body normalization before canonical CRUD persists the record.',
           'Do not implement encrypted field normalization as a Knex/database hook.',
-          'Use $encrypt for encryption and $ssh.generateKeyPair for SSH key generation; do not use $secrets.',
+          'Use isEncrypted columns for database encryption and $helpers.$crypto.generateSshKeyPair for SSH key generation; do not use $helpers.$ssh or $helpers.$secrets.',
         ],
       },
       {

package/src/lib/mcp-instructions.js

@@ -139,8 +139,8 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '### Dynamic script syntax preference',
     '- When writing server-side Enfyra scripts, prefer template macros over raw `$ctx` access: use `@BODY`, `@QUERY`, `@PARAMS`, `@USER`, `@REPOS`, `@HELPERS`, `@SOCKET`, `@TRIGGER`, `@DATA`, `@ERROR`, and `@THROW400`–`@THROW503`.',
     '- Use Enfyra native throw helpers for intentional errors: `@THROW400("message")`, `@THROW403()`, `@THROW404("resource", id)`, or `$ctx.$throw[400]("message")`. Do not generate `throw new Error(...)` for user/domain errors in handlers, hooks, flows, websocket events, OAuth scripts, or admin-generated scripts.',
-    '- For encrypted persisted fields such as `*_encrypted`, use an Enfyra route pre-hook, not a Knex/database hook. Mutate the body before persistence: `const value = @BODY.field_encrypted; if (value && value.slice(0, 7) !== "enc:v1:") @BODY.field_encrypted = @HELPERS.$encrypt.encrypt(value);`.',
-    '- ASV exposes `$helpers.$encrypt.encrypt/decrypt` for encrypted strings and `$helpers.$ssh.generateKeyPair` for SSH keys. Do not generate `$helpers.$secrets` usage.',
+    '- For regular app data that must be encrypted at rest, create the column with `isEncrypted=true`; Enfyra database-query hooks will encrypt on insert/update and decrypt after select. `isEncrypted` does not imply immutability; use `isUpdatable=false` separately only when the field itself must be immutable. Do not filter or sort on encrypted fields. Legacy Cloud control-plane fields named `*_encrypted` may still use route pre-hooks until migrated.',
+    '- Enfyra scripts use `$helpers.$crypto` for bounded crypto helpers such as `randomUUID()`, `randomBytes(size, encoding)`, `sha256(value, encoding)`, `hmacSha256(value, secret, encoding)`, and `generateSshKeyPair(comment)`. Do not generate legacy `$helpers.$ssh` or `$helpers.$secrets` usage.',
     '- Script-backed records use one shared persistence contract: `sourceCode` is the editable source, `scriptLanguage` controls compilation, and `compiledCode` is generated by the server from `sourceCode`. Do not hand-edit or send stale `compiledCode` from generated tools; save `sourceCode`/`scriptLanguage` through `PATCH /<script_table>/<id>` and let the server persist generated `compiledCode` internally. Public metadata may mark `compiledCode` non-updatable, but the server engine must still preserve the generated value after normalization.',
     '- For route handlers specifically, the field is also `sourceCode`. Older names such as `logic` are wrong for current Enfyra REST CRUD and will be rejected. Use MCP `create_handler` so it writes `sourceCode` and resolves method ids correctly.',
     '- MCP `create_pre_hook` and `create_post_hook` accept a user-facing `code` argument but persist it as `sourceCode` with `scriptLanguage`. Do not call raw `create_record` with a `code` field for hook tables; backend request validation rejects `code` on REST CRUD.',
@@ -205,7 +205,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- To check which tables have canonical CRUD routes, call `get_all_routes` and look for `mainTable`. Custom routes intentionally have no `mainTable`; inspect their handlers/hooks to see which repos they touch.',
     '- **Tables confirmed to have REST routes (system):** `bootstrap_script_definition`, `column_rule_definition`, `cors_origin_definition`, `extension_definition`, `field_permission_definition`, `file_definition`, `file_permission_definition`, `flow_definition`, `flow_execution_definition`, `flow_step_definition`, `folder_definition`, `gql_definition`, `guard_definition`, `guard_rule_definition`, `menu_definition`, `method_definition`, `oauth_account_definition`, `oauth_config_definition`, `package_definition`, `post_hook_definition`, `pre_hook_definition`, `relation_definition`, `role_definition`, `route_definition`, `route_handler_definition`, `route_permission_definition`, `schema_migration_definition`, `setting_definition`, `storage_config_definition`, `table_definition`, `user_definition`, `websocket_definition`, `websocket_event_definition`.',
     '- **Tables without REST routes (internal/system only):** `column_definition`, `session_definition`. Columns are managed indirectly via cascade on `table_definition` (POST/PATCH with columns arrays). The `create_table`, `create_column`/`add_column`, `update_column`, and `delete_column`/`remove_column` MCP tools handle this automatically by reading full table metadata first.',
-    '- Use `create_column`/`add_column` for new scalar fields. These tools accept column metadata such as `isNullable`, `isUnique`, `isPublished`, `isPrimary`, `isGenerated`, `isSystem`, `defaultValue`, `description`, and `options`; set `isPublished=false` directly when creating secret/internal fields such as `*_encrypted`. When patching an existing table, only persisted columns with an `id`/`_id` belong in the cascade payload; metadata projections such as `createdAt`, `updatedAt`, or relation-derived FK display fields without an id are not valid column-definition patch rows. Never rebuild a schema cascade from `table_definition?fields=columns.*`, because nested relation fields may be paginated/truncated.',
+    '- Use `create_column`/`add_column` for new scalar fields. These tools accept column metadata such as `isNullable`, `isUnique`, `isPublished`, `isUpdatable`, `isEncrypted`, `isPrimary`, `isGenerated`, `isSystem`, `defaultValue`, `description`, and `options`; set `isUpdatable=false` for immutable fields and set `isPublished=false` directly when creating secret/internal fields. `isEncrypted=true` encrypts stored values at rest but does not change `isUpdatable`; encrypted fields must not be used for filter/sort. When patching an existing table, only persisted columns with an `id`/`_id` belong in the cascade payload; metadata projections such as `createdAt`, `updatedAt`, or relation-derived FK display fields without an id are not valid column-definition patch rows. Never rebuild a schema cascade from `table_definition?fields=columns.*`, because nested relation fields may be paginated/truncated.',
     '- Prefer `create_relation`/`add_relation` and `delete_relation`/`remove_relation` for relation schema changes because they preserve the full table relation list, serialize schema mutations, verify unrelated relation ids survived, and handle schema-confirm retry. Direct `create_record` on `relation_definition` only edits metadata and is not the canonical schema migration path; generic record mutations also reject physical FK/junction fields on `relation_definition`.',
     '- Destructive schema tools and generic `delete_record` return a preview unless `confirm=true` is passed. This applies to `delete_record`, `delete_table`, `delete_column`/`remove_column`, and `delete_relation`/`remove_relation`; do not add `confirm=true` until the user has explicitly approved the destructive operation.',
     '',

package/src/lib/table-tools.js

@@ -208,12 +208,14 @@ async function verifyRelationCascade(ENFYRA_API_URL, tableId, beforeIds, {
   return afterRelations;
 }
 
-function buildColumnDefinition({
+export function buildColumnDefinition({
   name,
   type,
   isNullable,
   isUnique,
   isPublished,
+  isUpdatable,
+  isEncrypted,
   isPrimary,
   isGenerated,
   isSystem,
@@ -225,6 +227,8 @@ function buildColumnDefinition({
   if (isNullable !== undefined) column.isNullable = isNullable;
   if (isUnique !== undefined) column.isUnique = isUnique;
   if (isPublished !== undefined) column.isPublished = isPublished;
+  if (isUpdatable !== undefined) column.isUpdatable = isUpdatable;
+  if (isEncrypted !== undefined) column.isEncrypted = isEncrypted;
   if (isPrimary !== undefined) column.isPrimary = isPrimary;
   if (isGenerated !== undefined) column.isGenerated = isGenerated;
   if (isSystem !== undefined) column.isSystem = isSystem;
@@ -378,6 +382,8 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     isNullable: z.boolean().optional().default(true).describe('Set to false if column cannot be null.'),
     isUnique: z.boolean().optional().default(false).describe('Set to true for unique constraint.'),
     isPublished: z.boolean().optional().describe('Set column visibility baseline. Use false for secrets and internal fields.'),
+    isUpdatable: z.boolean().optional().describe('Set false for immutable fields that cannot be updated after creation. Independent from isEncrypted.'),
+    isEncrypted: z.boolean().optional().describe('Set true to encrypt this column at the Enfyra database-query layer. This does not change isUpdatable. Encrypted fields cannot be filtered or sorted.'),
     isPrimary: z.boolean().optional().describe('Set true only for primary key columns; normally only create_table auto id uses this.'),
     isGenerated: z.boolean().optional().describe('Set true only for generated columns such as auto id.'),
     isSystem: z.boolean().optional().describe('Set true only for system-managed columns. Avoid for normal app fields.'),
@@ -448,7 +454,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       name: z.string().describe('Table name (e.g., "user_definition", "my_custom_table"). Must be unique, lowercase with underscores.'),
       description: z.string().optional().describe('Description of what this table stores.'),
       isSingleRecord: z.boolean().optional().describe('Set to true for single-record tables such as settings/config. This is passed directly to table_definition create.'),
-      columns: z.string().optional().describe('JSON array of column definitions to create with the table (cascade). Each column: { name, type, isNullable?, isUnique?, defaultValue?, description?, options? }. The `id` column is always auto-included. Example: [{"name":"title","type":"varchar"},{"name":"status","type":"enum","options":["draft","published"]}]'),
+      columns: z.string().optional().describe('JSON array of column definitions to create with the table (cascade). Each column: { name, type, isNullable?, isUnique?, isPublished?, isUpdatable?, isEncrypted?, defaultValue?, description?, options? }. Set isEncrypted=true for values encrypted at rest; set isUpdatable=false separately only when the field should be immutable. The `id` column is always auto-included. Example: [{"name":"title","type":"varchar"},{"name":"api_key","type":"varchar","isEncrypted":true,"isPublished":false}]'),
       relations: z.string().optional().describe('JSON array of relation definitions to create with the table in the same cascade call. Each relation: { targetTable, type, propertyName, inversePropertyName?, mappedBy?, isNullable?, onDelete?, description? }. targetTable can be an id or {"id": <id>}. Do not include physical FK/junction columns such as fkCol, foreignKeyColumn, sourceColumn, targetColumn, junctionSourceColumn, or junctionTargetColumn; Enfyra derives them and hides FK columns from app schema. Example: [{"targetTable":2,"type":"many-to-one","propertyName":"author","inversePropertyName":"posts","isNullable":false,"onDelete":"CASCADE"}]'),
       indexes: z.string().optional().describe('JSON array of logical index field groups. Each group can be ["fieldA","fieldB"] or {"value":["fieldA","fieldB"]}. Relation property names are allowed. Example: [["member","isRead","conversation"],["conversation","member","isRead"]]'),
       uniques: z.string().optional().describe('JSON array of logical unique field groups. Each group can be ["fieldA","fieldB"] or {"value":["fieldA","fieldB"]}. Example: [["message","member"]]'),
@@ -611,11 +617,12 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       type: z.string().optional().describe('New column type.'),
       isNullable: z.boolean().optional().describe('Set nullable.'),
       isPublished: z.boolean().optional().describe('Set column visibility baseline. false = unpublished (omitted from response unless allowed by field permission rules).'),
+      isUpdatable: z.boolean().optional().describe('Set false for immutable fields that should be stripped from update payloads.'),
       defaultValue: z.string().optional().describe('New default value as JSON string.'),
       description: z.string().optional().describe('New description.'),
       options: z.string().optional().describe('New options as JSON string.'),
     },
-    async ({ tableId, columnId, name, type, isNullable, isPublished, defaultValue, description, options }) => withSchemaQueue(async () => {
+    async ({ tableId, columnId, name, type, isNullable, isPublished, isUpdatable, defaultValue, description, options }) => withSchemaQueue(async () => {
       const tableData = await fetchTableWithDetails(ENFYRA_API_URL, tableId);
       if (!tableData) {
         return { content: [{ type: 'text', text: `Error: Table with ID ${tableId} not found.` }] };
@@ -634,6 +641,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
           if (type !== undefined) rest.type = type;
           if (isNullable !== undefined) rest.isNullable = isNullable;
           if (isPublished !== undefined) rest.isPublished = isPublished;
+          if (isUpdatable !== undefined) rest.isUpdatable = isUpdatable;
           if (defaultValue !== undefined) rest.defaultValue = defaultValue;
           if (description !== undefined) rest.description = description;
           if (options !== undefined) rest.options = JSON.parse(options);

package/src/mcp-server-entry.mjs

@@ -175,6 +175,8 @@ function summarizeTable(table) {
       isPrimary: !!column.isPrimary,
       isNullable: column.isNullable,
       isPublished: column.isPublished,
+      isUpdatable: column.isUpdatable !== false,
+      isEncrypted: column.isEncrypted === true,
     })),
     relations: (table.relations || []).map((relation) => ({
       id: relation.id ?? relation._id,
@@ -702,6 +704,9 @@ server.tool(
           keyRule: 'Do not include NODE_NAME, user_cache:, or Redis namespace prefixes in scripts. Prefer TTL-based set(key, value, ttlMs); setNoExpire may still be evicted by the user-cache soft allocation.',
         },
         throws: '@THROW400 through @THROW503 and @THROW map to $ctx.$throw helpers.',
+        helpers: {
+          crypto: '$ctx.$helpers.$crypto exposes bounded runtime crypto helpers: randomUUID(), randomBytes(size, encoding), sha256(value, encoding), hmacSha256(value, secret, encoding), and generateSshKeyPair(comment). Use generateSshKeyPair for Cloud host SSH keys. Do not use legacy $ctx.$helpers.$ssh.',
+        },
       },
       contexts: {
         preHook: {