sonpx/loyalty-agent-service
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: expand MCP server functionality with customer, catalogue, marketing, and user tools and integrate new health indicators and configuration models.

Browse Source
This commit is contained in:
Son Phung
2026-08-11 16:31:52 +07:00
parent 9a26c6ce2d
commit 8ecd27dd0e
188 changed files with 5672 additions and 983 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
context-mcp-server.md
View File

@@ -14,6 +14,7 @@ Technology Stack: Java 25, Spring Boot 4.x, Spring AI 2.x MCP Server (`spring-ai
## 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...).
@@ -26,18 +27,43 @@ Technology Stack: Java 25, Spring Boot 4.x, Spring AI 2.x MCP Server (`spring-ai
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.
- **`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(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).
- **`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 associated with a campaign.
- **`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.
---
@@ -45,7 +71,7 @@ Tools are registered using the `@McpTool` annotation in the `dev.sonpx.loyalty.m
- **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`).
- 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`.
@@ -56,13 +82,16 @@ Tools are registered using the `@McpTool` annotation in the `dev.sonpx.loyalty.m
## 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)
- `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.