---
trigger: always_on
---

# Application Context: `loyalty-mcp-server`

Application Name: **Loyalty MCP Server**  
Module Path: `loyalty-mcp-server/`  
Runtime Port: `9331`  
Technology Stack: Java 25, Spring Boot 4.x, Spring AI 2.x MCP Server (`spring-ai-mcp-server-spring-boot-starter`), OAuth2 RestClient, OpenAPI Specs

---

## 1. Primary Roles & Responsibilities

`loyalty-mcp-server` operates as a standalone **MCP Tool Server**:
- **Expose Tools to Agent**: Encapsulates loyalty business capabilities into standardized Model Context Protocol (MCP) tools.
- **MCP SSE Transport**: Exposes an SSE endpoint (`/sse`) and a Message endpoint (`/message`) for `loyalty-agent` to connect and execute tools remotely.
- **Loyalty Core API Integration**: Directly calls the Loyalty Core Backend API to query and manipulate domain entities (Campaigns, Rules, Point Pools, Members, Attributes...).
- **Response Standardization & Exception Safety**: Wraps tool outputs in standard `Result<T>` and `OperationResult<T>` structures, supplying a `presentation.content` Markdown snippet for direct user display.

---

## 2. Business Tool Registry

Tools are registered using the `@McpTool` annotation in the `dev.sonpx.loyalty.mcp.tool` package.

### A. Campaign Management (`CampaignTools.java`)
- **`searchCampaigns(search)`**: Searches campaigns by keyword (name/code). Returns a list of `CampaignSummaryDto` (basic info: name, code, owner, type, schedule).
- **`countCampaigns(search)`**: Returns the total count of campaigns.
- **`getCampaignById(id)` / `getCampaignsByIds(ids)`**: Fetches details for one or multiple campaigns by ID.
- **`generateCampaignId()` / `checkCampaignId(id)`**: Generates a new campaign ID or verifies ID validity.
- **`createCampaign(Campaign dto)`**: Creates a new loyalty campaign.

### B. Campaign Rule Management (`CampaignRuleTools.java`)
- **`searchRules(search)`**: Searches campaign rules/terms by keyword (name/code). Returns a list of `CampaignRuleSummaryDto` (includes reward formula, parent campaign, rule type).
- **`countRules(search)`**: Returns the total count of rules.
- **`getRuleById(id)` / `getRulesByIds(ids)`**: Fetches details for one or multiple rules by ID (reward formula, conditions, limits, schedule).
- **`generateRuleId()` / `checkRuleId(id)`**: Generates a new rule ID or checks ID validity.
- **`createRule(CampaignRule dto)`**: Creates a new campaign rule associated with a campaign.

---

## 3. Loyalty Core API Integration & OpenAPI Specs

- **OAuth2 Client Credentials Authentication**:
  - Automatically fetches Bearer tokens from Keycloak (`KEYCLOAK_TOKEN_URI`, `KEYCLOAK_CLIENT_SECRET`).
  - Attaches authorization headers to requests sent to `LOYALTY_CORE_BASE_URL` (`http://192.168.99.242:8081`).
- **OpenAPI Specs Registry**:
  - Located at `src/main/resources/specs/`:
    - `master.json`, `marketing.json`, `reward.json`, `customer.json`, `attribute.json`, `catalogue.json`, `transaction.json`, `identity.json`.
  - Serves as the authoritative schema reference for DTOs and API payloads.

---

## 4. Response Wrapping & Exception Handling

### Standardized Response Wrapper
All tools return `Result<T>`:
- `success`: boolean
- `data`: T (Payload data)
- `message`: Summary status message or error details
- `presentation`: Object containing `content` (Markdown string intended for user-facing display)

### Exception Handling (`aspect/` & `exception/`)
- `GlobalToolExceptionHandlerAspect`: AOP aspect that intercepts exceptions across all `@McpTool` methods.
- `GlobalMcpExceptionHandler`: Catches Core API failures (HTTP 4xx, 5xx, timeouts) and formats them into clean `Result.failure(...)` objects for the LLM without crashing the invocation stream.

---

## 5. Key Development Guidelines for Agents

1. **Tool Prompting Quality (`description`)**: `@McpTool` descriptions act as direct system prompt instructions for the LLM when choosing tools. Keep descriptions precise, clear, and explicit (e.g., instructing the LLM not to pass generic terms like "campaign" into search queries).
2. **Strict Adherence to `Result<T>`**: Never return raw null values or throw unhandled `RuntimeException`s from tool methods.
3. **Clear Tool Boundaries**: `CampaignTools` handles top-level campaign metadata. `CampaignRuleTools` handles reward formulas, conditions, and rules.
4. **MCP Ports**: Maintain server execution on port `9331` at endpoints `/sse` and `/message`.