@fluentcommerce/fluent-mcp-extn 0.2.0 → 0.3.0

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/CONTRIBUTING.md

@@ -1,100 +1,100 @@
-# Contributing Guide
-
-This guide defines how to safely change `fluent-mcp-extn` while keeping
-behavior predictable for all clients.
-
-## 1) Core principles
-
-- Keep the extension **client-agnostic** (no client-specific names in code/docs).
-- Prefer **typed boundaries** and avoid unscoped `any`.
-- Keep tool responses consistent:
-  - success: `{ "ok": true, ... }`
-  - failure: `{ "ok": false, "error": { ... } }`
-- Route Fluent API calls through `FluentClientAdapter` only.
-
-## 2) Local setup
-
-```bash
-npm install
-npm run build
-npm test
-```
-
-## 3) Change workflow
-
-1. Make focused changes.
-2. Add or update tests.
-3. Run `npm run build`.
-4. Run `npm test`.
-5. Run `npm run e2e:smoke -- --skip-real-send` when touching tool runtime (requires `FLUENT_BASE_URL` + auth env, or `--profile`).
-6. Update docs if tool behavior/config changed.
-
-## 4) Adding a new tool (required checklist)
-
-When adding a tool, update all of the following:
-
-1. `src/tools.ts`
-   - add zod schema
-   - add `TOOL_DEFINITIONS` entry
-   - add handler branch
-2. `src/index.ts`
-   - add tool name to startup log list
-3. tests
-   - add/adjust unit tests in `test/`
-4. docs
-   - update `docs/TOOL_REFERENCE.md`
-   - update `docs/E2E_TESTING.md` if smoke flow changes
-
-## 5) Error handling standards
-
-- Throw `ToolError` for domain/runtime failures.
-- Do not return raw thrown errors directly.
-- Let `toToolFailure()` convert unknown errors into normalized error payloads.
-- Use specific error codes where possible (`AUTH_ERROR`, `VALIDATION_ERROR`, etc.).
-
-## 6) Resilience standards
-
-- Keep retry/timeout policy centralized via:
-  - `withTimeout()`
-  - `withRetry()`
-- Avoid per-tool custom retry loops.
-- Use config-driven values (`FLUENT_REQUEST_TIMEOUT_MS`, retry env vars).
-- Preserve idempotency boundaries:
-  - read operations can use retry/backoff
-  - non-idempotent write operations must not auto-retry
-- Keep SDK retry disabled and adapter retry as the single control plane.
-
-## 7) Security and secrets
-
-- Never log secrets or token values.
-- Use redacted summaries via `toSafeConfigSummary()`.
-- Prefer profile, `TOKEN_COMMAND`, or OAuth over static tokens in shared environments.
-
-## 8) Documentation standards
-
-- Keep docs concise and task-oriented.
-- Include at least one valid request example when changing tool inputs.
-- Update all cross-links in `README.md` when adding new docs.
-- For behavior changes, update all affected docs end-to-end:
-  - `README.md`
-  - `docs/TOOL_REFERENCE.md`
-  - `docs/RUNBOOK.md`
-  - `docs/E2E_TESTING.md`
-
-## 9) Pull request quality bar
-
-A change is ready only if:
-
-- build passes
-- tests pass
-- smoke runner passes (or is intentionally skipped with rationale)
-- no lint errors introduced
-- docs updated for behavior/interface changes
-- no client-specific wording added
-
-## 10) CI expectations
-
-- CI workflow file: `.github/workflows/ci.yml`
-- `build-and-test` must pass for every PR.
-- `e2e-smoke` is manual (`workflow_dispatch`) and requires repository secrets.
-
+# Contributing Guide
+
+This guide defines how to safely change `fluent-mcp-extn` while keeping
+behavior predictable for all clients.
+
+## 1) Core principles
+
+- Keep the extension **client-agnostic** (no client-specific names in code/docs).
+- Prefer **typed boundaries** and avoid unscoped `any`.
+- Keep tool responses consistent:
+  - success: `{ "ok": true, ... }`
+  - failure: `{ "ok": false, "error": { ... } }`
+- Route Fluent API calls through `FluentClientAdapter` only.
+
+## 2) Local setup
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## 3) Change workflow
+
+1. Make focused changes.
+2. Add or update tests.
+3. Run `npm run build`.
+4. Run `npm test`.
+5. Run `npm run e2e:smoke -- --skip-real-send` when touching tool runtime (requires `FLUENT_BASE_URL` + auth env, or `--profile`).
+6. Update docs if tool behavior/config changed.
+
+## 4) Adding a new tool (required checklist)
+
+When adding a tool, update all of the following:
+
+1. `src/tools.ts`
+   - add zod schema
+   - add `TOOL_DEFINITIONS` entry
+   - add handler branch
+2. `src/index.ts`
+   - add tool name to startup log list
+3. tests
+   - add/adjust unit tests in `test/`
+4. docs
+   - update `docs/TOOL_REFERENCE.md`
+   - update `docs/E2E_TESTING.md` if smoke flow changes
+
+## 5) Error handling standards
+
+- Throw `ToolError` for domain/runtime failures.
+- Do not return raw thrown errors directly.
+- Let `toToolFailure()` convert unknown errors into normalized error payloads.
+- Use specific error codes where possible (`AUTH_ERROR`, `VALIDATION_ERROR`, etc.).
+
+## 6) Resilience standards
+
+- Keep retry/timeout policy centralized via:
+  - `withTimeout()`
+  - `withRetry()`
+- Avoid per-tool custom retry loops.
+- Use config-driven values (`FLUENT_REQUEST_TIMEOUT_MS`, retry env vars).
+- Preserve idempotency boundaries:
+  - read operations can use retry/backoff
+  - non-idempotent write operations must not auto-retry
+- Keep SDK retry disabled and adapter retry as the single control plane.
+
+## 7) Security and secrets
+
+- Never log secrets or token values.
+- Use redacted summaries via `toSafeConfigSummary()`.
+- Prefer profile, `TOKEN_COMMAND`, or OAuth over static tokens in shared environments.
+
+## 8) Documentation standards
+
+- Keep docs concise and task-oriented.
+- Include at least one valid request example when changing tool inputs.
+- Update all cross-links in `README.md` when adding new docs.
+- For behavior changes, update all affected docs end-to-end:
+  - `README.md`
+  - `docs/TOOL_REFERENCE.md`
+  - `docs/RUNBOOK.md`
+  - `docs/E2E_TESTING.md`
+
+## 9) Pull request quality bar
+
+A change is ready only if:
+
+- build passes
+- tests pass
+- smoke runner passes (or is intentionally skipped with rationale)
+- no lint errors introduced
+- docs updated for behavior/interface changes
+- no client-specific wording added
+
+## 10) CI expectations
+
+- CI workflow file: `.github/workflows/ci.yml`
+- `build-and-test` must pass for every PR.
+- `e2e-smoke` is manual (`workflow_dispatch`) and requires repository secrets.
+