@fluentcommerce/fluent-mcp-extn 0.2.1 → 0.3.1

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/<PROFILE>/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/<PROFILE>/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.1",
   "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",