@fluentcommerce/fluent-mcp-extn 0.2.1 → 0.3.0

package/README.md

@@ -19,7 +19,7 @@ Exposes event dispatch, transition actions, GraphQL operations, Prometheus metri
 - [Requirements](#requirements)
 - [Install](#install)
 - [Configuration](#configuration)
-- [Tools (36)](#tools-36)
+- [Tools (39)](#tools-39)
 - [Error Handling](#error-handling)
 - [Support Scripts (Debugging and Validation)](#support-scripts-debugging-and-validation)
 - [Troubleshooting](#troubleshooting)
@@ -81,8 +81,8 @@ The official `fluent mcp server` (bundled with Fluent CLI) covers core GraphQL a
 | Schema introspection (`graphql.introspect`) | | Yes |
 | Multi-strategy auth (profile, OAuth, token command, static token) | | Yes |
 | Entity CRUD (`entity.create` / `entity.update` / `entity.get`) | | Yes |
-| Workflow management (`workflow.upload` / `workflow.diff` / `workflow.simulate`) | | Yes |
-| Settings management (`setting.upsert` / `setting.bulkUpsert`) | | Yes |
+| Workflow management (`workflow.get` / `workflow.list` / `workflow.upload` / `workflow.diff` / `workflow.simulate`) | | Yes |
+| Settings management (`setting.get` / `setting.upsert` / `setting.bulkUpsert`) | | Yes |
 | Environment snapshot (`environment.discover` / `environment.validate`) | | Yes |
 | Test assertions with polling (`test.assert`) | | Yes |
 
@@ -120,7 +120,16 @@ Reads base URL, client ID/secret, username/password, and retailer ID from `~/.fl
 
 #### Option B: Explicit OAuth credentials
 
-Pass all credentials directly in env vars:
+Set credentials as **shell environment variables** (never in `.mcp.json`):
+
+```bash
+export FLUENT_CLIENT_ID=your-client-id
+export FLUENT_CLIENT_SECRET=your-client-secret
+export FLUENT_USERNAME=your-username
+export FLUENT_PASSWORD=your-password
+```
+
+Then in `.mcp.json`, only the non-sensitive connection details:
 
 ```json
 {
@@ -131,17 +140,15 @@ Pass all credentials directly in env vars:
       "args": ["@fluentcommerce/fluent-mcp-extn"],
       "env": {
         "FLUENT_BASE_URL": "https://YOUR_ACCOUNT.sandbox.api.fluentretail.com",
-        "FLUENT_RETAILER_ID": "YOUR_RETAILER_ID",
-        "FLUENT_CLIENT_ID": "YOUR_CLIENT_ID",
-        "FLUENT_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
-        "FLUENT_USERNAME": "YOUR_USERNAME",
-        "FLUENT_PASSWORD": "YOUR_PASSWORD"
+        "FLUENT_RETAILER_ID": "YOUR_RETAILER_ID"
       }
     }
   }
 }
 ```
 
+The MCP server inherits all parent shell environment variables automatically.
+
 #### Option C: Profile + overrides (hybrid)
 
 Use a profile as the base, override specific values via env vars:
@@ -383,6 +390,8 @@ Plus at least one auth method below.
 | `FLUENT_USERNAME` | No | Username (for password grant) |
 | `FLUENT_PASSWORD` | No | Password (for password grant) |
 
+> **Security:** These credentials must be set as shell environment variables, never in `.mcp.json`. MCP server processes inherit all parent shell env vars automatically. The `mcp-setup` command strips any secrets found in `.mcp.json` during re-runs.
+
 #### 3. Token command
 
 | Variable | Default | Description |
@@ -423,7 +432,7 @@ Controls how large responses are handled before returning to the AI. When a resp
 | `FLUENT_RESPONSE_MAX_ARRAY` | `50` | Arrays exceeding this size are auto-summarized. Only active when budget > 0. |
 | `FLUENT_RESPONSE_SAMPLE_SIZE` | `3` | Number of sample records included in array summaries. |
 
-## Tools (36)
+## Tools (39)
 
 ### Diagnostics
 
@@ -534,6 +543,8 @@ Useful flags:
 | `workflow.transitions` | Query available user actions/transitions for provided triggers (`POST /api/v4.1/transition`) |
 | `plugin.list` | List all registered rules with metadata (`GET /orchestration/rest/v1/plugin`). Supports optional name filter. |
 
+**`flexType` auto-derive:** When `type` and `subtype` are provided but `flexType` is omitted, it is auto-derived as `TYPE::SUBTYPE`. All three params (`module`, `flexType`, `flexVersion`) are required by the Transition API — omitting any one silently returns empty results.
+
 **Example** — get actions for a ServicePoint manifest trigger:
 
 ```json
@@ -551,6 +562,23 @@ Useful flags:
 }
 ```
 
+**Example** — auto-derive flexType from type + subtype:
+
+```json
+{
+  "triggers": [
+    {
+      "type": "CREDIT_MEMO",
+      "subtype": "APPEASEMENT",
+      "status": "CREATED",
+      "module": "adminconsole",
+      "flexVersion": "1.0",
+      "retailerId": "2"
+    }
+  ]
+}
+```
+
 **Example** — list all rules matching "SendEvent":
 
 ```json
@@ -600,6 +628,19 @@ Useful flags:
 }
 ```
 
+**Example** — dry-run batch mutation (validates query without executing):
+
+```json
+{
+  "mutation": "updateOrder",
+  "inputs": [{ "id": "1", "status": "SHIPPED" }],
+  "returnFields": ["id", "ref", "status"],
+  "dryRun": true
+}
+```
+
+With `dryRun: true`, returns the generated aliased mutation query and variables for review without making any API call. Use this to preview what will be sent before executing bulk operations.
+
 ### Batch Ingestion
 
 | Tool | Description |
@@ -647,19 +688,73 @@ Typical flow: `batch.create` → `batch.send` → `batch.status` (poll) → `bat
 
 | Tool | Description |
 |---|---|
+| `workflow.get` | Fetch a specific workflow by entity type and subtype via REST API. Works even when the list endpoint returns 401. |
+| `workflow.list` | List all workflows for a retailer. Deduplicates to latest version per workflow name. |
 | `workflow.upload` | Deploy workflow JSON via REST API with structure validation. For production, prefer `fluent module install` via CLI. |
 | `workflow.diff` | Compare two workflow definitions — returns added/removed/modified rulesets with risk assessment. Supports `summary`, `detailed`, and `mermaid` formats. |
 | `workflow.simulate` | Static analysis prediction of which rulesets would fire for a given status + event name. Does NOT execute Java rules or check runtime state — use `workflow.transitions` for authoritative live validation. |
 
+**Example** — fetch a workflow and save to file:
+
+```json
+{
+  "entityType": "ORDER",
+  "entitySubtype": "HD",
+  "retailerId": "2",
+  "outputFile": "accounts/MYPROFILE/workflows/MyRetailer/ORDER-HD.json"
+}
+```
+
+When `outputFile` is set, the full workflow JSON is saved to disk and only a summary is returned (status count, ruleset count, total rules). This reads from the **live server** via REST API — not the CLI workflowlog cache.
+
+**Example** — list all workflows and download to directory:
+
+```json
+{
+  "retailerId": "2",
+  "outputDir": "accounts/MYPROFILE/workflows/MyRetailer/"
+}
+```
+
+With `outputDir`, each workflow is saved as `{TYPE}-{SUBTYPE}.json` (e.g., `ORDER-HD.json`). The response lists saved files with paths and sizes. Without `outputDir`, returns metadata only (name, version, status count per workflow).
+
 ### Settings Management
 
 | Tool | Description |
 |---|---|
+| `setting.get` | Fetch settings by name (`%` wildcards supported), optionally save to local file to keep large JSON out of LLM context |
 | `setting.upsert` | Create or update a setting with upsert semantics — queries existing by name + context + contextId first |
 | `setting.bulkUpsert` | Batch create/update up to 50 settings with per-setting error handling |
 
 **Contexts:** RETAILER, ACCOUNT, LOCATION, NETWORK, AGENT, CUSTOMER
 
+**Example** — fetch a manifest setting and save to file (keeps large JSON out of LLM context):
+
+```json
+{
+  "name": "fc.mystique.manifest.oms",
+  "context": "ACCOUNT",
+  "contextId": 0,
+  "outputFile": "accounts/MYPROFILE/manifests/backups/fc.mystique.manifest.oms.json"
+}
+```
+
+When `outputFile` is set, the response returns metadata only (name, context, valueType, sizeBytes, savedTo path) — the full JSON goes to disk. For multiple matches (e.g., `name: "fc.mystique.manifest.%"`), each setting is saved as a separate file in the outputFile directory.
+
+**Example** — create/update a manifest setting with explicit `valueType`:
+
+```json
+{
+  "name": "fc.mystique.manifest.oms.fragment.custom",
+  "context": "ACCOUNT",
+  "contextId": 0,
+  "valueType": "JSON",
+  "lobValue": { "manifestVersion": "2.0", "routes": [] }
+}
+```
+
+The `valueType` parameter accepts `"STRING"`, `"LOB"`, or `"JSON"`. For Mystique manifest settings, always use `valueType: "JSON"` — the default `LOB` breaks manifest parsing. A warning is emitted if a `fc.mystique.manifest.*` setting is created without `valueType: "JSON"`.
+
 ### Environment
 
 | Tool | Description |
@@ -727,6 +822,10 @@ All tools return a consistent envelope:
 | `SDK_ERROR` | Unexpected SDK error | Varies |
 | `UNKNOWN_ERROR` | Unclassified error | No |
 
+### Retry Behavior
+
+Read operations (queries, list, get) use `execute()` which retries on transient failures (timeout, rate limit, network errors) with exponential backoff up to `FLUENT_RETRY_ATTEMPTS` times. Write operations (create, update, send, upload, upsert) use `executeOnce()` with **no automatic retry** to prevent duplicate side effects. Tune retry parameters via the [Resilience Tuning](#resilience-tuning) env vars above.
+
 ## Support Scripts (Debugging and Validation)
 
 These scripts are useful during tenant validation, support, and failure triage:
@@ -775,7 +874,9 @@ When used alongside `@fluentcommerce/ai-skills`, this extension server integrate
 ```
 accounts/
   <PROFILE>/
-    SOURCE/           # custom plugin repos and JAR files
+    SOURCE/           # custom source code (account-level, shared across retailers)
+      backend/        # Java Maven plugin repos and JAR files
+      frontend/       # Mystique SDK component projects
     workflows/        # downloaded workflow JSONs (scoped by retailer)
     analysis/         # generated analysis artifacts
 ```

package/dist/entity-registry.js

@@ -286,6 +286,7 @@ const ENTITY_REGISTRY = {
             'context is a plain String ("RETAILER"), NOT { contextType: "RETAILER" }',
             "contextId is a separate Int field, not combined with context",
             "For large JSON values, use lobValue instead of value (lobType: LOB)",
+            'For Mystique manifest settings (fc.mystique.*), set valueType:"JSON" — LOB type breaks manifest parsing silently',
         ],
         hasRef: false,
         retailerScoped: false,

package/dist/fluent-client.js

@@ -140,6 +140,36 @@ export class FluentClientAdapter {
             return FluentClientAdapter.unwrapResponse(response);
         });
     }
+    /**
+     * Fetch a workflow definition by name from the REST API.
+     * GET /api/v4.1/workflow/{retailerId}/{entityType}::{entitySubtype}/
+     * Optionally fetch a specific version:
+     * GET /api/v4.1/workflow/{retailerId}/{entityType}::{entitySubtype}/{version}
+     * Read-only — safe to retry.
+     */
+    async getWorkflow(retailerId, entityType, entitySubtype, version) {
+        const requestClient = this.requireRequestClient("Workflow REST API");
+        const workflowName = `${entityType}::${entitySubtype}`;
+        const path = version
+            ? `/api/v4.1/workflow/${retailerId}/${workflowName}/${version}`
+            : `/api/v4.1/workflow/${retailerId}/${workflowName}/`;
+        return this.execute("getWorkflow", async () => {
+            const response = await requestClient.request(path, { method: "GET" });
+            return FluentClientAdapter.unwrapResponse(response);
+        });
+    }
+    /**
+     * List all workflows for a retailer from the REST API.
+     * GET /api/v4.1/workflow?retailerId={retailerId}
+     * Read-only — safe to retry.
+     */
+    async listWorkflows(retailerId) {
+        const requestClient = this.requireRequestClient("Workflow REST API");
+        return this.execute("listWorkflows", async () => {
+            const response = await requestClient.request(`/api/v4.1/workflow?retailerId=${retailerId}&count=200`, { method: "GET" });
+            return FluentClientAdapter.unwrapResponse(response);
+        });
+    }
     /**
      * Query Prometheus metrics via GraphQL metricInstant / metricRange queries.
      * The Fluent platform does NOT expose raw Prometheus REST endpoints

package/dist/settings-tools.js

@@ -5,6 +5,8 @@
  * settings that workflows depend on (webhook URLs, feature flags, thresholds).
  */
 import { z } from "zod";
+import * as fs from "node:fs";
+import * as path from "node:path";
 import { ToolError } from "./errors.js";
 // ---------------------------------------------------------------------------
 // Input schemas
@@ -16,6 +18,11 @@ const SettingInputSchema = z.object({
         .string()
         .optional()
         .describe("Large object value (for JSON payloads > 4KB). Mutually exclusive with value."),
+    valueType: z
+        .enum(["STRING", "LOB", "JSON"])
+        .optional()
+        .describe('Explicit value type override. Use "JSON" for Mystique manifest settings (fc.mystique.*). ' +
+        'Defaults to "LOB" when lobValue is provided, "STRING" when value is provided.'),
     context: z
         .string()
         .min(1)
@@ -26,6 +33,34 @@ const SettingInputSchema = z.object({
         .optional()
         .describe("Context ID (e.g., retailer ID). Falls back to FLUENT_RETAILER_ID for RETAILER context."),
 });
+export const SettingGetInputSchema = z.object({
+    name: z
+        .string()
+        .min(1)
+        .describe('Setting name or pattern. Supports "%" wildcards (e.g., "fc.mystique.manifest.%" for all manifest settings).'),
+    context: z
+        .string()
+        .optional()
+        .describe('Filter by context: "ACCOUNT", "RETAILER". Omit for all contexts.'),
+    contextId: z
+        .number()
+        .int()
+        .optional()
+        .describe("Context ID. Falls back to FLUENT_RETAILER_ID for RETAILER context, 0 for ACCOUNT."),
+    outputFile: z
+        .string()
+        .optional()
+        .describe("Optional file path to save the setting value/lobValue. " +
+        "When provided, writes content to file and returns only metadata (name, context, valueType, size) — " +
+        "keeps large manifests/JSON out of the LLM context. Parent directories are created automatically."),
+    first: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .default(10)
+        .describe("Max results to return (default: 10, max: 100)."),
+});
 export const SettingUpsertInputSchema = SettingInputSchema;
 export const SettingBulkUpsertInputSchema = z.object({
     settings: z
@@ -38,6 +73,57 @@ export const SettingBulkUpsertInputSchema = z.object({
 // Tool definitions (JSON Schema for MCP)
 // ---------------------------------------------------------------------------
 export const SETTING_TOOL_DEFINITIONS = [
+    {
+        name: "setting.get",
+        description: [
+            "Fetch one or more Fluent Commerce settings by name (supports % wildcards).",
+            "",
+            "Returns metadata inline (name, context, contextId, valueType).",
+            "For small settings, the value is returned inline.",
+            "For large settings (manifests, JSON > 4KB), use outputFile to save content",
+            "to a local file and keep it out of the LLM context.",
+            "",
+            "When outputFile is set AND exactly one setting matches:",
+            "  - Writes lobValue (or value) to the file",
+            "  - Returns metadata + file path + byte size (NOT the content)",
+            "",
+            "When outputFile is NOT set:",
+            "  - Returns full setting data inline (may be large for manifests)",
+            "",
+            "Examples:",
+            '  setting.get({ name: "fc.mystique.manifest.oms.fragment.ordermanagement" })',
+            '  setting.get({ name: "fc.mystique.manifest.%", context: "ACCOUNT" })',
+            '  setting.get({ name: "fc.mystique.manifest.oms", outputFile: "./manifest-backup.json" })',
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Setting name or pattern with % wildcards",
+                },
+                context: {
+                    type: "string",
+                    description: "Filter by context: ACCOUNT, RETAILER, etc.",
+                },
+                contextId: {
+                    type: "integer",
+                    description: "Context ID. Defaults to FLUENT_RETAILER_ID or 0.",
+                },
+                outputFile: {
+                    type: "string",
+                    description: "File path to save setting content. Returns metadata only (not content) when set.",
+                },
+                first: {
+                    type: "integer",
+                    description: "Max results (default: 10, max: 100)",
+                    default: 10,
+                },
+            },
+            required: ["name"],
+            additionalProperties: false,
+        },
+    },
     {
         name: "setting.upsert",
         description: [
@@ -50,6 +136,8 @@ export const SETTING_TOOL_DEFINITIONS = [
             '- context is a plain String ("RETAILER"), NOT an object',
             "- contextId is a separate Int field",
             "- For large JSON values (>4KB), use lobValue instead of value",
+            '- For Mystique manifest settings (fc.mystique.*), set valueType: "JSON"',
+            "  — without it, defaults to LOB which breaks manifest parsing",
             "- Returns created: true/false for audit trail",
             "",
             "CONTEXTS: RETAILER, ACCOUNT, LOCATION, NETWORK, AGENT, CUSTOMER",
@@ -69,6 +157,12 @@ export const SETTING_TOOL_DEFINITIONS = [
                     type: "string",
                     description: "Large object value (for JSON payloads > 4KB)",
                 },
+                valueType: {
+                    type: "string",
+                    enum: ["STRING", "LOB", "JSON"],
+                    description: 'Explicit value type. Use "JSON" for Mystique manifest settings (fc.mystique.*). ' +
+                        "Defaults to LOB when lobValue provided, STRING when value provided.",
+                },
                 context: {
                     type: "string",
                     description: 'Setting scope: RETAILER, ACCOUNT, LOCATION, NETWORK, AGENT, CUSTOMER',
@@ -103,6 +197,11 @@ export const SETTING_TOOL_DEFINITIONS = [
                             name: { type: "string" },
                             value: { type: "string" },
                             lobValue: { type: "string" },
+                            valueType: {
+                                type: "string",
+                                enum: ["STRING", "LOB", "JSON"],
+                                description: 'Explicit value type. Use "JSON" for manifest settings.',
+                            },
                             context: { type: "string" },
                             contextId: { type: "integer" },
                         },
@@ -179,10 +278,18 @@ async function createSetting(client, input) {
     };
     if (input.lobValue) {
         mutationInput.lobValue = input.lobValue;
-        mutationInput.valueType = "LOB";
     }
     else {
         mutationInput.value = input.value;
+    }
+    // Explicit valueType wins; otherwise default to LOB/STRING based on field used
+    if (input.valueType) {
+        mutationInput.valueType = input.valueType;
+    }
+    else if (input.lobValue) {
+        mutationInput.valueType = "LOB";
+    }
+    else {
         mutationInput.valueType = "STRING";
     }
     const mutation = `mutation CreateSetting($input: CreateSettingInput!) {
@@ -220,10 +327,18 @@ async function updateSetting(client, input) {
     };
     if (input.lobValue) {
         mutationInput.lobValue = input.lobValue;
-        mutationInput.valueType = "LOB";
     }
     else {
         mutationInput.value = input.value;
+    }
+    // Explicit valueType wins; otherwise default to LOB/STRING based on field used
+    if (input.valueType) {
+        mutationInput.valueType = input.valueType;
+    }
+    else if (input.lobValue) {
+        mutationInput.valueType = "LOB";
+    }
+    else {
         mutationInput.valueType = "STRING";
     }
     const mutation = `mutation UpdateSetting($input: UpdateSettingInput!) {
@@ -250,6 +365,151 @@ async function updateSetting(client, input) {
     }
     return setting;
 }
+/**
+ * Handle setting.get tool call.
+ * Fetches settings by name (with wildcard support) and optionally writes to file.
+ */
+export async function handleSettingGet(args, ctx) {
+    const parsed = SettingGetInputSchema.parse(args);
+    const client = requireSettingClient(ctx);
+    // Build variables — only include context/contextId if provided
+    const variables = {
+        name: [parsed.name],
+        first: parsed.first,
+    };
+    if (parsed.context) {
+        variables.context = [parsed.context];
+    }
+    if (parsed.contextId !== undefined) {
+        variables.contextId = [parsed.contextId];
+    }
+    else if (parsed.context === "RETAILER" && ctx.config.retailerId) {
+        variables.contextId = [Number(ctx.config.retailerId)];
+    }
+    else if (parsed.context === "ACCOUNT") {
+        variables.contextId = [0];
+    }
+    // Build query — include lobValue for full content
+    const query = `query GetSettings($name: [String!], $context: [String!], $contextId: [Int!], $first: Int) {
+  settings(name: $name, context: $context, contextId: $contextId, first: $first) {
+    edges {
+      node {
+        id
+        name
+        value
+        lobValue
+        context
+        contextId
+        valueType
+      }
+    }
+  }
+}`;
+    const response = await client.graphql({
+        query,
+        variables: variables,
+    });
+    const data = response?.data;
+    const connection = data?.settings;
+    const edges = (connection?.edges ?? []);
+    const settings = edges.map((e) => e.node);
+    if (settings.length === 0) {
+        return {
+            ok: true,
+            count: 0,
+            settings: [],
+            message: `No settings found matching "${parsed.name}"${parsed.context ? ` with context ${parsed.context}` : ""}.`,
+        };
+    }
+    // If outputFile is provided and exactly one setting matches, write to file
+    if (parsed.outputFile && settings.length === 1) {
+        const setting = settings[0];
+        const content = setting.lobValue ?? setting.value ?? "";
+        // Try to pretty-print JSON content
+        let fileContent = content;
+        try {
+            const parsed = JSON.parse(content);
+            fileContent = JSON.stringify(parsed, null, 2);
+        }
+        catch {
+            // Not JSON — write as-is
+        }
+        // Ensure parent directory exists
+        const dir = path.dirname(parsed.outputFile);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(parsed.outputFile, fileContent, "utf-8");
+        return {
+            ok: true,
+            count: 1,
+            savedTo: parsed.outputFile,
+            sizeBytes: Buffer.byteLength(fileContent, "utf-8"),
+            setting: {
+                id: setting.id,
+                name: setting.name,
+                context: setting.context,
+                contextId: setting.contextId,
+                valueType: setting.valueType,
+            },
+            message: `Setting "${setting.name}" saved to ${parsed.outputFile} (${Buffer.byteLength(fileContent, "utf-8")} bytes). Content NOT included in response.`,
+        };
+    }
+    // If outputFile provided but multiple settings match, warn
+    if (parsed.outputFile && settings.length > 1) {
+        // Write each setting to a separate file in the outputFile directory
+        const outputDir = parsed.outputFile.endsWith(".json")
+            ? path.dirname(parsed.outputFile)
+            : parsed.outputFile;
+        fs.mkdirSync(outputDir, { recursive: true });
+        const savedFiles = [];
+        for (const setting of settings) {
+            const content = setting.lobValue ?? setting.value ?? "";
+            let fileContent = content;
+            try {
+                const p = JSON.parse(content);
+                fileContent = JSON.stringify(p, null, 2);
+            }
+            catch {
+                // Not JSON — write as-is
+            }
+            const safeName = setting.name.replace(/[^a-zA-Z0-9._-]/g, "_");
+            const filePath = path.join(outputDir, `${safeName}.json`);
+            fs.writeFileSync(filePath, fileContent, "utf-8");
+            savedFiles.push({
+                name: setting.name,
+                file: filePath,
+                sizeBytes: Buffer.byteLength(fileContent, "utf-8"),
+            });
+        }
+        return {
+            ok: true,
+            count: settings.length,
+            savedTo: outputDir,
+            files: savedFiles,
+            settings: settings.map((s) => ({
+                id: s.id,
+                name: s.name,
+                context: s.context,
+                contextId: s.contextId,
+                valueType: s.valueType,
+            })),
+            message: `${settings.length} settings saved to ${outputDir}/. Content NOT included in response.`,
+        };
+    }
+    // No outputFile — return everything inline
+    return {
+        ok: true,
+        count: settings.length,
+        settings: settings.map((s) => ({
+            id: s.id,
+            name: s.name,
+            value: s.value,
+            lobValue: s.lobValue,
+            context: s.context,
+            contextId: s.contextId,
+            valueType: s.valueType,
+        })),
+    };
+}
 /**
  * Handle setting.upsert tool call.
  */
@@ -259,37 +519,52 @@ export async function handleSettingUpsert(args, ctx) {
     const contextId = resolveContextId(parsed.context, parsed.contextId, ctx.config);
     // Check if setting already exists
     const existing = await findExistingSetting(client, parsed.name, parsed.context, contextId);
+    // Warn when manifest setting is used without explicit valueType: "JSON"
+    const isManifestSetting = parsed.name.startsWith("fc.mystique.manifest.");
+    const manifestWarning = isManifestSetting && parsed.valueType !== "JSON"
+        ? 'Manifest setting detected without valueType:"JSON". ' +
+            "Default LOB type will break Mystique manifest parsing. " +
+            'Set valueType:"JSON" for fc.mystique.* settings.'
+        : undefined;
     if (existing) {
         // Update
         const setting = await updateSetting(client, {
             id: existing.id,
             value: parsed.value,
             lobValue: parsed.lobValue,
+            valueType: parsed.valueType,
             context: parsed.context,
             contextId,
         });
-        return {
+        const result = {
             ok: true,
             created: false,
             updated: true,
             setting,
             previousValue: existing.value ?? existing.lobValue,
         };
+        if (manifestWarning)
+            result.warning = manifestWarning;
+        return result;
     }
     // Create
     const setting = await createSetting(client, {
         name: parsed.name,
         value: parsed.value,
         lobValue: parsed.lobValue,
+        valueType: parsed.valueType,
         context: parsed.context,
         contextId,
     });
-    return {
+    const result = {
         ok: true,
         created: true,
         updated: false,
         setting,
     };
+    if (manifestWarning)
+        result.warning = manifestWarning;
+    return result;
 }
 /**
  * Handle setting.bulkUpsert tool call.
@@ -310,6 +585,7 @@ export async function handleSettingBulkUpsert(args, ctx) {
                     id: existing.id,
                     value: setting.value,
                     lobValue: setting.lobValue,
+                    valueType: setting.valueType,
                     context: setting.context,
                     contextId,
                 });
@@ -321,6 +597,7 @@ export async function handleSettingBulkUpsert(args, ctx) {
                     name: setting.name,
                     value: setting.value,
                     lobValue: setting.lobValue,
+                    valueType: setting.valueType,
                     context: setting.context,
                     contextId,
                 });

package/dist/tools.js

@@ -6,8 +6,8 @@ import { buildEventPayload } from "./event-payload.js";
 import { ToolError, toToolFailure } from "./errors.js";
 // New tool modules
 import { ENTITY_TOOL_DEFINITIONS, handleEntityCreate, handleEntityUpdate, handleEntityGet, } from "./entity-tools.js";
-import { WORKFLOW_TOOL_DEFINITIONS, handleWorkflowUpload, handleWorkflowDiff, handleWorkflowSimulate, } from "./workflow-tools.js";
-import { SETTING_TOOL_DEFINITIONS, handleSettingUpsert, handleSettingBulkUpsert, } from "./settings-tools.js";
+import { WORKFLOW_TOOL_DEFINITIONS, handleWorkflowGet, handleWorkflowList, handleWorkflowUpload, handleWorkflowDiff, handleWorkflowSimulate, } from "./workflow-tools.js";
+import { SETTING_TOOL_DEFINITIONS, handleSettingGet, handleSettingUpsert, handleSettingBulkUpsert, } from "./settings-tools.js";
 import { ENVIRONMENT_TOOL_DEFINITIONS, handleEnvironmentDiscover, handleEnvironmentValidate, } from "./environment-tools.js";
 import { TEST_TOOL_DEFINITIONS, handleTestAssert, } from "./test-tools.js";
 import { shapeResponse, summarizeConnection, analyzeEvents, } from "./response-shaper.js";
@@ -128,6 +128,8 @@ const TransitionTriggerInputSchema = z.object({
     module: z.string().min(1).optional(),
     flexType: z.string().min(1).optional(),
     flexVersion: z.union([z.string().min(1), z.number().int()]).optional(),
+    entityId: z.string().min(1).optional(),
+    entityRef: z.string().min(1).optional(),
 });
 const TransitionActionsInputSchema = z.object({
     triggers: z.array(TransitionTriggerInputSchema).min(1),
@@ -599,8 +601,16 @@ const TOOL_DEFINITIONS = [
             "INTEGRATION: The eventName from each userAction maps directly to event.send's \"name\" parameter.",
             "The attributes[] tell you what to include in event.send's \"attributes\" parameter.",
             "",
+            "CRITICAL: The Transition API requires `flexType` (e.g. ORDER::HD) to return results.",
+            "Without it the API silently returns empty `{response:[]}`. For some entity types",
+            "(e.g. CREDIT_MEMO) `flexVersion` is also required. When `type` and `subtype` are",
+            "provided but `flexType` is not, the tool auto-derives it as `TYPE::SUBTYPE`.",
+            "",
+            "BEST PRACTICE: Always provide `flexType` and `flexVersion` for reliable results.",
+            "Get these from the entity's `workflowRef` and `workflowVersion` fields via GraphQL.",
+            "",
             "EXAMPLE: Find available actions for an ORDER in CREATED status:",
-            "{ triggers: [{ type: \"ORDER\", subtype: \"HD\", status: \"CREATED\", retailerId: \"5\", flexType: \"ORDER::HD\" }] }",
+            "{ triggers: [{ type: \"ORDER\", subtype: \"HD\", status: \"CREATED\", retailerId: \"5\", flexType: \"ORDER::HD\", flexVersion: 4 }] }",
         ].join("\n"),
         inputSchema: {
             type: "object",
@@ -623,17 +633,19 @@ const TOOL_DEFINITIONS = [
                             },
                             module: {
                                 type: "string",
-                                description: "Filter by module (e.g. servicepoint, adminconsole). Case-sensitive.",
+                                description: "REQUIRED for results. App module name (e.g. adminconsole, oms, store, servicepoint). Without this, API silently returns empty userActions. Case-sensitive.",
                             },
                             flexType: {
                                 type: "string",
-                                description: "Workflow type (e.g. ORDER::HD, FULFILMENT::HD_WH).",
+                                description: "Workflow type (e.g. ORDER::HD, FULFILMENT::HD_WH). REQUIRED for API to return results. Auto-derived from type::subtype when omitted.",
                             },
                             flexVersion: {
                                 oneOf: [{ type: "integer" }, { type: "string" }],
-                                description: "Workflow version. Omit for latest.",
+                                description: "Workflow version. Strongly recommended — required for some entity types (e.g. CREDIT_MEMO). Get from entity's workflowVersion field.",
                             },
                             name: { type: "string", description: "Event name filter" },
+                            entityId: { type: "string", description: "Entity ID (strongly recommended — API may return empty without it)" },
+                            entityRef: { type: "string", description: "Entity ref (strongly recommended — API may return empty without it)" },
                         },
                         required: ["retailerId"],
                         additionalProperties: false,
@@ -1258,7 +1270,14 @@ export function toEventQueryParams(input) {
     return params;
 }
 /**
- * Fill missing trigger.retailerId from runtime config and validate readiness.
+ * Fill missing trigger fields from runtime config and validate readiness.
+ *
+ * The Transition API requires `flexType` (e.g. "ORDER::HD") to return results.
+ * Without it the API silently returns `{"response":[]}`.  For some entity
+ * types (e.g. CREDIT_MEMO) `flexVersion` is also required.
+ *
+ * This function auto-derives `flexType` from `type`+`subtype` when both are
+ * present and `flexType` is not explicitly set.
  */
 export function resolveTransitionRequest(input, fallbackRetailerId) {
     const triggers = input.triggers.map((trigger, index) => {
@@ -1266,9 +1285,16 @@ export function resolveTransitionRequest(input, fallbackRetailerId) {
         if (!retailerId) {
             throw new ToolError("VALIDATION_ERROR", `triggers[${index}].retailerId is required. Set FLUENT_RETAILER_ID or pass retailerId per trigger.`);
         }
+        // Auto-derive flexType from type+subtype when not explicitly provided.
+        // The Transition API requires flexType to return user actions.
+        let flexType = trigger.flexType;
+        if (!flexType && trigger.type && trigger.subtype) {
+            flexType = `${trigger.type}::${trigger.subtype}`;
+        }
         return {
             ...trigger,
             retailerId,
+            ...(flexType ? { flexType } : {}),
         };
     });
     return { triggers };
@@ -3212,6 +3238,16 @@ export function registerToolHandlers(server, ctx) {
                 const result = await handleEntityGet(args, ctx);
                 return json(result, false, ctx.responseBudget);
             }
+            // ------- workflow.get ---------------------------------------------------
+            if (toolName === "workflow.get") {
+                const result = await handleWorkflowGet(args, ctx);
+                return json(result, false, ctx.responseBudget);
+            }
+            // ------- workflow.list --------------------------------------------------
+            if (toolName === "workflow.list") {
+                const result = await handleWorkflowList(args, ctx);
+                return json(result, false, ctx.responseBudget);
+            }
             // ------- workflow.upload -----------------------------------------------
             if (toolName === "workflow.upload") {
                 const result = await handleWorkflowUpload(args, ctx);
@@ -3227,6 +3263,11 @@ export function registerToolHandlers(server, ctx) {
                 const result = await handleWorkflowSimulate(args, ctx);
                 return json(result, false, ctx.responseBudget);
             }
+            // ------- setting.get ---------------------------------------------------
+            if (toolName === "setting.get") {
+                const result = await handleSettingGet(args, ctx);
+                return json(result, false, ctx.responseBudget);
+            }
             // ------- setting.upsert ------------------------------------------------
             if (toolName === "setting.upsert") {
                 const result = await handleSettingUpsert(args, ctx);

package/dist/workflow-tools.js

@@ -7,6 +7,8 @@
  * event outcomes without live execution.
  */
 import { z } from "zod";
+import * as fs from "node:fs";
+import * as path from "node:path";
 import { ToolError } from "./errors.js";
 // ---------------------------------------------------------------------------
 // Input schemas
@@ -40,6 +42,42 @@ export const WorkflowDiffInputSchema = z.object({
         .default("summary")
         .describe("Output format: summary (default), detailed, or mermaid"),
 });
+export const WorkflowGetInputSchema = z.object({
+    entityType: z
+        .string()
+        .describe("Workflow entity type (e.g., ORDER, FULFILMENT, INVENTORY_CATALOGUE, RETURN_ORDER, BILLING_ACCOUNT, VIRTUAL_CATALOGUE, PRODUCT_CATALOGUE, CONTROL_GROUP, PAYMENT, WAVE, CONSIGNMENT, ARTICLE)."),
+    entitySubtype: z
+        .string()
+        .describe("Workflow entity subtype (e.g., HD, DEFAULT, MASTER, BASE, CC, CUSTOMER, REFUND, PAYMENT)."),
+    retailerId: z
+        .string()
+        .optional()
+        .describe("Target retailer ID. Falls back to FLUENT_RETAILER_ID."),
+    version: z
+        .string()
+        .optional()
+        .describe("Specific workflow version to fetch. Omit for latest."),
+    outputFile: z
+        .string()
+        .optional()
+        .describe("Optional file path to save the full workflow JSON. " +
+        "When provided, writes workflow to file and returns only summary " +
+        "(name, version, status/ruleset counts) — keeps large workflow JSON out of the LLM context. " +
+        "Parent directories are created automatically."),
+});
+export const WorkflowListInputSchema = z.object({
+    retailerId: z
+        .string()
+        .optional()
+        .describe("Target retailer ID. Falls back to FLUENT_RETAILER_ID."),
+    outputDir: z
+        .string()
+        .optional()
+        .describe("Optional directory path to download ALL workflows (latest version each) as individual JSON files. " +
+        "Each file is named <ENTITY_TYPE>-<ENTITY_SUBTYPE>.json (e.g., ORDER-HD.json). " +
+        "Returns only summary metadata — full workflow JSON is NOT included in the response. " +
+        "Reads from live server (NOT workflowlog cache). Parent directories are created automatically."),
+});
 export const WorkflowSimulateInputSchema = z.object({
     workflow: z
         .union([z.string(), z.record(z.string(), z.unknown())])
@@ -64,6 +102,91 @@ export const WorkflowSimulateInputSchema = z.object({
 // Tool definitions (JSON Schema for MCP)
 // ---------------------------------------------------------------------------
 export const WORKFLOW_TOOL_DEFINITIONS = [
+    {
+        name: "workflow.get",
+        description: [
+            "Fetch a workflow definition by entity type and subtype from the Fluent REST API.",
+            "",
+            "Calls GET /api/v4.1/workflow/{retailerId}/{entityType}::{entitySubtype}/",
+            "Returns the full workflow JSON including statuses, rulesets, rules, and triggers.",
+            "",
+            "NOTE: This fetches a specific workflow by name, which works even when the list",
+            "endpoint returns 401 (insufficient permissions for listing).",
+            "",
+            "KNOWN ENTITY TYPES:",
+            "ORDER, FULFILMENT, INVENTORY_CATALOGUE, RETURN_ORDER, BILLING_ACCOUNT,",
+            "VIRTUAL_CATALOGUE, PRODUCT_CATALOGUE, CONTROL_GROUP, PAYMENT, WAVE,",
+            "CONSIGNMENT, ARTICLE, LOCATION, NETWORK, CUSTOMER, CREDIT_MEMO",
+            "",
+            "COMMON SUBTYPES:",
+            "HD, CC, DEFAULT, MASTER, BASE, CUSTOMER, REFUND, PAYMENT, HD_WH, HD_MP",
+            "",
+            "RESPONSE includes: name, version, entityType, entitySubtype, statuses, rulesets,",
+            "and a summary with status/ruleset/rule counts.",
+            "",
+            "Use outputFile to save large workflow JSON to disk instead of returning inline.",
+            "Returns only summary (name, version, counts) when outputFile is set.",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                entityType: {
+                    type: "string",
+                    description: "Workflow entity type (e.g., ORDER, FULFILMENT, INVENTORY_CATALOGUE)",
+                },
+                entitySubtype: {
+                    type: "string",
+                    description: "Workflow entity subtype (e.g., HD, DEFAULT, MASTER)",
+                },
+                retailerId: {
+                    type: "string",
+                    description: "Target retailer ID.",
+                },
+                version: {
+                    type: "string",
+                    description: "Specific workflow version. Omit for latest.",
+                },
+                outputFile: {
+                    type: "string",
+                    description: "File path to save workflow JSON. Returns summary only (not full JSON) when set.",
+                },
+            },
+            required: ["entityType", "entitySubtype"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "workflow.list",
+        description: [
+            "List all workflows for a retailer from the Fluent REST API.",
+            "",
+            "Calls GET /api/v4.1/workflow?retailerId={retailerId}",
+            "Returns a list of workflow summaries (name, version, entityType, entitySubtype, status).",
+            "",
+            "When outputDir is provided, downloads ALL workflows (latest version each) as individual",
+            "JSON files to the directory. Each file is named <TYPE>-<SUBTYPE>.json (e.g., ORDER-HD.json).",
+            "Returns only summary metadata — full JSON stays on disk, not in the response.",
+            "Reads from LIVE server, not the workflowlog cache.",
+            "",
+            "NOTE: This endpoint may return 401 on some accounts where the user lacks listing",
+            "permissions. In that case, use workflow.get to fetch a specific workflow by name.",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                retailerId: {
+                    type: "string",
+                    description: "Target retailer ID.",
+                },
+                outputDir: {
+                    type: "string",
+                    description: "Directory to save all workflows as individual JSON files. Returns summary only when set.",
+                },
+            },
+            required: [],
+            additionalProperties: false,
+        },
+    },
     {
         name: "workflow.upload",
         description: [
@@ -750,3 +873,166 @@ export async function handleWorkflowSimulate(args, _ctx) {
         limitations,
     };
 }
+/**
+ * Handle workflow.get tool call.
+ * Fetches a specific workflow by entityType::entitySubtype via REST API.
+ */
+export async function handleWorkflowGet(args, ctx) {
+    const parsed = WorkflowGetInputSchema.parse(args);
+    const retailerId = parsed.retailerId ?? ctx.config.retailerId;
+    if (!retailerId) {
+        throw new ToolError("VALIDATION_ERROR", "retailerId is required. Set FLUENT_RETAILER_ID or pass retailerId.");
+    }
+    const client = requireWorkflowClient(ctx);
+    const workflowName = `${parsed.entityType}::${parsed.entitySubtype}`;
+    const response = await client.getWorkflow(retailerId, parsed.entityType, parsed.entitySubtype, parsed.version);
+    // Extract summary info from the workflow
+    const wf = response;
+    if (!wf || typeof wf !== "object") {
+        throw new ToolError("VALIDATION_ERROR", `No workflow found for ${workflowName} on retailer ${retailerId}.`);
+    }
+    const statuses = (wf.statuses ?? wf.subStatuses);
+    const rulesets = wf.rulesets;
+    const totalRules = (rulesets ?? []).reduce((sum, rs) => {
+        const rules = rs.rules;
+        return sum + (rules?.length ?? 0);
+    }, 0);
+    const summary = {
+        statuses: statuses?.length ?? 0,
+        rulesets: rulesets?.length ?? 0,
+        totalRules,
+    };
+    // If outputFile is provided, write workflow to file and return summary only
+    if (parsed.outputFile) {
+        const fileContent = JSON.stringify(wf, null, 2);
+        const dir = path.dirname(parsed.outputFile);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(parsed.outputFile, fileContent, "utf-8");
+        return {
+            ok: true,
+            workflowName: wf.name ?? workflowName,
+            version: wf.version,
+            entityType: wf.entityType ?? parsed.entityType,
+            entitySubtype: wf.entitySubtype ?? parsed.entitySubtype,
+            retailerId,
+            summary,
+            savedTo: parsed.outputFile,
+            sizeBytes: Buffer.byteLength(fileContent, "utf-8"),
+            message: `Workflow saved to ${parsed.outputFile} (${Buffer.byteLength(fileContent, "utf-8")} bytes). Full JSON NOT included in response.`,
+        };
+    }
+    return {
+        ok: true,
+        workflowName: wf.name ?? workflowName,
+        version: wf.version,
+        entityType: wf.entityType ?? parsed.entityType,
+        entitySubtype: wf.entitySubtype ?? parsed.entitySubtype,
+        retailerId,
+        summary,
+        workflow: wf,
+    };
+}
+/**
+ * Handle workflow.list tool call.
+ * Lists all workflows for a retailer via REST API.
+ */
+export async function handleWorkflowList(args, ctx) {
+    const parsed = WorkflowListInputSchema.parse(args);
+    const retailerId = parsed.retailerId ?? ctx.config.retailerId;
+    if (!retailerId) {
+        throw new ToolError("VALIDATION_ERROR", "retailerId is required. Set FLUENT_RETAILER_ID or pass retailerId.");
+    }
+    const client = requireWorkflowClient(ctx);
+    const response = await client.listWorkflows(retailerId);
+    // Response can be: bare array, paginated { results: [...] }, or unwrapped from { data: ... }
+    let workflows;
+    if (Array.isArray(response)) {
+        workflows = response;
+    }
+    else if (response && typeof response === "object" && "results" in response) {
+        workflows = response.results;
+    }
+    else {
+        workflows = [];
+    }
+    // Deduplicate: group by name, keep only latest version
+    const latestByName = new Map();
+    for (const wf of workflows) {
+        const w = wf;
+        const name = w.name;
+        if (!name)
+            continue;
+        const existing = latestByName.get(name);
+        if (!existing || Number(w.version) > Number(existing.version)) {
+            latestByName.set(name, w);
+        }
+    }
+    const latest = [...latestByName.values()].map((w) => ({
+        name: w.name,
+        version: w.version,
+        entityType: w.entityType,
+        entitySubtype: w.entitySubtype,
+        status: w.status,
+        createdOn: w.createdOn,
+    }));
+    // If outputDir is provided, download each workflow's full JSON to individual files
+    if (parsed.outputDir && latest.length > 0) {
+        fs.mkdirSync(parsed.outputDir, { recursive: true });
+        const savedFiles = [];
+        const errors = [];
+        for (const wf of latest) {
+            const entityType = wf.entityType;
+            const entitySubtype = wf.entitySubtype;
+            if (!entityType || !entitySubtype)
+                continue;
+            try {
+                const fullWf = await client.getWorkflow(retailerId, entityType, entitySubtype);
+                if (fullWf && typeof fullWf === "object") {
+                    const fileContent = JSON.stringify(fullWf, null, 2);
+                    const fileName = `${entityType}-${entitySubtype}.json`;
+                    const filePath = path.join(parsed.outputDir, fileName);
+                    fs.writeFileSync(filePath, fileContent, "utf-8");
+                    savedFiles.push({
+                        name: wf.name,
+                        file: filePath,
+                        sizeBytes: Buffer.byteLength(fileContent, "utf-8"),
+                        version: wf.version,
+                    });
+                }
+            }
+            catch (err) {
+                errors.push({
+                    name: `${entityType}::${entitySubtype}`,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        const totalBytes = savedFiles.reduce((s, f) => s + f.sizeBytes, 0);
+        return {
+            ok: true,
+            retailerId,
+            totalVersions: workflows.length,
+            uniqueWorkflows: latest.length,
+            savedTo: parsed.outputDir,
+            filesWritten: savedFiles.length,
+            totalSizeBytes: totalBytes,
+            files: savedFiles,
+            ...(errors.length > 0 ? { errors } : {}),
+            message: `${savedFiles.length} workflow(s) saved to ${parsed.outputDir}/ (${(totalBytes / 1024).toFixed(1)} KB total). ` +
+                `Full JSON NOT included in response.` +
+                (errors.length > 0
+                    ? ` ${errors.length} workflow(s) failed to download.`
+                    : ""),
+        };
+    }
+    return {
+        ok: true,
+        retailerId,
+        totalVersions: workflows.length,
+        uniqueWorkflows: latest.length,
+        workflows: latest,
+        note: workflows.length === 0
+            ? "No workflows found. The list endpoint may return 401 on some accounts — try workflow.get with a specific entityType and entitySubtype instead."
+            : undefined,
+    };
+}

package/docs/RUNBOOK.md

@@ -92,8 +92,11 @@ Run tools in this order:
 7. `event.get` using ID returned by send
 8. `graphql.query` simple read
 9. `entity.get` — verify entity lookup works (e.g., look up a known order by ref)
-10. `workflow.transitions` (optional) — verify User Action API access for a known trigger
-11. `graphql.queryAll` — verify auto-pagination and run-level timeout
+10. `setting.get` with `name: "fc.mystique.manifest.%"` — verify settings read access and wildcard support
+11. `workflow.list` — verify REST workflow API access (list all workflows for a retailer)
+12. `workflow.get` with `entityType: "ORDER", entitySubtype: "HD"` — verify specific workflow fetch
+13. `workflow.transitions` (optional) — verify User Action API access for a known trigger
+14. `graphql.queryAll` — verify auto-pagination and run-level timeout
 12. `graphql.introspect` with `listMutations: true` — verify schema access
 13. `environment.discover` with `include: ["retailer", "locations"]` — verify environment snapshot
 14. `environment.validate` with `checks: ["auth", "retailer", "locations"]` — verify pre-flight checks

package/docs/TOOL_REFERENCE.md

@@ -462,6 +462,7 @@ Calls `POST /api/v4.1/transition` to discover what events can be fired, what att
 - **Required**: `triggers` (array), each trigger requires `retailerId`
 - **Optional per trigger**: `type`, `subtype`, `status`, `module`, `flexType`, `flexVersion`, `name`
 - **Retailer behavior**: `retailerId` is required per trigger. Falls back to `FLUENT_RETAILER_ID` when omitted.
+- **flexType auto-derive**: When `flexType` is not provided but `type` and `subtype` are, the tool auto-derives `flexType` as `{type}::{subtype}` (e.g., `CREDIT_MEMO::APPEASEMENT`). This avoids the silent empty-response problem where the Transition API returns `{"response":[]}` when `flexType` is missing.
 
 ### Use cases
 
@@ -1309,6 +1310,62 @@ Response:
 
 ---
 
+## `workflow.get`
+
+Fetch a specific workflow definition by entity type and subtype via REST API.
+
+Uses `GET /api/v4.1/workflow/{retailerId}/{entityType}::{entitySubtype}/` — works even when the list endpoint returns 401 (permission-restricted accounts).
+
+- **Required**:
+  - `entityType`: workflow entity type (e.g., `ORDER`, `FULFILMENT`, `INVENTORY_CATALOGUE`)
+  - `entitySubtype`: workflow entity subtype (e.g., `HD`, `DEFAULT`, `MASTER`)
+- **Optional**:
+  - `retailerId`: target retailer ID (falls back to `FLUENT_RETAILER_ID`)
+  - `version`: specific workflow version to fetch (omit for latest)
+  - `outputFile`: file path to save workflow JSON. When set, writes full workflow to file and returns only summary (name, version, status/ruleset/rule counts) — keeps large workflow JSON out of the LLM context. Parent directories are created automatically.
+
+**Response** includes a summary (status count, ruleset count, total rules) plus the full workflow JSON (unless `outputFile` is set).
+
+**Known entity types:** ORDER, FULFILMENT, FULFILMENT_CHOICE, ARTICLE, RETURN_ORDER, WAVE, CONSIGNMENT, INVENTORY_CATALOGUE, INVENTORY_POSITION, VIRTUAL_CATALOGUE, LOCATION, PRODUCT, CUSTOMER, CARRIER, NETWORK, CREDIT_MEMO.
+
+**Example:**
+
+```json
+{
+  "entityType": "INVENTORY_CATALOGUE",
+  "entitySubtype": "DEFAULT",
+  "retailerId": "34"
+}
+```
+
+**Note:** Fluent returns HTTP 200 with an empty body for nonexistent workflows — the handler checks for meaningful content (presence of `name` field) and returns a clear "not found" message.
+
+---
+
+## `workflow.list`
+
+List all workflows for a retailer via REST API.
+
+Uses `GET /api/v4.1/workflow?retailerId={id}&count=200`. Response is deduplicated to show only the latest version of each workflow. Reads from **live server**, NOT the workflowlog cache.
+
+- **Optional**:
+  - `retailerId`: target retailer ID (falls back to `FLUENT_RETAILER_ID`)
+  - `outputDir`: directory path to download ALL workflows (latest version each) as individual JSON files. Each file is named `<TYPE>-<SUBTYPE>.json`. Returns only summary metadata when set — full JSON stays on disk. Parent directories are created automatically.
+
+**Response** includes per-workflow summary (name, version, status count, ruleset count) and totals.
+
+**Example:**
+
+```json
+{
+  "retailerId": "35"
+}
+```
+
+**Note:** Some accounts restrict this endpoint (401 "Incorrect retailer"). In that case, use `workflow.get` with a specific entityType + entitySubtype instead.
+
+---
+
 ## `workflow.upload`
 
 Deploy a workflow JSON definition to the Fluent environment.
@@ -1491,6 +1548,57 @@ Response:
 
 ---
 
+## `setting.get`
+
+Fetch one or more Fluent Commerce settings by name (supports `%` wildcards).
+
+Uses the GraphQL `settings(name:)` query. Returns metadata inline (name, context, contextId, valueType). For large settings (manifests, JSON > 4KB), use `outputFile` to save content to a local file and keep it out of the LLM context.
+
+- **Required**:
+  - `name`: setting name or pattern. Supports `%` wildcards (e.g., `fc.mystique.manifest.%` for all manifest settings)
+- **Optional**:
+  - `context`: filter by context — `ACCOUNT`, `RETAILER`, etc.
+  - `contextId`: context ID. Falls back to `FLUENT_RETAILER_ID` for `RETAILER` context, `0` for `ACCOUNT`.
+  - `outputFile`: file path to save the setting value/lobValue. When provided, writes content to file and returns only metadata (name, context, valueType, size) — keeps large manifests out of the LLM context. Parent directories are created automatically.
+  - `first`: max results (default: 10, max: 100)
+
+**Behavior with `outputFile`:**
+
+- **Single match** + `outputFile` → writes lobValue (or value) to the file, returns metadata + file path + byte size (NOT the content)
+- **Multiple matches** + `outputFile` → writes each setting to a separate file in the directory (named `<setting-name>.json`), returns per-file metadata
+- **No `outputFile`** → returns full setting data inline (may be large for manifests)
+- JSON content is automatically pretty-printed when saved to file
+
+**Example** — fetch a specific manifest setting to disk:
+
+```json
+{
+  "name": "fc.mystique.manifest.oms",
+  "context": "ACCOUNT",
+  "outputFile": "./accounts/SAGIRISH/manifests/backups/fc.mystique.manifest.oms.json"
+}
+```
+
+**Example** — list all manifest settings (wildcard):
+
+```json
+{
+  "name": "fc.mystique.manifest.%",
+  "context": "ACCOUNT"
+}
+```
+
+**Example** — download all manifests to directory:
+
+```json
+{
+  "name": "fc.mystique.manifest.%",
+  "outputFile": "./accounts/SAGIRISH/manifests/backups/"
+}
+```
+
+---
+
 ## `setting.upsert`
 
 Create or update a Fluent Commerce setting with upsert semantics.
@@ -1504,12 +1612,14 @@ Queries existing settings by `name` + `context` + `contextId` first. Creates if
 - **Optional**:
   - `lobValue`: large object value for JSON payloads > 4KB (mutually exclusive with `value`)
   - `contextId`: context ID (e.g., retailer ID). Defaults to `FLUENT_RETAILER_ID` for `RETAILER` context.
+  - `valueType`: explicit value type — `"STRING"`, `"LOB"`, or `"JSON"`. **Use `"JSON"` for Mystique manifest settings** (`fc.mystique.*`). Defaults to `"LOB"` when `lobValue` is provided, `"STRING"` when `value` is provided.
 
 **Key gotchas:**
 
 - `context` is a plain String (`"RETAILER"`), NOT an object
 - `contextId` is a separate Int field
 - For large JSON values (> 4KB), use `lobValue` instead of `value`
+- **For Mystique manifest settings, set `valueType: "JSON"`** — without it, defaults to `"LOB"` which breaks manifest parsing. The tool emits a `warning` field in the response when a `fc.mystique.manifest.*` name is used without `valueType: "JSON"`.
 - Returns `created: true/false` for audit trail
 
 **Example** — create a webhook URL setting:
@@ -1560,7 +1670,7 @@ Batch create or update multiple settings in one call.
 Processes up to 50 settings sequentially with individual error handling. Each setting is an independent upsert — failures on one setting don't block others.
 
 - **Required**:
-  - `settings`: array of setting objects (min 1, max 50), each with `name`, `value`, `context`, and optional `lobValue` and `contextId`
+  - `settings`: array of setting objects (min 1, max 50), each with `name`, `value`, `context`, and optional `lobValue`, `contextId`, and `valueType` (`"STRING"`, `"LOB"`, or `"JSON"`)
 
 **Example** — bulk create 3 settings:
 
@@ -1763,11 +1873,11 @@ Response (fail after timeout):
 
 | Category | Tools | Retry behavior |
 |------|----------|-------------|
-| Read operations | `event.get`, `event.list`, `event.flowInspect`, `metrics.query`, `metrics.healthCheck`, `metrics.sloReport`, `metrics.labelCatalog`, `metrics.topEvents`, `workflow.transitions`, `graphql.query` (query), `graphql.queryAll`, `batch.status`, `batch.batchStatus`, `batch.results`, `graphql.introspect`, `connection.test`, `entity.get`, `environment.discover`, `environment.validate`, `test.assert`, `plugin.list` | retry + backoff |
+| Read operations | `event.get`, `event.list`, `event.flowInspect`, `metrics.query`, `metrics.healthCheck`, `metrics.sloReport`, `metrics.labelCatalog`, `metrics.topEvents`, `workflow.transitions`, `workflow.get`, `workflow.list`, `graphql.query` (query), `graphql.queryAll`, `batch.status`, `batch.batchStatus`, `batch.results`, `graphql.introspect`, `connection.test`, `entity.get`, `setting.get`, `environment.discover`, `environment.validate`, `test.assert`, `plugin.list` | retry + backoff |
 | Write operations | `event.send`, `batch.create`, `batch.send`, `graphql.query` (mutation), `graphql.batchMutate`, `entity.create`, `entity.update`, `workflow.upload`, `setting.upsert`, `setting.bulkUpsert` | timeout-only (no automatic retry) |
 | Local validation / no API | `config.validate`, `health.ping`, `event.build`, `webhook.validate`, `workflow.diff`, `workflow.simulate` | not applicable |
 
-## Tool inventory summary (36 tools)
+## Tool inventory summary (39 tools)
 
 | Tool | Category | Requires SDK | Retry | Description |
 |------|----------|:------------:|:-----:|-------------|
@@ -1799,9 +1909,12 @@ Response (fail after timeout):
 | `entity.create` | Entity | Yes | No | Type-safe entity creation with field validation and gotcha knowledge (12 entity types) |
 | `entity.update` | Entity | Yes | No | Status-aware entity updates with optional transition validation |
 | `entity.get` | Entity | Yes | Yes | Unified entity lookup by ID or ref with optional edge inclusion |
+| `workflow.get` | Workflow Mgmt | Yes | Yes | Fetch specific workflow by entityType + entitySubtype via REST API |
+| `workflow.list` | Workflow Mgmt | Yes | Yes | List all workflows for a retailer (deduplicated to latest versions) |
 | `workflow.upload` | Workflow Mgmt | Yes | No | Deploy workflow JSON via REST API with structure validation |
 | `workflow.diff` | Workflow Mgmt | No | — | Compare two workflows — rulesets, statuses, risk assessment, mermaid output |
 | `workflow.simulate` | Workflow Mgmt | No | — | Static prediction of event outcomes from workflow JSON |
+| `setting.get` | Settings | Yes | Yes | Fetch settings by name (wildcards supported), optionally save to local file |
 | `setting.upsert` | Settings | Yes | No | Create or update a setting with upsert semantics |
 | `setting.bulkUpsert` | Settings | Yes | No | Batch create/update up to 50 settings with per-setting error handling |
 | `environment.discover` | Environment | Yes | Yes | Full environment snapshot — retailer, locations, networks, catalogues, settings, modules |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluentcommerce/fluent-mcp-extn",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "MCP (Model Context Protocol) extension server for Fluent Commerce. Exposes event dispatch, transition actions, GraphQL execution, Prometheus metrics, batch ingestion, and webhook validation as MCP tools.",
   "type": "module",
   "main": "dist/index.js",