Changelog
Every version, every fix, every new tool. The full paper trail.
What changed, when, and why you should care.
March 2026
v1.1.0
Released 4 March 2026 — npm · GitHub Release
The "full audit" release. Every single tool was tested against live FluentCart 1.3.13, the backend PHP source was read line-by-line, and every schema, response shape, and undocumented quirk was hunted down. 41 bug fixes, 30 quality improvements, 14 new upstream issues filed. The tool count dropped from 279 to 274 — five tools were removed because their backend endpoints are genuinely broken with no workaround.
274 total tools (was 279).
What changed
Response transforms — List endpoints now return trimmed payloads. product_list includes product_type and fulfillment_type. customer_list includes purchase_value, ltv, and purchase_count. subscription_list and subscription_get strip bloat via transformSubscription(). variant_list and variant_list_all trim variants to essential fields via trimVariant().
Fetch-merge pattern — Write tools that were silently nuking unspecified fields now fetch the current state first, merge your changes, and send the complete object. Applied to: coupon_update, customer_update, variant_update, product_update_detail, settings_save_store.
Cache invalidation — Write tools now declare which cache keys to invalidate on success via invalidates in the factory. 17 write tools wired: tax classes, tax settings, shipping zones, shipping classes, and roles. No more stale cached data after mutations.
Schema corrections from PHP source — bundle_save was sending bundle_items (wrong) instead of bundle_child_ids. pricing_update had invalid enum values variable/subscription — corrected to simple_variations/advanced_variations. tax_eu_vat_save was missing the required action: 'euCrossBorderSettings' discriminator and eu_vat_settings wrapper.
Timing-safe auth — HTTP transport Bearer token comparison now uses crypto.timingSafeEqual instead of string equality.
Bug fixes (41)
| Area | Fix |
|---|---|
| Coupons | coupon_update rewritten with fetch-merge pattern |
| Coupons | coupon_list response transform added (trim to essential fields) |
| Coupons | coupon_apply/coupon_cancel converted to createTool with correct field names |
| Coupons | coupon_settings_save specific field schema added |
| Customers | customer_list transform includes purchase analytics fields |
| Customers | customer_update rewritten with fetch-merge pattern |
| Customers | customer_bulk_action enum restricted to delete_customers |
| Customers | customer_update_additional_info now handles label sync correctly |
| Subscriptions | subscription_list now supports active_view filter |
| Subscriptions | Response transforms strip bloat from subscription data |
| Products | product_list transform includes product_type and fulfillment_type |
| Products | product_bulk_action enum restricted to valid actions |
| Products | product_update_detail rewritten with fetch-merge pattern |
| Products | product_fetch_by_ids array serialisation fixed |
| Products | variant_create title marked as required |
| Products | variant_update warning added about subscription field re-specification |
| Products | buildVariantFromExisting now spreads other_info instead of mutating input |
| Products | bundle_save field name corrected to bundle_child_ids |
| Products | pricing_update enum values corrected to match backend constants |
| Products | Upgrade path schemas corrected |
| Products | integration_save integration field schema added |
| Products | feed_status field renamed to notification_id |
| Products | terms_by_parent annotations corrected (readOnly + idempotent) |
| Tax | tax_eu_vat_save rewritten as createTool with correct payload structure |
| Tax | Cache invalidation wired to tax write tools |
| Integrations | integration_change_feed_status enum added |
| Integrations | integration_get_feed_settings required fields added |
| Integrations | integration_save_feed_settings required fields + integration field added |
| Settings | settings_save_store rewritten to flat key-value structure |
| Shipping | Cache invalidation wired to all shipping write tools |
| Roles | Capability guards and FluentCart Pro requirement notes added |
| Roles | role_get WARNING (empty backend), role_update WARNING (no-op) |
| Files | file_upload WARNING (multipart-only, JSON not supported) |
| Files | file_bucket_list driver field marked required with warning |
email_template_preview param renamed to match backend | |
email_list format note added | |
| Orders | order_sync_statuses warning added |
| Orders | order_transaction_update_status warning added |
| Orders | Order bump tools get capability guards |
| Reports | Duplicate report clarifications added |
| Public | public_user_login HTTPS security warning added |
Infrastructure improvements (30 P2 fixes)
truncateResponserefactored withsliceToFithelper and while-loop safety cap for high-variance arraysserver.tsimportsDYNAMIC_TOOL_COUNTconstant instead of hardcoded3parseSuccessBodyextracted fromrequest()to reduce cognitive complexityexecuteStatusOperationsextracted from order status handler- Biome config updated to exclude test utility scripts from linting
- 22 stale debug/scenario test files removed (6,813 lines)
Upstream FluentCart bugs filed
14 new issues filed on fluent-cart/fluent-cart (issues #22–#35):
| Issue | Bug |
|---|---|
| #22 | revenue-by-group and fetch-order-by-group crash with SQL syntax error for all groupKey values |
| #23 | POST /coupons returns full WordPress HTML page instead of JSON |
| #24 | Customer address API — three endpoint inconsistencies |
| #25 | Subscription pause, resume, and reactivate return 'Not available yet' |
| #26 | Role get and update methods have empty bodies — endpoints are no-ops |
| #27 | Coupon apply expects 'coupon_code' — inconsistent with every other coupon endpoint |
| #28 | File upload endpoint requires multipart only — no JSON-based upload option |
| #29 | Customer bulk action only supports delete — no status updates |
| #30 | Email template preview crashes — undocumented 'template' parameter required |
| #31 | Transaction status update accepts any value — no server-side validation |
| #32 | Coupon cancel crashes with null dereference when no coupons applied |
| #33 | EU VAT settings endpoint requires undocumented action discriminator |
| #34 | File bucket-list throws 'Invalid driver' — unclear which driver values are accepted |
| #35 | Coupon re-apply and checkProductEligibility are checkout-only but registered as admin REST routes |
Previously filed (v1.0.1): #9–#15, #17–#21
v1.0.1
Released 3 March 2026 — npm · GitHub Release
The "we actually tested it against a real store" release. Everything that v1.0.0 got wrong with product tools — fixed. Every tool was tested live against FluentCart 1.3.13 and the ones that didn't work were hunted down, root-caused, and either fixed or filed as upstream bugs.
New tools (3)
| Tool | What it does |
|---|---|
fluentcart_product_editor_mode_update | Switch product long description between wp-editor and block-editor |
fluentcart_product_create_dummy | Generate test products for development |
fluentcart_product_variant_option_update | Configure attribute combinations for advanced_variations products |
279 total tools (was 276).
Subscription pricing support
The big feature gap in v1.0.0: you could read subscription data but couldn't write it. Now product_pricing_update, variant_create, and variant_update all support the full subscription billing schema:
payment_type—onetimeorsubscriptionrepeat_interval—daily,weekly,monthly,quarterly,half_yearly,yearlytimes— billing cycle count (0 = unlimited)trial_days— trial period before first chargemanage_setup_fee/signup_fee/signup_fee_name— one-time setup feescompare_price— strike-through priceitem_status—active/inactiveper variantvariation_type—simple/variable/subscriptionon pricing update
Bug fixes
Price corruption — The centrepiece disaster of v1.0.0. The API expects prices in currency units (e.g. 400 for 400 PLN) and multiplies by 100 internally. The MCP tools were sending values that were already in cents, producing prices 100x too high. A 400 PLN product became 40,000 PLN. Now every write tool sends currency units and every read tool documents that responses are in cents.
Cascading variant corruption — product_pricing_update would silently nuke all existing variants when you only wanted to change the product title. It now fetches the full product state first, converts existing variant prices from cents back to currency units, and merges your changes before sending. Your variants survive a title update.
product_create nested schema — The Zod schema had detail: { fulfillment_type } nested, which MCP hosts flattened into unusable parameters. Converted to flat fulfillment_type at schema level with the handler building the nesting internally.
variant_list always 500 — FluentCart's ProductVariationController::index() crashes when query params are null. The tool now always sends explicit page and per_page params.
variant_create and variant_update broken — Both had schema/handler mismatches from the MCP flattening issue. Rewritten with proper createTool handlers. variant_update now does fetch-then-merge so it doesn't destroy fields you didn't touch.
variant_fetch_by_ids empty results — Array params weren't serialised correctly. Fixed.
product_fetch_by_ids empty results — Same issue, same fix.
product_taxonomy_sync wrong param name — Was sending term_ids, FluentCart expects terms. One letter away from working.
product_taxonomy_delete wrong param type — Was sending term_ids as an array. FluentCart's deleteTaxonomyTermFromProduct() expects a single term integer. Changed accordingly.
attribute_group_update fails without slug — FluentCart's API requires slug on every update, even for title-only changes. The tool now auto-fetches the current group to grab the existing slug when you don't provide one.
product_list filter_type param removed — filter_type controls FluentCart's internal filter mode (simple vs advanced), not product type. Product type filtering is done via active_view. Removed the misleading param and updated active_view to document all valid values: publish, draft, subscribable, not_subscribable, physical, digital, bundle, non_bundle.
post_content stripped from product GET — The response transform was removing long descriptions. Now only integrations and pricing_table are stripped.
Upstream FluentCart bugs filed
Confirmed against FluentCart 1.3.13, filed on fluent-cart/fluent-cart:
| Issue | Bug |
|---|---|
| #14 | Product duplication fails when variant SKU is empty string (unique constraint violation) |
| #15 | AttrTermResource::create() validates group_id against wrong table (fct_atts_terms instead of fct_atts_groups) |
Previously filed (v1.0.0): #9 pricing-table only updates description, #10 fetchVariationsByIds crashes, #11 GET /products/variants null params, #12 no lightweight product update endpoint, #13 price unit asymmetry
v1.0.0
Released 3 March 2026 — npm · GitHub Release
The stable release. From 200 tools to 276. Docker support. HTTP transport. Claude Desktop extension. Caching. Prompts. Resources. Dynamic mode. The works.
New tool modules (5)
| Module | Tools | What |
|---|---|---|
| Shipping | 15 | Zones, methods, classes — full CRUD with zone reordering |
| Tax | 22 | Classes, rates, EU VAT, country tax IDs, shipping overrides, records |
| Email Notifications | 8 | Templates, shortcodes, previews, global settings |
| Roles | 7 | Role CRUD, user lists, permission management |
| Files | 4 | Upload, list, delete, bucket management |
New tools in existing modules
| Module | New tools | Highlights |
|---|---|---|
| Reports (core) | +10 | Country heatmap, cart analysis, order value distribution, day/hour patterns, completion time, weeks-between-refund |
| Reports (insights) | +7 | License charts, retention analysis, subscription cohorts, retention snapshots |
| Settings | +7 | Module management, confirmation pages, payment method ordering, print templates |
Features
Docker support — Multi-stage Node 22 Alpine build. Published to Docker Hub (vcodesh/fluentcart-mcp) and GHCR. One-liner deployment for remote servers and ChatGPT integration.
HTTP transport — --transport http starts an Express server with /mcp (SSE) and /health endpoints. Optional Bearer token auth via FLUENTCART_MCP_API_KEY. Stateless — no session affinity needed.
Dynamic toolset mode — --mode dynamic registers 3 meta-tools instead of 276. The AI searches, discovers, and executes tools on demand. Token cost drops from ~30K to ~1.5K for the initial tool list. Built for MCP hosts with tool count limits.
In-memory TTL cache — Three tiers: SHORT (2 min), MEDIUM (10 min), LONG (1 hour). Applied to stable reference data: countries, tax settings, shipping zones, email shortcodes, roles. Stops redundant API calls when the AI asks the same question twice in a conversation.
MCP Prompts — 5 workflow prompts that structure common tasks:
analyze-store-performance, investigate-order, customer-overview, catalog-summary, subscription-health
MCP Resources — 4 read-only resources: store config, countries, payment methods, filter options. Available via resource:// URIs.
Claude Desktop Extension — .mcpb bundle attached to every GitHub Release. Download, double-click, enter credentials. No Node.js, no terminal, no JSON.
Interactive setup wizard — npx fluentcart-mcp setup walks through URL, username, and Application Password with live connection testing and auto-retry.
Response size limits — Responses capped at 80,000 characters with intelligent array slicing. No more MCP protocol overflows on large product catalogues.
Request tracing — Every API call includes an X-Request-Id UUID header.
Structured logging — MCP-native logging with debug/info/warn/error levels.
Bug fixes and schema corrections
| Fix | Module |
|---|---|
Report date range params used bracket notation (params[startDate]) — changed to flat startDate | Reports |
Coupon create used wrong field names (name→title, value→amount, usage_limit→conditions.max_uses) | Coupons |
Customer address had first_name/last_name — changed to name (full name, required) | Customers |
Customer and order sort params used order_by/order_type — changed to sort_by/sort_type | Customers, Orders |
Label create used value — changed to title | Labels |
Generic Error thrown for all API failures — now typed FluentCartApiError with machine-readable codes | Client |
Response transforms
List and detail endpoints now return slimmed responses to stay within context windows:
product_list— ID, title, status, slug, date onlyproduct_get— stripsintegrationsand variantpricing_tableorder_get— stripsactivities,post_content, transactionmetacustomer_list— core fields only (id, name, email, status, spend)customer_get— replaces full address array withaddress_countapp_init— stripstrans(translation strings)
Breaking changes from v0.9.0
If you built anything against v0.9.0 (you probably didn't — it was out for 12 hours):
- Coupon, customer address, label, and report tool schemas changed significantly
fluentcart_variant_updatenow requiresproduct_idalongsidevariant_id- Sort parameters standardised to
sort_by/sort_typeacross all listing tools structuredContentremoved from tool response type
v0.9.0
Released 2 March 2026 — Feature-complete pre-release.
200 tools across 22 modules. The first version that actually did things. Everything from orders to subscriptions to product management to reports. Stdio transport only, no Docker, no caching, no resources, no prompts.
Modules: orders, order transactions, customers, coupons, subscriptions, products (core, pricing, variants, catalog), product options, integrations, reports (core, insights), settings, order bumps, activity, application, dashboard, labels, notes, misc, public.
CI pipeline: typecheck, lint, test, build, smoke test, npm publish, GitHub Release.
v0.1.0
Released 2 March 2026 — Initial scaffolding. Package structure, CLI skeleton, API client, tool factory. Zero functional tools. Existed on npm for approximately 2 hours before v0.9.0 replaced it.