@fluentcommerce/fluent-mcp-extn 0.2.1 → 0.3.1

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,155 @@ 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 raw = setting.lobValue ?? setting.value ?? "";
+        // lobValue may be a parsed object (valueType: JSON) or a string — normalize to string
+        const content = typeof raw === "string" ? raw : JSON.stringify(raw, null, 2);
+        // Try to pretty-print JSON content (if it's a JSON string, reformat)
+        let fileContent = content;
+        try {
+            const obj = JSON.parse(content);
+            fileContent = JSON.stringify(obj, 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 raw = setting.lobValue ?? setting.value ?? "";
+            // lobValue may be a parsed object (valueType: JSON) or a string — normalize to string
+            const content = typeof raw === "string" ? raw : JSON.stringify(raw, null, 2);
+            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 +523,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 +589,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 +601,7 @@ export async function handleSettingBulkUpsert(args, ctx) {
                     name: setting.name,
                     value: setting.value,
                     lobValue: setting.lobValue,
+                    valueType: setting.valueType,
                     context: setting.context,
                     contextId,
                 });