Commerce-MCP

Implementation Reference

• tools/cs_collect.py:9-36 (handler)

  Main handler function `collect_cs` that executes the commerce_collect_cs tool logic - normalizes incoming CS tickets, classifies messages, and stores them in the database

  def collect_cs(
      *,
      tickets: list[dict[str, object]] | None = None,
      db_path: Path | str,
  ) -> dict[str, object]:
      database = Database(db_path)
      database.bootstrap()
  
      if tickets:
          normalized = []
          for ticket in tickets:
              category = _classify_message(str(ticket["message"]))
              normalized.append(
                  CSTicket(
                      channel=str(ticket["channel"]),
                      order_id=ticket.get("order_id"),
                      type=category,
                      message=str(ticket["message"]),
                      ai_category=category,
                  )
              )
          database.save_cs_tickets(normalized)
  
      stored = database.list_cs_tickets()
      return {
          "count": len(stored),
          "tickets": stored,
      }

• core/models.py:90-100 (schema)

  CSTicket Pydantic model defining the schema for customer service tickets with fields for channel, order_id, type, message, ai_category, ai_draft_response, status, and timestamps

  class CSTicket(BaseModel):
      id: str = Field(default_factory=generate_cs_ticket_id)
      channel: str
      order_id: str | None = None
      type: str = "inquiry"
      message: str
      ai_category: str | None = None
      ai_draft_response: str | None = None
      status: str = "open"
      created_at: str = Field(default_factory=utc_now_iso)

• core/server.py:78-80 (registration)

  Tool registration for 'commerce_collect_cs' using FastMCP decorator, exposing the tool to MCP clients with the tickets parameter

  @app.tool(name="commerce_collect_cs")
  def commerce_collect_cs(tickets: list[dict[str, object]] | None = None) -> dict[str, object]:
      return collect_cs(tickets=tickets, db_path=resolved_db_path)

• tools/cs_collect.py:39-47 (helper)

  Helper function `_classify_message` that classifies CS messages into categories (exchange, return, complaint, inquiry) based on keyword matching in Korean and English

  def _classify_message(message: str) -> str:
      lowered = message.lower()
      if "교환" in message or "size" in lowered:
          return "exchange"
      if "반품" in message or "refund" in lowered:
          return "return"
      if "불량" in message or "불편" in message or "complaint" in lowered:
          return "complaint"
      return "inquiry"