@diviops/mcp-server 1.5.18 → 1.5.20

package/README.md

@@ -84,6 +84,10 @@ Additional **conditionally-registered Pro tools** appear only on sites that have
 |----------|------------------|------------|
 | FluentCart reads (V1) | Pro plugin + FluentCart installed + module enabled | `diviops_fc_product_list`, `diviops_fc_product_get` |
 | FluentCart simple product writes (V2) | Pro plugin + FluentCart installed + module enabled | `diviops_fc_product_create`, `diviops_fc_product_update`, `diviops_fc_product_delete` |
+| FluentCart variation read/write (V3) | Pro plugin + FluentCart installed + module enabled | `diviops_fc_variation_list`, `diviops_fc_variation_update` |
+| FluentCart license-settings read/write (V3) | Pro plugin + FluentCart Pro installed + module enabled | `diviops_fc_license_settings_get`, `diviops_fc_license_settings_update` |
+| FluentCart order readback + guarded mark-paid (V3.1) | Pro plugin + FluentCart installed + module enabled | `diviops_fc_order_list`, `diviops_fc_order_get`, `diviops_fc_order_mark_paid` |
+| FluentCart license readback (V3.1) | Pro plugin + FluentCart Pro installed + module enabled | `diviops_fc_license_list`, `diviops_fc_license_get`, `diviops_fc_license_activations_list` |
 
 When the gates are not satisfied, the tools simply don't appear on the MCP surface — no error envelope, no missing-capability hint. See the `diviops-fluentcart` skill bundle for the operator-side guide.
 

package/dist/index.js

@@ -3328,6 +3328,571 @@ function registerProTools() {
             ],
         };
     }, { target: "fluentcart", capabilityKey: "fluentcart_product_delete" });
+    // ── V3 — variation read/write + license-settings read/write ────────
+    //
+    // V3 expands the FCP authoring surface so a draft simple-product catalog
+    // can represent ADR-005 commercial shape: annual rows become subscription
+    // products, lifetime rows stay onetime, and per-tier activation_limit
+    // is writable. Activation limits live in `ProductMeta.license_settings`
+    // per FluentCart Pro source (NOT variation `other_info`), so license
+    // settings have their own dedicated read/write tools.
+    //
+    // V3 stays inside the simple-product default-variation contract:
+    // no multi-variation create/delete, no signup-fee writes,
+    // no license activation flow, no update-ZIP / readme / banner config.
+    // diviops_fc_variation_list — POST /diviops/v1/pro/fluentcart/products/{id}/variations
+    registerProTool("diviops_fc_variation_list", {
+        description: "List FluentCart Pro variations for a product (Pro tier; V3; requires FluentCart Pro installed + activated). Read-only. Returns every variation row attached to the product with its subscription shape (payment_type, other_info.repeat_interval/times/trial_days/manage_setup_fee) and a license-settings projection when ProductMeta.license_settings is configured. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; success payload is { product_id, variation_type, default_variation_id, variations: VariationRow[], variations_count }. Each VariationRow carries { id, post_id, variation_title, sku, payment_type, item_price, compare_price, fulfillment_type, stock_status, manage_stock, available, other_info: { ...all stored keys... }, license: { activation_limit, validity: { unit, value } } | null }. Unit convention: item_price and compare_price are stored cents (e.g. 1900 = $19.00). compare_price is null when FCP stores the no-compare sentinel 0; sku is null when the column is SQL NULL OR an empty string. license is null when the product has no license_settings; otherwise activation_limit is null/'' (unset), 0 (unlimited per FluentCart Pro License::getActivationLimit), or a positive integer (max activations). validity.unit is one of: lifetime/day/week/month/year. Error codes: invalid_input (400) when id is not a positive integer; not_found (404) when the product does not exist; fluentcart.module_inactive (412); fluentcart.query_failed (500). Idempotency: read-only.",
+        inputSchema: {
+            product_id: z
+                .number()
+                .int()
+                .positive()
+                .describe("FluentCart product ID (the post ID of the fluent_products CPT entry)."),
+        },
+        annotations: { idempotentHint: true },
+        _meta: { idempotent: "true" },
+    }, async ({ product_id }) => {
+        const result = await wp.requestEnveloped(`/pro/fluentcart/products/${product_id}/variations`, { method: "POST" });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: serializeEnvelope(result, "diviops_fc_variation_list"),
+                },
+            ],
+        };
+    }, { target: "fluentcart", capabilityKey: "fluentcart_variation_list" });
+    // diviops_fc_variation_update — POST /diviops/v1/pro/fluentcart/products/{product_id}/variations/{variation_id}/update
+    registerProTool("diviops_fc_variation_update", {
+        description: "Update the default variation of a simple FluentCart Pro product (Pro tier; V3; requires FluentCart Pro installed + activated). V3 scope: writes the product's default variation only; refuses non-simple products and non-default variations with `fluentcart.unsupported_product_shape` (HTTP 422). Multi-variation create/delete remains out of scope. Accepts partial updates on price, compare_price, sku, payment_type, and the subscription shape (repeat_interval, times, trial_days, manage_setup_fee). Switching `payment_type: \"subscription\"` requires `repeat_interval` (yearly/half_yearly/quarterly/monthly/weekly/daily) — either supplied in the same call or already stored. Switching to `onetime` strips the subscription-only keys from other_info, matching ProductVariationRequest::beforeValidation. `manage_setup_fee: \"yes\"` requires signup_fee + signup_fee_name which are out of scope for V3 (use FluentCart admin UI for setup fees); only `manage_setup_fee: \"no\"` is accepted. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; apply-mode success payload is { product_id, variation_id, changed_fields[], variation: VariationRow, product_price_range: { min_price, max_price } | null } (or { noop: true, product_id, variation_id, variation } when nothing changes). VariationRow mirrors the diviops_fc_variation_list shape — sku, item_price, compare_price, payment_type, other_info, license round-trip without a follow-up read. Unit asymmetry: write inputs (price, compare_price) are currency units (e.g. 19.00); VariationRow returns item_price + compare_price in stored cents. Error codes: invalid_input (400); not_found (404); fluentcart.unsupported_product_shape (422); fluentcart.sku_conflict (409); fluentcart.module_inactive (412); fluentcart.command_failed (500). Idempotency: conditional — identical repeat is a no-op." +
+            DRY_RUN_DESC_SUFFIX,
+        inputSchema: {
+            product_id: z
+                .number()
+                .int()
+                .positive()
+                .describe("FluentCart product ID (the post ID of the fluent_products CPT entry)."),
+            variation_id: z
+                .number()
+                .int()
+                .positive()
+                .describe("FluentCart variation ID. Must be the product's default variation (V3 constraint)."),
+            price: z
+                .number()
+                .min(0)
+                .optional()
+                .describe("Variation item_price in currency units (e.g. 19.00). Non-negative."),
+            compare_price: z
+                .number()
+                .min(0)
+                .optional()
+                .describe("Variation compare-at price in currency units. Must be ≥ price when both provided."),
+            sku: z
+                .string()
+                .optional()
+                .describe("Variation SKU. Must be unique across all FluentCart variations and at most 30 characters. Empty string clears the SKU (reads back as null)."),
+            payment_type: z
+                .enum(["onetime", "subscription"])
+                .optional()
+                .describe("Variation payment_type. Switching to 'subscription' requires repeat_interval. Switching to 'onetime' strips subscription-only fields from other_info."),
+            repeat_interval: z
+                .enum([
+                "yearly",
+                "half_yearly",
+                "quarterly",
+                "monthly",
+                "weekly",
+                "daily",
+            ])
+                .optional()
+                .describe("Subscription billing interval. Required when switching to payment_type='subscription' unless already stored. For ADR-005 annual rows use 'yearly'."),
+            times: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Number of subscription billing cycles. 0 = indefinite (default for V3 subscription rows)."),
+            trial_days: z
+                .number()
+                .int()
+                .min(0)
+                .max(365)
+                .optional()
+                .describe("Trial-period length in days (0-365)."),
+            manage_setup_fee: z
+                .enum(["no"])
+                .optional()
+                .describe("Setup-fee mode. V3 only accepts 'no' — manage_setup_fee='yes' requires signup_fee + signup_fee_name which are out of scope for V3."),
+            dry_run: DRY_RUN_FIELD,
+        },
+        annotations: { idempotentHint: false },
+        _meta: { idempotent: "conditional" },
+    }, async ({ product_id, variation_id, price, compare_price, sku, payment_type, repeat_interval, times, trial_days, manage_setup_fee, dry_run, }) => {
+        const body = {};
+        if (price !== undefined)
+            body.price = price;
+        if (compare_price !== undefined)
+            body.compare_price = compare_price;
+        if (sku !== undefined)
+            body.sku = sku;
+        if (payment_type !== undefined)
+            body.payment_type = payment_type;
+        if (repeat_interval !== undefined)
+            body.repeat_interval = repeat_interval;
+        if (times !== undefined)
+            body.times = times;
+        if (trial_days !== undefined)
+            body.trial_days = trial_days;
+        if (manage_setup_fee !== undefined)
+            body.manage_setup_fee = manage_setup_fee;
+        if (dry_run !== undefined)
+            body.dry_run = dry_run;
+        const result = await wp.requestEnveloped(`/pro/fluentcart/products/${product_id}/variations/${variation_id}/update`, { method: "POST", body });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: serializeEnvelope(result, "diviops_fc_variation_update"),
+                },
+            ],
+        };
+    }, { target: "fluentcart", capabilityKey: "fluentcart_variation_update" });
+    // diviops_fc_license_settings_get — POST /diviops/v1/pro/fluentcart/products/{id}/license-settings
+    registerProTool("diviops_fc_license_settings_get", {
+        description: "Read the per-product FluentCart Pro license-settings projection (Pro tier; V3; requires FluentCart Pro installed + activated). FluentCart Pro stores license settings in `ProductMeta` under meta_key='license_settings'; this tool reads that meta row and joins it against the product's variations so each variation surfaces with its current activation_limit + validity. Read-only. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; success payload is { product_id, enabled: boolean, version, prefix, variations: [ { variation_id, title, activation_limit, validity: { unit, value } | null } ] }. Storage semantics: `enabled` is stored as 'yes'/'no' in FCP and projected to boolean here. `activation_limit` is null/'' (unconfigured), 0 (unlimited per FluentCart Pro License::getActivationLimit), or a positive integer. `validity.unit` is one of lifetime/day/week/month/year. Variations the product has but license_settings doesn't mention surface with `activation_limit: null` and `validity: null`. Variations license_settings mentions that no longer exist on the product are filtered out — only the live variation set is returned. Error codes: invalid_input (400) when id is not a positive integer; not_found (404) when the product does not exist; fluentcart.module_inactive (412); fluentcart.query_failed (500). Idempotency: read-only.",
+        inputSchema: {
+            product_id: z
+                .number()
+                .int()
+                .positive()
+                .describe("FluentCart product ID (the post ID of the fluent_products CPT entry)."),
+        },
+        annotations: { idempotentHint: true },
+        _meta: { idempotent: "true" },
+    }, async ({ product_id }) => {
+        const result = await wp.requestEnveloped(`/pro/fluentcart/products/${product_id}/license-settings`, { method: "POST" });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: serializeEnvelope(result, "diviops_fc_license_settings_get"),
+                },
+            ],
+        };
+    }, { target: "fluentcart", capabilityKey: "fluentcart_license_settings_get" });
+    // diviops_fc_license_settings_update — POST /diviops/v1/pro/fluentcart/products/{id}/license-settings/update
+    registerProTool("diviops_fc_license_settings_update", {
+        description: "Write the per-product FluentCart Pro license-settings ProductMeta row (Pro tier; V3; requires FluentCart Pro installed + activated). Authors `enabled`, `version`, `prefix`, and per-variation `activation_limit` + `validity` — the storage shape FluentCart Pro reads via LicenseGenerationHandler when an order is placed. V3 explicitly skips configuring update-ZIP `global_update_file`, `wp` readme/banner/icon, downloadables, and the license-activation API; those fields are preserved when present but not authored. Refuses bundle products with `fluentcart.unsupported_product_shape` (HTTP 422). Inputs (all optional except product_id; partial updates supported): `enabled` (boolean — projected to FCP's 'yes'/'no' on write), `version` (required when enabling; max 50 chars), `prefix` (max 20 chars), `variations` (array of { variation_id (required), activation_limit (integer ≥ 0 or null; 0 = unlimited per FluentCart Pro License::getActivationLimit), validity (optional { unit: lifetime/day/week/month/year, value: positive integer } or null to auto-derive) }). When `validity` is omitted on a variation, the validity is derived from the variation's payment_type: subscription+yearly → { unit: 'year', value: 1 }; onetime → { unit: 'lifetime', value: 1 }. When `enabled: true` and the product carries variations, every variation must end up with a non-empty validity.unit. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; apply-mode success payload is { product_id, changed_fields[], license_settings: <same shape as diviops_fc_license_settings_get> } (or { noop: true, product_id, license_settings } on no-op). Error codes: invalid_input (400) when any field violates the constraints (unknown variation_id, negative activation_limit, missing version when enabling, missing validity.unit when enabling, bad enum value); not_found (404) when the product does not exist; fluentcart.unsupported_product_shape (422) on bundle products; fluentcart.module_inactive (412); fluentcart.command_failed (500). Idempotency: conditional — identical repeat is a no-op." +
+            DRY_RUN_DESC_SUFFIX,
+        inputSchema: {
+            product_id: z
+                .number()
+                .int()
+                .positive()
+                .describe("FluentCart product ID (the post ID of the fluent_products CPT entry)."),
+            enabled: z
+                .boolean()
+                .optional()
+                .describe("Toggle FCP license-settings enablement. Stored as 'yes'/'no' in FCP. When true, version is required (use '1.0.0-beta' for the dogfood catalog)."),
+            version: z
+                .string()
+                .max(50)
+                .optional()
+                .describe("License-settings version string (max 50 chars). Required when enabling. Recommended: '1.0.0-beta' for a beta-cohort catalog."),
+            prefix: z
+                .string()
+                .max(20)
+                .optional()
+                .describe("License-key prefix (max 20 chars). Recommended: 'DOP' for DiviOps products."),
+            variations: z
+                .array(z.object({
+                variation_id: z
+                    .number()
+                    .int()
+                    .positive()
+                    .describe("Target variation ID; must belong to this product."),
+                activation_limit: z
+                    .number()
+                    .int()
+                    .min(0)
+                    .nullable()
+                    .optional()
+                    .describe("Activation limit. 0 = unlimited (per FluentCart Pro License::getActivationLimit). null clears the configured limit."),
+                validity: z
+                    .object({
+                    unit: z.enum(["lifetime", "day", "week", "month", "year"]),
+                    value: z.number().int().positive(),
+                })
+                    .nullable()
+                    .optional()
+                    .describe("Validity period. When omitted, derived from the variation's payment_type (subscription+yearly → year/1; onetime → lifetime/1). When null, force-rederived from current variation state."),
+            }))
+                .optional()
+                .describe("Per-variation license configuration. Each entry's variation_id must belong to the product. Omitted variations preserve their existing license_settings."),
+            dry_run: DRY_RUN_FIELD,
+        },
+        annotations: { idempotentHint: false },
+        _meta: { idempotent: "conditional" },
+    }, async ({ product_id, enabled, version, prefix, variations, dry_run, }) => {
+        const body = {};
+        if (enabled !== undefined)
+            body.enabled = enabled;
+        if (version !== undefined)
+            body.version = version;
+        if (prefix !== undefined)
+            body.prefix = prefix;
+        if (variations !== undefined)
+            body.variations = variations;
+        if (dry_run !== undefined)
+            body.dry_run = dry_run;
+        const result = await wp.requestEnveloped(`/pro/fluentcart/products/${product_id}/license-settings/update`, { method: "POST", body });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: serializeEnvelope(result, "diviops_fc_license_settings_update"),
+                },
+            ],
+        };
+    }, {
+        target: "fluentcart",
+        capabilityKey: "fluentcart_license_settings_update",
+    });
+    // ── V3.1 — order/license/activation read + guarded mark-paid ───────
+    //
+    // FluentCart commerce-artifact readback surface plus a single
+    // mutating tool: a guarded offline mark-paid that mirrors FCP's
+    // OrderController::markAsPaid. Lifts the local checkout/license
+    // smoke off of eval-file PHP probes.
+    // diviops_fc_order_list — POST /diviops/v1/pro/fluentcart/orders
+    registerProTool("diviops_fc_order_list", {
+        description: "List FluentCart orders for commerce dogfooding / smoke baselines (Pro tier; V3.1; requires FluentCart installed + activated). Returns a paginated summary with order identity (id, status, payment_status), gateway info (payment_method + payment_method_title, mode), totals (currency, total_amount, total_paid), fulfillment_type, type (payment/subscription), customer (customer_id + customer_email), item_count, license_count, and timestamps (created_at, updated_at, completed_at). Filterable by status, payment_status, payment_method, product_id, customer_email, and mode (test/live). Read-only. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; the success payload is { orders: OrderSummary[], pagination: { page, per_page, total, total_pages }, filters: { ... } }. Error codes: invalid_input (HTTP 400) when status/payment_status/mode is out of range; fluentcart.module_inactive (HTTP 412); fluentcart.query_failed (HTTP 500). Use this alongside diviops_fc_order_get / diviops_fc_license_list to verify a smoke run without raw SQL probes.",
+        inputSchema: {
+            page: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .default(1)
+                .describe("Page number, 1-indexed. Default 1."),
+            per_page: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .default(20)
+                .describe("Page size. Default 20, clamped to a max of 100."),
+            status: z
+                .enum([
+                "on-hold",
+                "pending",
+                "processing",
+                "completed",
+                "canceled",
+                "refunded",
+                "failed",
+                "draft",
+            ])
+                .optional()
+                .describe("Order status filter (fct_orders.status). Match exact values such as 'completed' or 'on-hold'."),
+            payment_status: z
+                .enum([
+                "pending",
+                "paid",
+                "partially_paid",
+                "partially_refunded",
+                "refunded",
+                "failed",
+            ])
+                .optional()
+                .describe("Payment status filter (fct_orders.payment_status)."),
+            payment_method: z
+                .string()
+                .optional()
+                .describe("Exact-match payment_method (e.g. 'offline_payment', 'stripe'). Case-sensitive — FluentCart stores gateway slugs verbatim."),
+            product_id: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("FluentCart product ID (post_id of the fluent_products CPT entry). Filters to orders with at least one matching order item."),
+            customer_email: z
+                .string()
+                .optional()
+                .describe("Filter to orders whose customer record has this email (exact match)."),
+            mode: z
+                .enum(["test", "live"])
+                .optional()
+                .describe("Filter to test-mode or live-mode orders. Useful for smoke runs to isolate the test gateway corpus."),
+        },
+        annotations: { idempotentHint: true },
+        _meta: { idempotent: "true" },
+    }, async ({ page, per_page, status, payment_status, payment_method, product_id, customer_email, mode, }) => {
+        const body = {};
+        if (page !== undefined)
+            body.page = page;
+        if (per_page !== undefined)
+            body.per_page = per_page;
+        if (status !== undefined)
+            body.status = status;
+        if (payment_status !== undefined)
+            body.payment_status = payment_status;
+        if (payment_method !== undefined)
+            body.payment_method = payment_method;
+        if (product_id !== undefined)
+            body.product_id = product_id;
+        if (customer_email !== undefined)
+            body.customer_email = customer_email;
+        if (mode !== undefined)
+            body.mode = mode;
+        const result = await wp.requestEnveloped("/pro/fluentcart/orders", {
+            method: "POST",
+            body,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: serializeEnvelope(result, "diviops_fc_order_list"),
+                },
+            ],
+        };
+    }, { target: "fluentcart", capabilityKey: "fluentcart_order_list" });
+    // diviops_fc_order_get — POST /diviops/v1/pro/fluentcart/orders/{id}
+    registerProTool("diviops_fc_order_get", {
+        description: "Fetch a single FluentCart order with line items, transactions, and related license IDs (Pro tier; V3.1; requires FluentCart installed + activated). Read-only. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; the success payload is { order: OrderSummary, items: OrderItem[], transactions: Transaction[], license_ids: number[] }. OrderItem includes id, post_id (product CPT post_id), object_id (variation_id), title, quantity, unit_price, line_total, payment_type, fulfillment_type. Transaction includes id, status, payment_method, payment_mode, transaction_type, total, currency, created_at. license_ids carries the IDs of any fct_licenses rows tied to this order (use diviops_fc_license_get to fetch each row's redacted shape). Does NOT expose payment credentials, gateway secrets, or full license keys. Error codes: invalid_input (HTTP 400) when id is not a positive integer; not_found (HTTP 404) when no order matches; fluentcart.module_inactive (HTTP 412); fluentcart.query_failed (HTTP 500).",
+        inputSchema: {
+            id: z
+                .number()
+                .int()
+                .positive()
+                .describe("FluentCart order ID (fct_orders.id; for the local smoke runbook this is the order receipt anchor)."),
+        },
+        annotations: { idempotentHint: true },
+        _meta: { idempotent: "true" },
+    }, async ({ id }) => {
+        const result = await wp.requestEnveloped(`/pro/fluentcart/orders/${id}`, { method: "POST" });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: serializeEnvelope(result, "diviops_fc_order_get"),
+                },
+            ],
+        };
+    }, { target: "fluentcart", capabilityKey: "fluentcart_order_get" });
+    // diviops_fc_order_mark_paid — POST /diviops/v1/pro/fluentcart/orders/{id}/mark-paid
+    registerProTool("diviops_fc_order_mark_paid", {
+        description: "Guarded local/offline mark-paid for a FluentCart order (Pro tier; V3.1; requires FluentCart installed + activated). Mirrors the canonical `FluentCart\\App\\Http\\Controllers\\OrderController::markAsPaid` sequence — updates the pending offline transaction, flips payment_status to 'paid' (unless partially_refunded), flips order status to 'processing' (and 'completed' for digital fulfillment), then dispatches `OrderPaid` (which fires the `fluent_cart/order_paid` WordPress action, the listener `LicenseGenerationHandler::maybeGenerateLicensesOnPurchaseSuccess` hangs off of) plus `OrderStatusUpdated`. Does NOT directly insert license rows — license generation is a side effect of the dispatched event, exactly like the FCP admin path. Refuses non-offline gateways (anything other than `payment_method='offline_payment'`) with `fluentcart.unsupported_payment_method` (HTTP 422) — this slice is for local/test/COD smokes only. Refuses canceled orders with `fluentcart.order_canceled` (HTTP 422). Already-paid orders are repeat-safe: returns `ok:true` with `data.already_paid: true` (no second event fires). **dry_run defaults to TRUE** for safety; apply requires `dry_run:false` PLUS `confirm_order_id` + `confirm_payment_method` + `confirm_due_amount` matching current state. Dry-run payload: { dry_run:true, plan: { summary, changes[] (payment_status, status, total_paid, transaction), warnings[] }, events: ['fluent_cart/order_paid', 'fluent_cart/order_status_updated'], order_id, licenses_before }. Apply payload: { order: OrderSummary (post-mutation), transaction: TransactionSummary, events_fired: string[], licenses_before, licenses_after, licenses_created, license_ids: number[], licenses: LicenseRedactedSummary[] (no full keys). Error codes: invalid_input (400) when id/confirmation fields are wrong; not_found (404); fluentcart.order_canceled (422); fluentcart.unsupported_payment_method (422); fluentcart.module_inactive (412); fluentcart.command_failed (500). Idempotency: repeat-safe via already_paid sentinel." +
+            " Pass dry_run: false plus the confirm_* fields to apply.",
+        inputSchema: {
+            id: z
+                .number()
+                .int()
+                .positive()
+                .describe("FluentCart order ID (fct_orders.id) to mark paid."),
+            dry_run: z
+                .boolean()
+                .optional()
+                .default(true)
+                .describe("When true (default), return the change plan without mutating state. Apply requires explicit dry_run: false + the confirm_* fields."),
+            confirm_order_id: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Apply-mode confirmation: must equal `id`. Prevents accidentally marking the wrong order paid."),
+            confirm_payment_method: z
+                .string()
+                .optional()
+                .describe("Apply-mode confirmation: must equal the order's current payment_method (e.g. 'offline_payment')."),
+            confirm_due_amount: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Apply-mode confirmation: must equal (total_amount - total_paid) in stored units (cents). Inspect via diviops_fc_order_get."),
+            mark_paid_note: z
+                .string()
+                .optional()
+                .describe("Optional sanitize_text_field note to attach to the order's `note` column. Mirrors the admin mark-paid form field."),
+        },
+        annotations: { idempotentHint: false },
+        _meta: { idempotent: "conditional" },
+    }, async ({ id, dry_run, confirm_order_id, confirm_payment_method, confirm_due_amount, mark_paid_note, }) => {
+        const body = {};
+        // dry_run defaults to true at the MCP level — pass through whatever
+        // the caller sent so the plugin can apply the same default.
+        if (dry_run !== undefined)
+            body.dry_run = dry_run;
+        else
+            body.dry_run = true;
+        if (confirm_order_id !== undefined)
+            body.confirm_order_id = confirm_order_id;
+        if (confirm_payment_method !== undefined)
+            body.confirm_payment_method = confirm_payment_method;
+        if (confirm_due_amount !== undefined)
+            body.confirm_due_amount = confirm_due_amount;
+        if (mark_paid_note !== undefined)
+            body.mark_paid_note = mark_paid_note;
+        const result = await wp.requestEnveloped(`/pro/fluentcart/orders/${id}/mark-paid`, { method: "POST", body });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: serializeEnvelope(result, "diviops_fc_order_mark_paid"),
+                },
+            ],
+        };
+    }, { target: "fluentcart", capabilityKey: "fluentcart_order_mark_paid" });
+    // diviops_fc_license_list — POST /diviops/v1/pro/fluentcart/licenses
+    registerProTool("diviops_fc_license_list", {
+        description: "List FluentCart Pro licenses (Pro tier; V3.1; requires FluentCart Pro + Licensing module). Read-only. Filterable by product_id, variation_id, order_id, customer_id, status (active/inactive/disabled/expired/in_trial). License keys are NEVER returned in full — every row carries `redacted_key` only (first 4 + last 4 with ellipsis); use diviops_fc_license_get with explicit secret-handling opt-in if a full key is required for an authorized integration test. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; the success payload is { licenses: LicenseSummary[], pagination: { page, per_page, total, total_pages }, filters: { ... } }. LicenseSummary includes id, status, product_id, variation_id, order_id, customer_id, subscription_id, limit (0 = unlimited per License::getActivationLimit), activation_count, expiration_date, created_at, updated_at, redacted_key. Error codes: invalid_input (HTTP 400) when status is out of range; fluentcart.module_inactive (HTTP 412); fluentcart.licensing_unavailable (HTTP 412) when FluentCart Pro's Licensing module is absent; fluentcart.query_failed (HTTP 500).",
+        inputSchema: {
+            page: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .default(1)
+                .describe("Page number, 1-indexed. Default 1."),
+            per_page: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .default(20)
+                .describe("Page size. Default 20, clamped to a max of 100."),
+            product_id: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Filter to licenses for this FluentCart product ID."),
+            variation_id: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Filter to licenses for this FluentCart variation ID."),
+            order_id: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Filter to licenses issued by this order ID."),
+            customer_id: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Filter to licenses owned by this customer ID."),
+            status: z
+                .enum(["active", "inactive", "disabled", "expired", "in_trial"])
+                .optional()
+                .describe("License status (fct_licenses.status). 'active' is the healthy default."),
+        },
+        annotations: { idempotentHint: true },
+        _meta: { idempotent: "true" },
+    }, async ({ page, per_page, product_id, variation_id, order_id, customer_id, status, }) => {
+        const body = {};
+        if (page !== undefined)
+            body.page = page;
+        if (per_page !== undefined)
+            body.per_page = per_page;
+        if (product_id !== undefined)
+            body.product_id = product_id;
+        if (variation_id !== undefined)
+            body.variation_id = variation_id;
+        if (order_id !== undefined)
+            body.order_id = order_id;
+        if (customer_id !== undefined)
+            body.customer_id = customer_id;
+        if (status !== undefined)
+            body.status = status;
+        const result = await wp.requestEnveloped("/pro/fluentcart/licenses", {
+            method: "POST",
+            body,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: serializeEnvelope(result, "diviops_fc_license_list"),
+                },
+            ],
+        };
+    }, { target: "fluentcart", capabilityKey: "fluentcart_license_list" });
+    // diviops_fc_license_get — POST /diviops/v1/pro/fluentcart/licenses/{id}
+    registerProTool("diviops_fc_license_get", {
+        description: "Fetch a single FluentCart Pro license by ID (Pro tier; V3.1; requires FluentCart Pro + Licensing module). Read-only by default. The default response redacts the license key to `redacted_key` only (first 4 + last 4 with ellipsis). To surface the full key, pass BOTH `include_license_key: true` AND `confirm_secret_handling: true` — the response then carries `license.license_key` plus `_meta.contains_secret: true` naming the secret field. **Full license keys must never be pasted into PRs, issues, Slack, or any external surface.** Returns the standardized envelope { ok, data?, error: { code, message, hint? } }. Success payload: { license: { id, status, product_id, variation_id, order_id, customer_id, subscription_id, limit, activation_count, expiration_date, created_at, updated_at, redacted_key, license_key? } }. limit semantics: 0 = unlimited per License::getActivationLimit; positive integers are the actual activation cap. Error codes: invalid_input (HTTP 400) when id is non-positive or include_license_key was passed without confirm_secret_handling; not_found (HTTP 404); fluentcart.module_inactive (HTTP 412); fluentcart.licensing_unavailable (HTTP 412); fluentcart.query_failed (HTTP 500).",
+        inputSchema: {
+            id: z
+                .number()
+                .int()
+                .positive()
+                .describe("FluentCart license ID (fct_licenses.id)."),
+            include_license_key: z
+                .boolean()
+                .optional()
+                .describe("Opt-in: include the full unredacted license key in the response. Requires confirm_secret_handling: true. Default: redacted-only."),
+            confirm_secret_handling: z
+                .boolean()
+                .optional()
+                .describe("Required alongside include_license_key: true. Acknowledges that full license keys must not be pasted into reports, PRs, issues, or external chat surfaces."),
+        },
+        annotations: { idempotentHint: true },
+        _meta: { idempotent: "true" },
+    }, async ({ id, include_license_key, confirm_secret_handling, }) => {
+        const body = {};
+        if (include_license_key !== undefined)
+            body.include_license_key = include_license_key;
+        if (confirm_secret_handling !== undefined)
+            body.confirm_secret_handling = confirm_secret_handling;
+        const result = await wp.requestEnveloped(`/pro/fluentcart/licenses/${id}`, { method: "POST", body });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: serializeEnvelope(result, "diviops_fc_license_get"),
+                },
+            ],
+        };
+    }, { target: "fluentcart", capabilityKey: "fluentcart_license_get" });
+    // diviops_fc_license_activations_list — POST /diviops/v1/pro/fluentcart/licenses/{id}/activations
+    registerProTool("diviops_fc_license_activations_list", {
+        description: "List a FluentCart license's activation rows (Pro tier; V3.1; requires FluentCart Pro + Licensing module). Read-only. Returns one row per `fct_license_activations` entry for the license, including the joined `fct_license_sites.site_url` (the NORMALIZED form — scheme + trailing slash + `www.` prefix stripped per LicenseHelper::sanitizeSiteUrl — not the raw URL the consumer submitted). Filterable by status (active/inactive/deactivated). License keys are NEVER returned by this endpoint. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; success payload: { license_id, activations: Activation[], count, filters: { status } }. Activation row: id, license_id, site_id, site_url, status, is_local, product_id, variation_id, activation_method, last_update_date, last_update_version, created_at, updated_at. Error codes: invalid_input (HTTP 400); not_found (HTTP 404) when the license doesn't exist; fluentcart.module_inactive (HTTP 412); fluentcart.licensing_unavailable (HTTP 412); fluentcart.query_failed (HTTP 500). Useful for smoke verification (count + site_url presence) and for the activation-cap test described in the diviops-fluentcart skill.",
+        inputSchema: {
+            license_id: z
+                .number()
+                .int()
+                .positive()
+                .describe("FluentCart license ID whose activation rows to list (fct_licenses.id)."),
+            status: z
+                .enum(["active", "inactive", "deactivated"])
+                .optional()
+                .describe("Activation row status filter (fct_license_activations.status)."),
+        },
+        annotations: { idempotentHint: true },
+        _meta: { idempotent: "true" },
+    }, async ({ license_id, status, }) => {
+        const body = {};
+        if (status !== undefined)
+            body.status = status;
+        const result = await wp.requestEnveloped(`/pro/fluentcart/licenses/${license_id}/activations`, { method: "POST", body });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: serializeEnvelope(result, "diviops_fc_license_activations_list"),
+                },
+            ],
+        };
+    }, {
+        target: "fluentcart",
+        capabilityKey: "fluentcart_license_activations_list",
+    });
 }
 // ── Start ────────────────────────────────────────────────────────────
 async function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diviops/mcp-server",
-  "version": "1.5.18",
+  "version": "1.5.20",
   "description": "MCP server exposing Divi 5 Visual Builder as tools for Claude",
   "type": "module",
   "main": "dist/index.js",