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
parent 9a26c6ce2d
commit 8ecd27dd0e
188 changed files with 5672 additions and 983 deletions
--- a/README.md
+++ b/README.md
@@ -1,31 +1,146 @@
 # Loyalty Agent Service

-This project consists of a 3-module architecture:
-1. `loyalty-mcp-server`: Domain MCP tools and operations
-2. `loyalty-agent`: Orchestration and BFF layer
-3. Frontend (React/Vite in the root directory)
+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

-### 1. Prerequisites
- Java 21+
+### Prerequisites
+- Java 25+
 - Node.js & pnpm
- `.env` file created (see `.env.example`)
+- PostgreSQL (for agent persistence)
+- `.env` file created (see `.env` for template)

-### 2. Start Backend Modules
-You can use the provided startup script:
+### Start Backend Modules
 ```bash
+# Start both modules with one script:
 ./start-all.sh
-```
-Or start them individually in separate terminals:
-```bash
+
+# Or start individually:
 ./mvnw spring-boot:run -pl loyalty-mcp-server
 ./mvnw spring-boot:run -pl loyalty-agent
 ```

-### 3. Start Frontend
-In a new terminal:
+### Start Frontend
 ```bash
 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
+
+```bash
+# 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
+
+- [ARCHITECTURE.md](ARCHITECTURE.md) — System architecture, data flow, security model
+- [DEPLOYMENT.md](DEPLOYMENT.md) — Production deployment guide
+- [.env.example](.env.example) — Environment variable template
+