@enfyra/mcp-server 0.1.69 → 0.1.71

package/dist/lib/mcp-example-extensions.js.map

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

package/dist/lib/mcp-example-files.d.ts

@@ -0,0 +1,9 @@
+export declare const filesExamples: {
+    title: string;
+    useWhen: string;
+    examples: {
+        name: string;
+        code: string;
+        notes: string[];
+    }[];
+};

package/dist/lib/mcp-example-files.js

@@ -0,0 +1,51 @@
+export const filesExamples = {
+    title: 'Files, folders, upload metadata, and assets',
+    useWhen: 'Use when handling uploads or returning uploaded files.',
+    examples: [
+        {
+            name: 'Upload a file from browser',
+            code: `const form = new FormData()
+form.append("file", file)
+form.append("folder", folderId)
+form.append("title", "Invoice")
+
+const uploadId = crypto.randomUUID()
+const uploaded = await fetch("/enfyra/enfyra_file", {
+  method: "POST",
+  credentials: "include",
+  headers: { "x-enfyra-upload-id": uploadId },
+  body: form
+}).then((res) => res.json())`,
+            notes: [
+                'Do not set Content-Type manually for FormData.',
+                'Browser apps use the app-origin /enfyra/enfyra_file proxy path; the Enfyra server endpoint is /enfyra_file.',
+                'x-enfyra-upload-id correlates $system:upload:progress events for this upload.',
+                'Use file routes/helpers instead of writing binary data into normal tables.',
+            ],
+        },
+        {
+            name: 'Use uploaded file in handler',
+            code: `const file = @UPLOADED_FILE
+if (!file) @THROW400("File is required")
+
+const saved = await @STORAGE.$upload({
+  file,
+  storageConfig: @BODY.storageConfig,
+  folder: @BODY.folder,
+  title: @BODY.title,
+  description: @BODY.description
+})
+
+return saved`,
+            notes: [
+                'Use file-specific context only in upload-capable routes.',
+                'For request uploads, pass file: @UPLOADED_FILE to @STORAGE.$upload/@STORAGE.$update so Enfyra streams from the temp file path.',
+                'For upload progress, the client should send x-enfyra-upload-id and listen for the authenticated $system:upload:progress event.',
+                'Use @STORAGE.$registerFile when an external process already uploaded the object and the script only needs to create the enfyra_file record.',
+                'Do not read @UPLOADED_FILE.path into a Buffer and do not generate examples using @UPLOADED_FILE.buffer.',
+                'Use buffer only for small generated or transformed files, such as image thumbnails.',
+            ],
+        },
+    ],
+};
+//# sourceMappingURL=mcp-example-files.js.map

package/dist/lib/mcp-example-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-example-files.js","sourceRoot":"","sources":["../../src/lib/mcp-example-files.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,aAAa,GAAG;IACzB,KAAK,EAAE,6CAA6C;IACpD,OAAO,EAAE,wDAAwD;IACjE,QAAQ,EAAE;QACR;YACE,IAAI,EAAE,4BAA4B;YAClC,IAAI,EAAE;;;;;;;;;;;6BAWe;YACrB,KAAK,EAAE;gBACL,gDAAgD;gBAChD,6GAA6G;gBAC7G,+EAA+E;gBAC/E,4EAA4E;aAC7E;SACF;QACD;YACE,IAAI,EAAE,8BAA8B;YACpC,IAAI,EAAE;;;;;;;;;;;aAWD;YACL,KAAK,EAAE;gBACL,0DAA0D;gBAC1D,gIAAgI;gBAChI,gIAAgI;gBAChI,6IAA6I;gBAC7I,yGAAyG;gBACzG,qFAAqF;aACtF;SACF;KACF;CACF,CAAC"}

package/dist/lib/mcp-example-flows.d.ts

@@ -0,0 +1,9 @@
+export declare const flowsExamples: {
+    title: string;
+    useWhen: string;
+    examples: {
+        name: string;
+        code: string;
+        notes: string[];
+    }[];
+};

package/dist/lib/mcp-example-flows.js

@@ -0,0 +1,76 @@
+export const flowsExamples = {
+    title: 'Flows and step scripts',
+    useWhen: 'Use when automating background work or chaining steps.',
+    examples: [
+        {
+            name: 'Manual flow trigger from a post-hook',
+            code: `if (!@ERROR && @DATA?.data?.[0]) {
+  await @TRIGGER("send-welcome-email", {
+    userId: @DATA.data[0].id,
+    email: @DATA.data[0].email
+  })
+}`,
+            notes: [
+                'Use flows for workflow semantics, retries, and history.',
+                'Do not use a flow just to persist a normal chat message.',
+            ],
+        },
+        {
+            name: 'Flow condition step',
+            code: `const order = @FLOW_PAYLOAD.order
+return order && order.total > 1000`,
+            notes: [
+                'Condition steps use JavaScript truthy/falsy.',
+                'Children run according to branch true/false.',
+            ],
+        },
+        {
+            name: 'Split a provisioning workflow into focused steps',
+            code: `[
+  { "key": "load_project", "stepOrder": 10, "type": "query" },
+  { "key": "reserve_capacity", "stepOrder": 20, "type": "script" },
+  { "key": "create_database_user", "stepOrder": 30, "type": "http" },
+  { "key": "apply_database_guardrails", "stepOrder": 40, "type": "script" },
+  { "key": "start_container", "stepOrder": 50, "type": "http" },
+  { "key": "check_health", "stepOrder": 60, "type": "http" },
+  { "key": "finalize_project", "stepOrder": 70, "type": "update" },
+  { "key": "write_audit_log", "stepOrder": 80, "type": "log" }
+]`,
+            notes: [
+                'Prefer flow_workflow for creating/updating a flow plus steps; it plans fixed step types before saving.',
+                'Use plan_flow_steps only as a lightweight dry-run when the flow itself is not being changed.',
+                'Each step should return only ids, booleans, status keys, or small counters that later steps need.',
+                'When refactoring an existing flow, add or extract adjacent focused enfyra_flow_step rows instead of making an oversized sourceCode block longer.',
+            ],
+        },
+        {
+            name: 'Flow query step config',
+            code: `{
+  "table": "enfyra_user",
+  "filter": { "email": { "_contains": "@example.com" } },
+  "limit": 50
+}`,
+            notes: [
+                'Step configs are JSON; script steps use code strings.',
+                'Use public-safe URLs for HTTP steps.',
+            ],
+        },
+        {
+            name: 'Flow create/update/delete step configs',
+            code: `// ensure_create_flow_step
+{ "table": "todo", "data": { "title": "Review", "status": "open" } }
+
+// ensure_update_flow_step
+{ "table": "todo", "id": "fixed-todo-id", "data": { "status": "done" } }
+
+// ensure_delete_flow_step
+{ "table": "todo", "id": "fixed-todo-id" }`,
+            notes: [
+                'Use fixed CRUD flow step tools only for static config; ESV does not interpolate @FLOW_PAYLOAD, @FLOW_LAST, or @FLOW inside fixed-step config.',
+                'Use one focused script step when a record id or body comes from runtime flow values, when a step coordinates multiple records, computes complex data, or calls packages.',
+                'Inside a script step, write captured logs with @LOGS(message, details?), not @LOGS.info().',
+            ],
+        },
+    ],
+};
+//# sourceMappingURL=mcp-example-flows.js.map

package/dist/lib/mcp-example-flows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-example-flows.js","sourceRoot":"","sources":["../../src/lib/mcp-example-flows.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,aAAa,GAAG;IACzB,KAAK,EAAE,wBAAwB;IAC/B,OAAO,EAAE,wDAAwD;IACjE,QAAQ,EAAE;QACR;YACE,IAAI,EAAE,sCAAsC;YAC5C,IAAI,EAAE;;;;;EAKZ;YACM,KAAK,EAAE;gBACL,yDAAyD;gBACzD,0DAA0D;aAC3D;SACF;QACD;YACE,IAAI,EAAE,qBAAqB;YAC3B,IAAI,EAAE;mCACqB;YAC3B,KAAK,EAAE;gBACL,8CAA8C;gBAC9C,8CAA8C;aAC/C;SACF;QACD;YACE,IAAI,EAAE,kDAAkD;YACxD,IAAI,EAAE;;;;;;;;;EASZ;YACM,KAAK,EAAE;gBACL,wGAAwG;gBACxG,8FAA8F;gBAC9F,mGAAmG;gBACnG,kJAAkJ;aACnJ;SACF;QACD;YACE,IAAI,EAAE,wBAAwB;YAC9B,IAAI,EAAE;;;;EAIZ;YACM,KAAK,EAAE;gBACL,uDAAuD;gBACvD,sCAAsC;aACvC;SACF;QACD;YACE,IAAI,EAAE,wCAAwC;YAC9C,IAAI,EAAE;;;;;;;2CAO6B;YACnC,KAAK,EAAE;gBACL,+IAA+I;gBAC/I,0KAA0K;gBAC1K,4FAA4F;aAC7F;SACF;KACF;CACF,CAAC"}

package/dist/lib/mcp-example-graphql.d.ts

@@ -0,0 +1,9 @@
+export declare const graphqlExamples: {
+    title: string;
+    useWhen: string;
+    examples: {
+        name: string;
+        code: string;
+        notes: string[];
+    }[];
+};

package/dist/lib/mcp-example-graphql.js

@@ -0,0 +1,57 @@
+export const graphqlExamples = {
+    title: 'GraphQL table exposure, queries, mutations, and verification',
+    useWhen: 'Use when enabling generated GraphQL for a table or executing a GraphQL operation through Enfyra.',
+    examples: [
+        {
+            name: 'Enable a table and verify its generated query',
+            code: `inspect_table({ tableName: "project" })
+
+set_table_graphql({
+  tableName: "project",
+  isEnabled: true,
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>"
+})
+
+test_graphql({
+  operationName: "VerifyProjects",
+  query: \`query VerifyProjects {
+    project(limit: 1) {
+      data { id name }
+      meta { totalCount }
+    }
+  }\`
+})`,
+            notes: [
+                'GraphQL root query names match enabled Enfyra table names and return data plus meta.',
+                'Only select fields confirmed by inspect_table or the live GraphQL schema; unpublished fields are not generated.',
+                'GraphQL table operations require Bearer authentication even when the REST route has publicMethods.',
+                'enfyra_graphql stores exposure metadata. Resolvers are generated by Enfyra and do not have editable sourceCode.',
+            ],
+        },
+        {
+            name: 'Execute a generated GraphQL mutation with variables',
+            code: `test_graphql({
+  operationName: "CreateTodo",
+  query: \`mutation CreateTodo($input: todoInput!) {
+    create_todo(input: $input) {
+      id
+      title
+      status
+    }
+  }\`,
+  variables: {
+    input: {
+      title: "Review GraphQL contract",
+      status: "open"
+    }
+  }
+})`,
+            notes: [
+                'Generated mutation names are create_<table>, update_<table>, and delete_<table>.',
+                'Inspect the live schema before choosing input fields because required fields and scalar types come from current table metadata.',
+                'test_graphql returns GraphQL errors as structured data; do not treat HTTP 200 alone as success.',
+            ],
+        },
+    ],
+};
+//# sourceMappingURL=mcp-example-graphql.js.map

package/dist/lib/mcp-example-graphql.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-example-graphql.js","sourceRoot":"","sources":["../../src/lib/mcp-example-graphql.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,eAAe,GAAG;IAC3B,KAAK,EAAE,8DAA8D;IACrE,OAAO,EAAE,kGAAkG;IAC3G,QAAQ,EAAE;QACR;YACE,IAAI,EAAE,+CAA+C;YACrD,IAAI,EAAE;;;;;;;;;;;;;;;;GAgBX;YACK,KAAK,EAAE;gBACL,sFAAsF;gBACtF,iHAAiH;gBACjH,oGAAoG;gBACpG,iHAAiH;aAClH;SACF;QACD;YACE,IAAI,EAAE,qDAAqD;YAC3D,IAAI,EAAE;;;;;;;;;;;;;;;GAeX;YACK,KAAK,EAAE;gBACL,kFAAkF;gBAClF,iIAAiI;gBACjI,iGAAiG;aAClG;SACF;KACF;CACF,CAAC"}

package/dist/lib/mcp-example-handlers-hooks.d.ts

@@ -0,0 +1,9 @@
+export declare const handlersHooksExamples: {
+    title: string;
+    useWhen: string;
+    examples: {
+        name: string;
+        code: string;
+        notes: string[];
+    }[];
+};

package/dist/lib/mcp-example-handlers-hooks.js

@@ -0,0 +1,328 @@
+export const handlersHooksExamples = {
+    title: 'Custom handlers, pre-hooks, post-hooks, and script macros',
+    useWhen: 'Use when writing Enfyra dynamic JavaScript for REST behavior.',
+    examples: [
+        {
+            name: 'Create a route handler with current script fields',
+            code: `create_handler({
+  routeId: "<route_id>",
+  method: "POST",
+  scriptLanguage: "javascript",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
+  knowledgeAckKey: "<dynamicCodeAckKey from get_enfyra_required_knowledge>",
+  sourceCode: \`const email = @BODY.email
+if (!email) @THROW400("Email is required")
+
+return { ok: true, email }\`
+})`,
+            notes: [
+                'Use sourceCode, not logic. The server generates compiledCode.',
+                'Call get_enfyra_required_knowledge before saving dynamic code, pass globalRulesAckKey as globalRulesAckKey, and pass dynamicCodeAckKey as knowledgeAckKey.',
+                'Use method for one handler, or methods only when the same sourceCode should be saved for multiple methods.',
+                'Do not pass name to enfyra_route_handler; one handler is identified by route + method.',
+            ],
+        },
+        {
+            name: 'Third-party create endpoint with server-owned identity',
+            code: `api_endpoint_workflow({
+  path: "/integrations/orders",
+  method: "POST",
+  anonymousAccess: "private",
+  roleName: "user",
+  applyAll: true,
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
+  knowledgeAckKey: "<dynamicCodeAckKey from get_enfyra_required_knowledge>",
+  sourceCode: \`const title = @BODY.title
+if (!title) @THROW400("title is required")
+
+const result = await #secure.orders.create({
+  data: {
+    ...@BODY,
+    owner: @USER.id
+  },
+  fields: ["id", "title", "owner"]
+})
+
+const order = result.data?.[0] ?? null
+if (!order) @THROW500("Order was not returned after create")
+return {
+  id: order.id,
+  title: order.title,
+  owner: order.owner?.id || order.owner
+}\`
+})`,
+            notes: [
+                'Custom routes have no main table, so explicit user-facing access uses #secure.orders rather than @REPOS.main.',
+                'data: @BODY is valid TypeORM-style repository usage. Put ...@BODY first and server-owned fields afterward so caller input cannot override them.',
+                'Custom handlers do not inherit canonical column-rule/Zod middleware; validate the endpoint-specific business payload in the handler.',
+                'Replace orders, owner, fields, role, and path only after inspecting live metadata and the intended external contract.',
+            ],
+        },
+        {
+            name: 'Third-party scoped update endpoint',
+            code: `const found = await #secure.orders.find({
+  filter: {
+    _and: [
+      { id: { _eq: @PARAMS.id } },
+      { owner: { id: { _eq: @USER.id } } }
+    ]
+  },
+  fields: ["id", "title", "owner"],
+  limit: 1
+})
+
+const order = found.data?.[0]
+if (!order) @THROW404("Order not found")
+
+const result = await #secure.orders.update({
+  id: order.id,
+  data: {
+    ...@BODY,
+    owner: @USER.id
+  },
+  fields: ["id", "title", "owner"]
+})
+
+const updated = result.data?.[0] ?? null
+return updated
+  ? { id: updated.id, title: updated.title, owner: updated.owner?.id || updated.owner }
+  : null`,
+            notes: [
+                'The scoped lookup proves the current row belongs to the caller before mutation; route permission and secure repository selection do not prove ownership.',
+                'The update keeps owner server-controlled instead of allowing @BODY to reassign it.',
+                'If ownership can change concurrently, make it immutable or use the transaction/business invariant appropriate to the application.',
+            ],
+        },
+        {
+            name: 'Third-party action updates a non-updatable server field',
+            code: `const found = await #secure.orders.find({
+  filter: {
+    _and: [
+      { id: { _eq: @PARAMS.id } },
+      { owner: { id: { _eq: @USER.id } } }
+    ]
+  },
+  fields: ["id", "status", "owner"],
+  limit: 1
+})
+
+const order = found.data?.[0]
+if (!order) @THROW404("Order not found")
+if (order.status !== "pending") @THROW409("Order is not pending")
+
+const result = await #orders.update({
+  id: order.id,
+  data: { status: "cancelled" },
+  fields: ["id", "status"]
+})
+
+const updated = result.data?.[0] ?? null
+return updated ? { id: updated.id, status: updated.status } : null`,
+            notes: [
+                'The secure lookup proves caller scope before the privileged mutation.',
+                'The trusted write is intentional because status is server-owned and non-updatable through normal CRUD. It writes an exact literal object, never raw @BODY.',
+                'Do not change status.isUpdatable to make this action work; that would broaden canonical CRUD for eApp and every other consumer.',
+                'Return an explicit response shape and never the raw trusted row.',
+            ],
+        },
+        {
+            name: 'Custom register handler',
+            code: `const email = @BODY.email
+const password = @BODY.password
+
+if (!email || !password) @THROW400("Email and password are required")
+
+const existing = await #enfyra_user.find({
+  filter: { email: { _eq: email } },
+  limit: 1
+})
+if (existing.data[0]) @THROW409("Email is already registered")
+
+const result = await #enfyra_user.create({
+  data: {
+    email,
+    password: await @HELPERS.$bcrypt.hash(password)
+  }
+})
+
+const user = result.data?.[0] ?? null
+if (!user) @THROW500("User was not returned after create")
+return { id: user.id, email: user.email }`,
+            notes: [
+                'create/update return { data: [...] }, not a bare row.',
+                'The trusted user repository is intentional for registration internals. Shape the response explicitly and never return the raw trusted row.',
+                'Use numeric @THROW helpers for raw HTTP messages. If you pass details, pass an object/array such as @THROW404("Request not found", { requestId }). Use @THROW.notFound(resource, id?) or @THROW.duplicate(resource, field, value) only when you want Enfyra-formatted semantic messages.',
+                'Prefer macros over raw $ctx when a macro exists.',
+            ],
+        },
+        {
+            name: 'Workflow handler with relation read and side effects',
+            code: `const requestId = @BODY.requestId
+if (!requestId) @THROW400("requestId is required")
+
+const found = await #secure.app_requests.find({
+  filter: { id: { _eq: requestId } },
+  fields: ["id", "title", "status", "requester"],
+  deep: {
+    requester: { fields: ["id", "email"] }
+  },
+  limit: 1
+})
+
+const request = found.data?.[0]
+if (!request) @THROW404("Request not found")
+if (request.status !== "pending") @THROW409("Request is not pending")
+
+await #secure.app_requests.update({
+  id: request.id,
+  data: { status: "approved" }
+})
+
+await #app_audit_log.create({
+  data: {
+    action: "request_approved",
+    request: request.id,
+    actor: @USER?.id || undefined
+  }
+})
+
+await #app_notifications.create({
+  data: {
+    kind: "request_approved",
+    recipient: request.requester?.id || request.requester,
+    request: request.id,
+    isRead: false
+  }
+})
+
+return { ok: true, id: request.id, status: "approved" }`,
+            notes: [
+                'This is a shape example, not a table template: replace app_requests/app_audit_log/app_notifications and relation names with live metadata.',
+                'In dynamic scripts, top-level fields controls which parent properties appear. When using deep requester, also include requester in top-level fields.',
+                'Inside deep.requester.fields, choose fields from the related requester row.',
+                'Use #secure.table for user-facing reads and writes so field permissions stay enabled. The audit/notification writes above are trusted internal side effects and must return only the shaped response.',
+                'Create/update return { data: [...] }; use result.data?.[0] when the script needs the saved object.',
+            ],
+        },
+        {
+            name: 'Find one record by id in a handler',
+            code: `const reportId = @BODY.reportId
+if (!reportId) @THROW400("reportId is required")
+
+const found = await #secure.app_reports.find({
+  filter: { id: { _eq: reportId } },
+  fields: ["id", "status", "owner"],
+  limit: 1
+})
+
+const report = found.data?.[0]
+if (!report) @THROW404("Report not found", { reportId })
+
+return {
+  id: report.id,
+  status: report.status
+}`,
+            notes: [
+                'Use #secure.table_name with explicit fields and limit:1 for user-facing dynamic-script lookups.',
+                'Use id filters when they work in the live runtime, but do not keep retrying @REPOS.<table>.find id filter shapes if a runtime reports undefined SQL bindings.',
+                'If primary-key filtering fails in a runtime, pivot to a unique business field, the route main-table context, or a bounded query that you can verify, then update the contract/example for that runtime.',
+                'Never return raw trusted repository rows; shape the response explicitly.',
+            ],
+        },
+        {
+            name: 'Canonical route pre-hook RLS filter merge',
+            code: `const incoming = @QUERY.filter || {}
+const scope = {
+  memberships: {
+    member: { id: { _eq: @USER.id } }
+  }
+}
+
+@QUERY.filter = Object.keys(incoming).length
+  ? { _and: [incoming, scope] }
+  : scope`,
+            notes: [
+                '@QUERY.filter is initialized as an object for REST pre-hooks.',
+                'Mutate @QUERY.filter before canonical CRUD runs.',
+                'This policy affects every consumer of the canonical route, including eApp. Use a separate custom endpoint handler when the scope is third-party-only.',
+                'Do not override @QUERY.fields, @QUERY.deep, @QUERY.sort, @QUERY.limit, @QUERY.page, @QUERY.meta, @QUERY.aggregate, or debugMode in RLS; keep projection and pagination client-owned.',
+            ],
+        },
+        {
+            name: 'Encrypted field table definition',
+            code: `create_tables({
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
+  items: [
+    {
+      name: "integrations",
+      columns: [
+        { name: "name", type: "varchar", isNullable: false },
+        {
+          name: "api_token",
+          type: "varchar",
+          isNullable: false,
+          isPublished: false,
+          isEncrypted: true
+        }
+      ]
+    }
+  ]
+})`,
+            notes: [
+                'Use isEncrypted=true for values that must be encrypted at rest.',
+                'Scripts and REST callers read and write plaintext values; Enfyra encrypts on write and decrypts after select.',
+                'Set isPublished=false for secret fields that should not be exposed by default.',
+                'isEncrypted does not imply immutability; add isUpdatable=false separately only when the value must not change.',
+                'Do not generate manual $encrypt hooks or accept caller-supplied enc:v1: ciphertext for normal app data.',
+                'Encrypted fields cannot be filtered or sorted.',
+            ],
+        },
+        {
+            name: 'Pre-hook strips protected body fields silently',
+            code: `create_pre_hook({
+  routeId: "<enfyra_user_patch_route_id>",
+  name: "strip_email_verification_fields",
+  methods: ["PATCH"],
+  priority: -10,
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
+  knowledgeAckKey: "<dynamicCodeAckKey from get_enfyra_required_knowledge>",
+  code: \`delete @BODY.emailVerifiedAt
+delete @BODY.emailVerificationStatus
+delete @BODY.emailVerificationSentAt\`
+})`,
+            notes: [
+                'Use this pattern when clients may send protected user fields through /me or enfyra_user PATCH.',
+                'Strip fields instead of throwing when the product wants a permissive client contract with server-owned fields.',
+                'Use native macros such as @BODY instead of raw $ctx when a macro exists.',
+            ],
+        },
+        {
+            name: 'Post-hook response shaping',
+            code: `create_post_hook({
+  routeId: "<route_id>",
+  name: "shape_display_title",
+  methods: ["GET"],
+  priority: 0,
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
+  knowledgeAckKey: "<dynamicCodeAckKey from get_enfyra_required_knowledge>",
+  code: \`if (@ERROR) {
+  @LOGS("Request failed", @ERROR.message)
+  return
+}
+
+const row = Array.isArray(@DATA?.data) ? @DATA.data[0] : @DATA
+if (row) {
+  row.displayTitle = row.title || row.email || String(row.id)
+}
+
+return @DATA\`
+})`,
+            notes: [
+                'MCP create_post_hook accepts code as the tool argument, then persists sourceCode/scriptLanguage to Enfyra.',
+                'Post-hooks run after success and error paths.',
+                'Return non-undefined only when replacing the response body.',
+            ],
+        },
+    ],
+};
+//# sourceMappingURL=mcp-example-handlers-hooks.js.map

package/dist/lib/mcp-example-handlers-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-example-handlers-hooks.js","sourceRoot":"","sources":["../../src/lib/mcp-example-handlers-hooks.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACjC,KAAK,EAAE,2DAA2D;IAClE,OAAO,EAAE,+DAA+D;IACxE,QAAQ,EAAE;QACR;YACE,IAAI,EAAE,mDAAmD;YACzD,IAAI,EAAE;;;;;;;;;;GAUX;YACK,KAAK,EAAE;gBACL,+DAA+D;gBAC/D,4JAA4J;gBAC5J,4GAA4G;gBAC5G,wFAAwF;aACzF;SACF;QACD;YACE,IAAI,EAAE,wDAAwD;YAC9D,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BX;YACK,KAAK,EAAE;gBACL,+GAA+G;gBAC/G,iJAAiJ;gBACjJ,sIAAsI;gBACtI,uHAAuH;aACxH;SACF;QACD;YACE,IAAI,EAAE,oCAAoC;YAC1C,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;SA0BL;YACD,KAAK,EAAE;gBACL,0JAA0J;gBAC1J,oFAAoF;gBACpF,mIAAmI;aACpI;SACF;QACD;YACE,IAAI,EAAE,yDAAyD;YAC/D,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;mEAsBqD;YAC3D,KAAK,EAAE;gBACL,uEAAuE;gBACvE,4JAA4J;gBAC5J,iIAAiI;gBACjI,kEAAkE;aACnE;SACF;QACD;YACE,IAAI,EAAE,yBAAyB;YAC/B,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;0CAoB4B;YAClC,KAAK,EAAE;gBACL,uDAAuD;gBACvD,4IAA4I;gBAC5I,0RAA0R;gBAC1R,kDAAkD;aACnD;SACF;QACD;YACE,IAAI,EAAE,sDAAsD;YAC5D,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wDAsC0C;YAChD,KAAK,EAAE;gBACL,4IAA4I;gBAC5I,sJAAsJ;gBACtJ,6EAA6E;gBAC7E,uMAAuM;gBACvM,oGAAoG;aACrG;SACF;QACD;YACE,IAAI,EAAE,oCAAoC;YAC1C,IAAI,EAAE;;;;;;;;;;;;;;;EAeZ;YACM,KAAK,EAAE;gBACL,iGAAiG;gBACjG,+JAA+J;gBAC/J,yMAAyM;gBACzM,0EAA0E;aAC3E;SACF;QACD;YACE,IAAI,EAAE,2CAA2C;YACjD,IAAI,EAAE;;;;;;;;;UASJ;YACF,KAAK,EAAE;gBACL,+DAA+D;gBAC/D,kDAAkD;gBAClD,uJAAuJ;gBACvJ,sLAAsL;aACvL;SACF;QACD;YACE,IAAI,EAAE,kCAAkC;YACxC,IAAI,EAAE;;;;;;;;;;;;;;;;;GAiBX;YACK,KAAK,EAAE;gBACL,iEAAiE;gBACjE,+GAA+G;gBAC/G,gFAAgF;gBAChF,gHAAgH;gBAChH,yGAAyG;gBACzG,gDAAgD;aACjD;SACF;QACD;YACE,IAAI,EAAE,gDAAgD;YACtD,IAAI,EAAE;;;;;;;;;;GAUX;YACK,KAAK,EAAE;gBACL,gGAAgG;gBAChG,gHAAgH;gBAChH,0EAA0E;aAC3E;SACF;QACD;YACE,IAAI,EAAE,4BAA4B;YAClC,IAAI,EAAE;;;;;;;;;;;;;;;;;;GAkBX;YACK,KAAK,EAAE;gBACL,4GAA4G;gBAC5G,+CAA+C;gBAC/C,6DAA6D;aAC9D;SACF;KACF;CACF,CAAC"}

package/dist/lib/mcp-example-oauth-setup.d.ts

@@ -0,0 +1,9 @@
+export declare const oauthSetupExamples: {
+    title: string;
+    useWhen: string;
+    examples: {
+        name: string;
+        code: string;
+        notes: string[];
+    }[];
+};

package/dist/lib/mcp-example-oauth-setup.js

@@ -0,0 +1,41 @@
+export const oauthSetupExamples = {
+    title: 'OAuth provider setup',
+    useWhen: 'Use only after the third app follows the connect contract and the user is ready to supply Google, Facebook, or GitHub client credentials.',
+    examples: [
+        {
+            name: 'Configure the provider and hand off its callback',
+            code: `setup_oauth_provider({
+  provider: "google",
+  clientId: "<user-supplied-client-id>",
+  clientSecret: "<user-supplied-client-secret>",
+  appConnectionVerified: true,
+  globalRulesAckKey: "<globalRulesAckKey>",
+})`,
+            notes: [
+                'Connect the third app before asking for provider credentials. Load category=connect, inspect its framework, and verify the proxy, OAuth start action, cookieBridgePrefix, and /me flow first.',
+                'After the connection is verified, stop and ask the user to supply provider, clientId, and clientSecret. Never read or reuse stored credential values, never infer credentials, and never ask the user for a callback URI.',
+                'Do not present callbackUri or ask the user to configure the provider console before setup_oauth_provider returns its receipt. If credentials are missing, ask only for clientId and clientSecret and stop.',
+                'appConnectionVerified=true is required and may be sent only after that app connection check.',
+                'setup_oauth_provider derives callbackUri from the connected Enfyra API target, upserts enfyra_oauth_config, enables autoSetCookies, verifies runtime activation, and returns no credentials.',
+                'The receipt has setupComplete=false. Present providerConsole.value exactly as returned, ask the user to add it to providerConsole.field, then stop and wait for confirmation.',
+                'After confirmation, use the OAuth button in the already connected app and verify /me before reporting setup success.',
+            ],
+        },
+        {
+            name: 'Provider console handoff',
+            code: `// Use the successful setup_oauth_provider receipt.
+const callback = result.callbackUri
+
+// Google: Authorized redirect URIs
+// Facebook: Valid OAuth Redirect URIs
+// GitHub: Authorization callback URL`,
+            notes: [
+                'The provider callback is an Enfyra API URL, not the third-app return page.',
+                'If runtimeProviderActive is false, resolve verification before sending the user to the provider console.',
+                'Neither /auth/providers nor an existing linked OAuth account proves the provider console callback or current credentials work; complete a real browser login after confirmation.',
+                'Never echo clientId or clientSecret in the handoff.',
+            ],
+        },
+    ],
+};
+//# sourceMappingURL=mcp-example-oauth-setup.js.map

package/dist/lib/mcp-example-oauth-setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-example-oauth-setup.js","sourceRoot":"","sources":["../../src/lib/mcp-example-oauth-setup.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAC9B,KAAK,EAAE,sBAAsB;IAC7B,OAAO,EAAE,2IAA2I;IACpJ,QAAQ,EAAE;QACR;YACE,IAAI,EAAE,kDAAkD;YACxD,IAAI,EAAE;;;;;;GAMX;YACK,KAAK,EAAE;gBACL,+LAA+L;gBAC/L,2NAA2N;gBAC3N,4MAA4M;gBAC5M,8FAA8F;gBAC9F,8LAA8L;gBAC9L,+KAA+K;gBAC/K,sHAAsH;aACvH;SACF;QACD;YACE,IAAI,EAAE,0BAA0B;YAChC,IAAI,EAAE;;;;;sCAKwB;YAC9B,KAAK,EAAE;gBACL,4EAA4E;gBAC5E,0GAA0G;gBAC1G,kLAAkL;gBAClL,qDAAqD;aACtD;SACF;KACF;CACF,CAAC"}

package/dist/lib/mcp-example-permissions-rls.d.ts

@@ -0,0 +1,9 @@
+export declare const permissionsRlsExamples: {
+    title: string;
+    useWhen: string;
+    examples: {
+        name: string;
+        code: string;
+        notes: string[];
+    }[];
+};