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(request): Searches campaigns by criteria (name, code, owner, type). Returns a list of CampaignSummaryDto.
• countCampaigns(request): Returns the total count of campaigns matching criteria.
• 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(request): Searches campaign rules by criteria (name, campaign, type, dates). Returns CampaignRuleSummaryDto.
• countRules(request): Returns the total count of rules matching criteria.
• getRuleById(id) / getRulesByIds(ids): Fetches details for one or multiple rules by ID.
• generateRuleId() / checkRuleId(id): Generates a new rule ID or checks ID validity.
• createRule(CampaignRule dto): Creates a new campaign rule.
• findMatchingRules(ruleType, transactionCode, transactionDate, postDate, languageCode): Finds rules matching a specific transaction.

C. Pool Definition (PoolDefinitionTools.java)

• getPoolDefinitionById(poolId): Fetches details for a Point Pool.
• getPoolDefinitionsByIds(ids): Fetches multiple pools by IDs.
• searchPoolDefinitions(request): Searches pools by criteria.

D. Counter Definition (CounterDefinitionTools.java)

• getCounterDefinitionById(counterId): Fetches details for a Counter.
• getCounterDefinitionsByIds(ids): Fetches multiple counters by IDs.

E. Deduction Sequence (DeductionSequenceTools.java)

• getDeductionSequenceById(deductionSeqId): Fetches a deduction sequence config.
• getDefaultDeductionSequence(): Fetches the system default deduction sequence.

F. Transaction Code (TransactionCodeTools.java)

• getTransactionCode(transactionCode): Fetches details for a transaction code.
• getTransactionCodes(transactionCodes): Fetches multiple transaction codes.
• checkTransactionCodeExists(transactionCode): Checks if a transaction code exists.

---

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.88: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>:

• data: T (Payload data, null on validation errors)
• _agent_instruction: String (Instructions for the LLM on how to present the data, or VALIDATION_ERROR: ... for validation failures)

The _agent_instruction field is transformed by the agent's ToolResultPresentationProcessor into agent_instruction before being sent to the LLM.

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.