sonpx/loyalty-agent-service
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
18 Commits 1 Branch 0 Tags
main
Go to file
Clone
Open with VS Code Open with VSCodium Open with Intellij IDEA
Download ZIP Download TAR.GZ Download BUNDLE
Son Phung 8ecd27dd0e feat: expand MCP server functionality with customer, catalogue, marketing, and user tools and integrate new health indicators and configuration models.
2026-08-11 16:31:52 +07:00
.codegraph
feat: initialize loyalty-mcp-server module with foundational DTOs, criteria, enums, and MCP tool infrastructure
2026-07-19 23:54:26 +07:00
.mvn/wrapper
feat: scaffold initial loyalty-agent-service project with OpenAPI specifications and OAuth2-enabled API client configuration
2026-07-17 01:49:30 +07:00
docs
chore: remove legacy documentation and staging specification files
2026-07-27 18:28:51 +07:00
loyalty-agent
feat: expand MCP server functionality with customer, catalogue, marketing, and user tools and integrate new health indicators and configuration models.
2026-08-11 16:31:52 +07:00
loyalty-mcp-server
feat: expand MCP server functionality with customer, catalogue, marketing, and user tools and integrate new health indicators and configuration models.
2026-08-11 16:31:52 +07:00
public
refactor: migrate loyalty-agent and loyalty-mcp-server components to a new modular structure with updated specs and frontend integration.
2026-07-19 21:43:44 +07:00
sample-data
feat: overhaul chat architecture with persistent JdbcChatMemory, reactive UI components, and improved conversation management
2026-07-23 19:20:28 +07:00
src
feat: expand MCP server functionality with customer, catalogue, marketing, and user tools and integrate new health indicators and configuration models.
2026-08-11 16:31:52 +07:00
.env.example
feat: expand MCP server functionality with customer, catalogue, marketing, and user tools and integrate new health indicators and configuration models.
2026-08-11 16:31:52 +07:00
.gitignore
refactor: migrate loyalty-agent and loyalty-mcp-server components to a new modular structure with updated specs and frontend integration.
2026-07-19 21:43:44 +07:00
.oxlintrc.json
refactor: migrate loyalty-agent and loyalty-mcp-server components to a new modular structure with updated specs and frontend integration.
2026-07-19 21:43:44 +07:00
ARCHITECTURE.md
feat: expand MCP server functionality with customer, catalogue, marketing, and user tools and integrate new health indicators and configuration models.
2026-08-11 16:31:52 +07:00
components.json
refactor: migrate loyalty-agent and loyalty-mcp-server components to a new modular structure with updated specs and frontend integration.
2026-07-19 21:43:44 +07:00
context-agent.md
feat: expand MCP server functionality with customer, catalogue, marketing, and user tools and integrate new health indicators and configuration models.
2026-08-11 16:31:52 +07:00
context-fe.md
feat: overhaul chat architecture with persistent JdbcChatMemory, reactive UI components, and improved conversation management
2026-07-23 19:20:28 +07:00
context-mcp-server.md
feat: expand MCP server functionality with customer, catalogue, marketing, and user tools and integrate new health indicators and configuration models.
2026-08-11 16:31:52 +07:00
context.md
feat: expand MCP server functionality with customer, catalogue, marketing, and user tools and integrate new health indicators and configuration models.
2026-08-11 16:31:52 +07:00
DEPLOYMENT.md
feat: expand MCP server functionality with customer, catalogue, marketing, and user tools and integrate new health indicators and configuration models.
2026-08-11 16:31:52 +07:00
index.html
refactor: migrate loyalty-agent and loyalty-mcp-server components to a new modular structure with updated specs and frontend integration.
2026-07-19 21:43:44 +07:00
loyalty-agent-service-parent.iml
refactor: overhaul agent workflow engine with scoped tool execution, configurable LLM model profiles, and enhanced state management.
2026-07-22 18:41:45 +07:00
mvnw
refactor: migrate loyalty-agent and loyalty-mcp-server components to a new modular structure with updated specs and frontend integration.
2026-07-19 21:43:44 +07:00
mvnw.cmd
feat: scaffold initial loyalty-agent-service project with OpenAPI specifications and OAuth2-enabled API client configuration
2026-07-17 01:49:30 +07:00
package.json
feat: overhaul chat architecture with persistent JdbcChatMemory, reactive UI components, and improved conversation management
2026-07-23 19:20:28 +07:00
pnpm-lock.yaml
feat: overhaul chat architecture with persistent JdbcChatMemory, reactive UI components, and improved conversation management
2026-07-23 19:20:28 +07:00
pom.xml
refactor: migrate loyalty-agent and loyalty-mcp-server components to a new modular structure with updated specs and frontend integration.
2026-07-19 21:43:44 +07:00
postcss.config.js
refactor: migrate loyalty-agent and loyalty-mcp-server components to a new modular structure with updated specs and frontend integration.
2026-07-19 21:43:44 +07:00
README.md
feat: expand MCP server functionality with customer, catalogue, marketing, and user tools and integrate new health indicators and configuration models.
2026-08-11 16:31:52 +07:00
scaffold.py
feat: expand MCP server functionality with customer, catalogue, marketing, and user tools and integrate new health indicators and configuration models.
2026-08-11 16:31:52 +07:00
start-all.ps1
feat: expand MCP server functionality with customer, catalogue, marketing, and user tools and integrate new health indicators and configuration models.
2026-08-11 16:31:52 +07:00
start-all.sh
feat: expand MCP server functionality with customer, catalogue, marketing, and user tools and integrate new health indicators and configuration models.
2026-08-11 16:31:52 +07:00
tailwind.config.js
refactor: migrate loyalty-agent and loyalty-mcp-server components to a new modular structure with updated specs and frontend integration.
2026-07-19 21:43:44 +07:00
tsconfig.app.json
refactor: migrate loyalty-agent and loyalty-mcp-server components to a new modular structure with updated specs and frontend integration.
2026-07-19 21:43:44 +07:00
tsconfig.json
refactor: migrate loyalty-agent and loyalty-mcp-server components to a new modular structure with updated specs and frontend integration.
2026-07-19 21:43:44 +07:00
tsconfig.node.json
refactor: migrate loyalty-agent and loyalty-mcp-server components to a new modular structure with updated specs and frontend integration.
2026-07-19 21:43:44 +07:00
vite.config.ts
feat: overhaul chat architecture with persistent JdbcChatMemory, reactive UI components, and improved conversation management
2026-07-23 19:20:28 +07:00

README.md

Loyalty Agent Service

A production-ready AI-powered assistant for managing a Loyalty platform, built on the Model Context Protocol (MCP).

Architecture

Frontend (React/Vite :9333)
    ↓ WebSocket (STOMP)
loyalty-agent (:9332)                 ← Orchestrator + BFF
    ↓ MCP SSE Transport (/sse, /message)
loyalty-mcp-server (:9331)            ← MCP Tool Server
    ↓ REST + OAuth2 (Keycloak)
Loyalty Core API (:8081)              ← Backend Services

Modules

Module Port Role
loyalty-mcp-server 9331 MCP Server — exposes 25 tools via SSE transport
loyalty-agent 9332 AI Agent — orchestrates LLM + MCP tools
Frontend (root) 9333 React/Vite chat UI

Technology Stack

  • Java 25, Spring Boot 4.0.0, Spring AI 2.x
  • MCP Transport: SSE (WebMVC) via spring-ai-starter-mcp-server-webmvc
  • LLM: Ollama (qwen3.5:4b, configurable)
  • Auth: Keycloak OAuth2 Client Credentials
  • Persistence: PostgreSQL (agent conversation history)
  • Frontend: React + Vite + WebSocket (STOMP)

MCP Capabilities

Tools (25 registered)

Category Tools
Campaign searchCampaigns, countCampaigns, getCampaignById, getCampaignsByIds, generateCampaignId, checkCampaignId, createCampaign
Campaign Rule searchRules, countRules, getRuleById, getRulesByIds, generateRuleId, checkRuleId, createRule, findMatchingRules
Pool Definition getPoolDefinitionById, getPoolDefinitionsByIds, searchPoolDefinitions
Counter getCounterDefinitionById, getCounterDefinitionsByIds
Deduction Sequence getDeductionSequenceById, getDefaultDeductionSequence
Transaction Code getTransactionCode, getTransactionCodes, checkTransactionCodeExists

Resources & Prompts

  • Resources, resource templates, prompts, and completions capabilities are enabled via Spring AI autoconfiguration
  • Currently no custom resources or prompts defined (the autoconfiguration registers empty capability declarations)

Transport

  • SSE: /sse endpoint for server-sent events
  • Message: /message endpoint for client-to-server messages
  • Keep-alive: 30-second interval configured

Startup Instructions

Prerequisites

  • Java 25+
  • Node.js & pnpm
  • PostgreSQL (for agent persistence)
  • .env file created (see .env for template)

Start Backend Modules

# Start both modules with one script:
./start-all.sh

# Or start individually:
./mvnw spring-boot:run -pl loyalty-mcp-server
./mvnw spring-boot:run -pl loyalty-agent

Start Frontend

pnpm install
pnpm dev

Configuration

Key environment variables (see .env):

Variable Description
LOYALTY_CORE_BASE_URL Base URL for Loyalty Core API
KEYCLOAK_TOKEN_URI Keycloak token endpoint
KEYCLOAK_CLIENT_ID OAuth2 client ID
KEYCLOAK_CLIENT_SECRET OAuth2 client secret
SPRING_DATASOURCE_URL PostgreSQL connection for agent
OLLAMA_BASE_URL Ollama LLM endpoint

Error Handling

  • AOP Aspect (GlobalToolExceptionHandlerAspect): Wraps all @McpTool methods, catches exceptions and returns safe Result.failure() responses
  • REST Exception Handler (GlobalMcpExceptionHandler): Catches transport-level exceptions with safe error response
  • Agent-side (ToolInterceptor): Sanitizes error responses, auto-reconnects on dropped SSE connections, truncates large results

Security

  • OAuth2 Client Credentials flow for backend API authentication
  • No internal stack traces or credentials exposed to MCP client
  • Input validation on all tool parameters
  • Response body logging limited to debug level with truncation

Running Tests

# All tests
./mvnw test

# MCP server tests only
./mvnw test -pl loyalty-mcp-server

# Agent tests only
./mvnw test -pl loyalty-agent

Health Checks

Both services expose Spring Boot Actuator health endpoints:

GET /actuator/health          — Overall health
GET /actuator/health/liveness — Kubernetes liveness probe
GET /actuator/health/readiness — Kubernetes readiness probe

Additional Tools (Domain Services)

Category Tools
App Param searchAppParam, getAppParamById
Dynamic Attribute searchDynamicAttribute, getDynamicAttributeById
Journey searchJourney, getJourneyById
User searchUser, getUserById
Customer searchCustomers, getCustomerById
Catalogue searchCatalogues, getCatalogueById
Transaction searchTransactions, getTransactionById

Further Documentation

Description
No description provided
Readme 67 MiB
Languages
Java 83.4%
TypeScript 13.4%
Python 0.9%
PowerShell 0.6%
Shell 0.6%
Other 1.1%