Commerce-MCP

Implementation Reference

• tools/analytics.py:9-35 (handler)

  The analytics_report function is the core handler implementation for the commerce_analytics tool. It queries the database for orders, aggregates sales data by channel and product, calculates total orders and revenue, and returns a comprehensive analytics report including sales summary, channel breakdown, product breakdown, and daily sales data.

  def analytics_report(*, db_path: Path | str) -> dict[str, object]:
      database = Database(db_path)
      database.bootstrap()
  
      orders = database.list_orders()
      by_channel: dict[str, dict[str, int]] = defaultdict(lambda: {"orders": 0, "revenue": 0})
      by_product: dict[str, dict[str, int]] = defaultdict(lambda: {"orders": 0, "revenue": 0})
  
      total_orders = len(orders)
      total_revenue = 0
      for order in orders:
          revenue = int(order["selling_price"]) * int(order["quantity"])
          total_revenue += revenue
          by_channel[str(order["channel"])]["orders"] += 1
          by_channel[str(order["channel"])]["revenue"] += revenue
          by_product[str(order["product_id"])]["orders"] += int(order["quantity"])
          by_product[str(order["product_id"])]["revenue"] += revenue
  
      return {
          "sales": {
              "total_orders": total_orders,
              "total_revenue": total_revenue,
          },
          "channels": by_channel,
          "products": by_product,
          "daily_sales": database.list_daily_sales(),
      }

• core/server.py:102-104 (registration)

  The commerce_analytics tool is registered with the MCP framework using the @app.tool decorator with name="commerce_analytics". This registration wraps the analytics_report handler and exposes it as a tool that can be called through the MCP protocol. The tool takes no input parameters and returns a dictionary containing sales analytics.

  @app.tool(name="commerce_analytics")
  def commerce_analytics() -> dict[str, object]:
      return analytics_report(db_path=resolved_db_path)

• core/server.py:1-11 (helper)

  Import statement that brings analytics_report from tools.analytics into the server module, enabling the commerce_analytics tool registration to call the handler function.

  from __future__ import annotations
  
  import os
  from pathlib import Path
  
  from fastmcp import FastMCP
  
  from core.models import StandardProduct
  from tools.ad_create import create_ad
  from tools.ad_report import report_ad
  from tools.analytics import analytics_report