\documentclass[12pt]{article}
\usepackage{hyperref}
\usepackage{listings}
\usepackage{courier}
\usepackage{geometry}
\geometry{margin=1in}

\lstset{
  basicstyle=\ttfamily\footnotesize,
  breaklines=true,
}

\begin{document}

\section*{MCP Server for Recommendation System}

This document describes a hosted MCP server that provides tools exposing Large Language Models to a Reinforcement Learning-based Recommendation Engine. The system learns iteratively to tailor recommendations based on user interactions and journey patterns within the store.

\subsection*{Tools}
\begin{itemize}
    \item Status: Get the current status of the recommender system
    \item Submit feedback: Record user interaction events and update the Multi-Armed Bandit simulation with reward feedback
    \item Get recommendations: Generate personalized product recommendations using the MABSimulation recommender
\end{itemize}

\subsection*{Server Endpoint}
The MCP server is hosted at: \url{https://mcp-server.workzy.co}

\section*{MCP Server Communication Schema}

\subsection*{HTTP Transport}

The server implements the FastMCP HTTP transport protocol and exposes the following endpoints:

\subsubsection*{1. List Tools}
\begin{lstlisting}
GET /tools
\end{lstlisting}

Returns: Array of tool definitions with \texttt{inputSchema} automatically generated from Pydantic models

\subsubsection*{2. Call Tool}
\begin{lstlisting}
POST /tools/call_tool
Content-Type: application/json
\end{lstlisting}

\paragraph*{Request Format:}
\begin{lstlisting}
{
  "name": "tool_name",
  ...tool_arguments_flattened
}
\end{lstlisting}

\paragraph*{Response Format:} The response is a direct tool return value as a JSON object.

\section*{Tool Request/Response Formats}

\subsection*{\texttt{status}}

\textbf{Request:}
\begin{lstlisting}
{
  "name": "status"
}
\end{lstlisting}

\textbf{Response:}
\begin{lstlisting}
{
  "status": "success",
  "message": "Recommender system is running",
  "tools": [
    {
      "name": "get_system_status",
      "description": "Get the current status of the recommender system",
      "structured_output": false
    },
    {
      "name": "submit_feedback",
      "description": "Handles the MAB reward by feedback and updates the recommender simulation",
      "structured_output": false
    }
  ]
}
\end{lstlisting}

\subsection*{\texttt{submit\_feedback}}

\textbf{Request:}
\begin{lstlisting}
{
  "name": "submit_feedback",
  "feedback": {
    "user_id": 1,
    "item_id": 5,
    "event_type": "purchase",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
\end{lstlisting}

\textbf{Response:}
\begin{lstlisting}
{
  "status": "success",
  "item_id": 5,
  "user_id": 1,
  "reward": 1.0,
  "n": 10,
  "q": 0.85,
  "message": "Feedback processed and MABSimulation updated"
}
\end{lstlisting}

\subsubsection*{Reward Mapping}
\begin{itemize}
  \item purchase: 1.0
  \item cart: 0.33
  \item view: 0.1
  \item remove\_from\_cart: -0.5
\end{itemize}

\subsection*{\texttt{get\_recommendations}}

\textbf{Request:}
\begin{lstlisting}
{
  "name": "get_recommendations",
  "request": {
    "user_id": 1,
    "n_recommendations": 3,
    "algorithm_type": "epsilon_greedy",
    "algorithm_params": {
      "epsilon": 0.1
    }
  }
}
\end{lstlisting}

\textbf{Response:}
\begin{lstlisting}
{
  "status": "success",
  "user_id": 1,
  "recommendations": [6841151684791, 7096764989623, 6701918027959],
  "products": [
    {
      "product_id": 6841151684791,
      "product_name": "Now or Never - Mehndi Green  Pajama Set",
      "brand_name": "Unknown Brand",
      "category": "general",
      "price": 899.0,
      "description": "...",
      "image_url": "https://cdn.shopify.com/...",
      "created_at": "2025-12-01 04:14:37"
    },
    ...
  ],
  "algorithm_type": "epsilon_greedy",
  "algorithm_class": "EpsilonGreedyMAB",
  "confidence_scores": [0.1, 0.1, 0.1],
  "total_recommendations": 3,
  "message": "Recommendations generated using MABSimulation"
}
\end{lstlisting}

\section*{Pydantic Model Schemas}

\subsection*{RecommendationRequest}
\begin{itemize}
  \item user\_id (integer, required)
  \item n\_recommendations (integer, default = 3, min = 1, max = 50)
  \item algorithm\_type (string, default = epsilon\_greedy)
  \item algorithm\_params (object, optional)
\end{itemize}

\subsection*{FeedbackData}
\begin{itemize}
  \item user\_id (integer, required)
  \item item\_id (integer, required)
  \item event\_type (string, required, enum: view, cart, purchase, remove\_from\_cart)
  \item timestamp (string, optional)
\end{itemize}

\end{document}
