Ecommercen Docs

Appearance

<div style="display: none;" hidden="true" aria-hidden="true">Are you an LLM? You can read better optimized documentation at /changelog/Changelog.4.117.md for this page in Markdown format</div>

Home | Changelog

Version 4 ​

version 4.117 ​

  • [4.117.0] feat(mcp): read-only Sales & Analytics tools + token scopes (Advisable-com/ecommercen#403, #412)
    • Token scopes. Each MCP token now carries one or more scopes — seo (the existing 17 catalog/SEO edit tools) and/or analytics (the 7 new read-only tools). The admin "MCP Connector" settings page is now a token list: generate a token with selected scopes, rotate or revoke each independently. Multiple concurrent tokens are supported. Legacy scope-less tokens are treated as seo — no change to their tool surface. An analytics-only token is structurally blocked from reaching any write tool.
    • 7 read-only analytics tools (scope: analytics; ISO-8601 dates, Europe/Athens, amounts EUR, schema_version in every response, date range ≤ 366 days, ~5 min cache except orders_list):
      • sales_summary — period KPIs (orders_count, units_sold, gross/net revenue, VAT, shipping, discounts, avg_order_value, new/returning customers) + optional compare (yoy|mom|wow|prev_period) with delta_pct.
      • sales_timeseries — same KPIs bucketed day|week|month.
      • sales_breakdown — metrics by dimension: product|category|brand|payment_method|shipping_method|region; sort_by net_revenue|units|orders; limit; optional compare. Note: a product in multiple categories is attributed to each — category rows can exceed the grand total.
      • orders_list — granular order rows, PII-stripped: opaque non-reversible customer_id (keyed HMAC), coarse region only, no names/emails/phones/addresses/AFM. Keyset cursor pagination. Not cached.
      • price_history — per-product price-change history from the price-tracking log. on_promo is null (not historically recoverable → promo_history_available: false). Coverage via tracking_enabled / earliest_date.
      • product_sales — per-product sales series (units, net_revenue, avg_selling_price) + commercial snapshot (current_price excl. VAT, cost, margin_pct, current_stock).
      • customers_stats — aggregate-only, zero PII: new/returning (email-keyed, email not exposed), repeat_rate_pct, avg_orders_per_customer, avg_customer_value, cohorts by month|week.
    • Reporting conventions (CEO-confirmed): reporting date = order entry_datetime; ALL orders counted (phone/webignore not excluded); no refunds metric (platform has none); gross_revenue includes shipping.
    • Infrastructure. New src/Mcp/Auth/Scopes.php scope model; updated TokenGuard, TokenService, TokenRepository; new src/Mcp/Tools/AnalyticsTools.php; new src/Domains/Order/SalesAnalytics/ domain; McpAuditLogger extended with a logRead() path for analytics calls.
    • No storefront REST API changes. Adds 11 admin i18n keys (settings.mcp_connector.* — scope badges, token-list labels, generate/rotate) across all 8 languages; no storefront language keys.

Notes

  • [4.117.0] REQUIRES php migrator.php migrate:

    • 20260630120000_add_scopes_to_mcp_connector_tokens.php — adds the nullable scopes column to mcp_connector_tokens. No data backfill: existing tokens keep scopes = NULL, which is treated as seo at read time (their surface is unchanged). Forward-only.

  • [4.117.0] New env var — set before enabling analytics tools: APP_MCP_ANALYTICS_ID_SECRET (in .env, already added to .env.example) — a stable random secret used to derive the opaque customer_id in orders_list. Falls back to CodeIgniter's encryption_key; if neither is set the tool errors rather than emit a guessable id. The value must remain stable across deployments — changing it invalidates all previously issued customer ids (cohort continuity breaks).

  • [4.117.0] Optional registry key: MCP_ANALYTICS / SALE_STATUSES (CSV of order status names that count as a sale; default PENDING_ACCEPTED, PAID_SENT, SENT, INVOICED). Override in the DB registry if the deployment uses non-standard status names.