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/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@@ -0,0 +1,165 @@
+# Deployment Guide — Loyalty Agent Service
+
+## Prerequisites
+
+- Java 25+ (JRE)
+- PostgreSQL 15+
+- Ollama with `qwen3.5:4b` and `qwen2.5:1.5b` models
+- Keycloak with OAuth2 Client Credentials configured
+- Loyalty Core API running (`:8081`)
+
+## Environment Variables
+
+Copy `.env.example` to `.env` and configure all required values:
+
+```bash
+cp .env.example .env
+# Edit .env with your production values
+```
+
+### Required Variables
+
+| Variable | Service | Description |
+|----------|---------|-------------|
+| `KEYCLOAK_CLIENT_SECRET` | MCP Server | Keycloak client secret |
+| `KEYCLOAK_TOKEN_URI` | MCP Server | Keycloak token endpoint |
+| `LOYALTY_CORE_BASE_URL` | MCP Server | Loyalty Core API URL |
+| `SPRING_DATASOURCE_PASSWORD` | Agent | PostgreSQL password |
+| `MCP_SERVER_URL` | Agent | MCP SSE endpoint |
+
+### Optional Variables (with defaults)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `KEYCLOAK_CLIENT_ID` | `ols-cli` | OAuth2 client ID |
+| `SPRING_DATASOURCE_URL` | `jdbc:postgresql://localhost:5433/loyalty_agent` | DB URL |
+| `SPRING_DATASOURCE_USERNAME` | `postgres` | DB username |
+| `OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama URL |
+| `OLLAMA_MODEL` | `qwen3.5:4b` | Primary LLM model |
+| `AGENT_REQUEST_TIMEOUT` | `120` | LLM request timeout (seconds) |
+
+## Building
+
+```bash
+# Build both modules
+./mvnw clean package -DskipTests
+
+# Run tests
+./mvnw test
+```
+
+## Running Locally
+
+### Quick Start
+
+```bash
+./start-all.sh
+```
+
+### Manual Start
+
+```bash
+# 1. Start MCP Server (:9331)
+cd loyalty-mcp-server
+java -jar target/*.jar
+
+# 2. Start Agent (:9332)
+cd loyalty-agent
+java -jar target/*.jar
+
+# 3. Start Frontend (:9333)
+npm run dev
+```
+
+## Docker Deployment
+
+### Build Images
+
+```bash
+# MCP Server
+cd loyalty-mcp-server
+docker build -t loyalty-mcp-server:latest .
+
+# Agent
+cd loyalty-agent
+docker build -t loyalty-agent:latest .
+```
+
+### Run Containers
+
+```bash
+# MCP Server
+docker run -d --name loyalty-mcp-server \
+  -p 9331:9331 \
+  -e KEYCLOAK_CLIENT_SECRET=... \
+  -e KEYCLOAK_TOKEN_URI=... \
+  -e LOYALTY_CORE_BASE_URL=... \
+  loyalty-mcp-server:latest
+
+# Agent
+docker run -d --name loyalty-agent \
+  -p 9332:9332 \
+  -e SPRING_DATASOURCE_PASSWORD=... \
+  -e MCP_SERVER_URL=http://loyalty-mcp-server:9331/sse \
+  loyalty-agent:latest
+```
+
+## Health Checks
+
+Both services expose health endpoints via Spring Boot Actuator:
+
+| Endpoint | Purpose |
+|----------|---------|
+| `/actuator/health` | Overall health |
+| `/actuator/health/liveness` | Liveness probe (is the process alive?) |
+| `/actuator/health/readiness` | Readiness probe (can it handle requests?) |
+| `/actuator/info` | Service info |
+
+### Kubernetes Probes
+
+```yaml
+livenessProbe:
+  httpGet:
+    path: /actuator/health/liveness
+    port: 9332
+  initialDelaySeconds: 60
+  periodSeconds: 30
+
+readinessProbe:
+  httpGet:
+    path: /actuator/health/readiness
+    port: 9332
+  initialDelaySeconds: 30
+  periodSeconds: 10
+```
+
+## JVM Configuration
+
+Production JVM flags (included in Dockerfile):
+
+```bash
+java \
+  -XX:+UseContainerSupport \
+  -XX:MaxRAMPercentage=75.0 \
+  -Djava.security.egd=file:/dev/./urandom \
+  -jar app.jar
+```
+
+## Port Summary
+
+| Service | Port |
+|---------|------|
+| Loyalty MCP Server | 9331 |
+| Loyalty Agent | 9332 |
+| Frontend (dev) | 9333 |
+| Loyalty Core API | 8081 |
+
+## Troubleshooting
+
+### Common Issues
+
+1. **MCP Connection Timeout**: Increase `spring.ai.mcp.client.request-timeout` (default: 30000ms)
+2. **LLM Not Responding**: Check Ollama is running: `curl http://localhost:11434/api/tags`
+3. **OAuth2 Token Error**: Verify Keycloak credentials and token-uri
+4. **DB Migration Failed**: Check Flyway logs, ensure PostgreSQL is accessible
+5. **WebSocket Disconnect**: Frontend auto-reconnects with exponential backoff