loyalty-agent-service/context-mcp-server.md

trigger

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 RuntimeExceptions 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.