dbbaskette/imc-policy-mcp-server

graph TB
    A[🔍 MCP Client Query] --> B[🧠 Query Transformation]
    B --> C[🎯 Customer-Scoped Search]
    C --> D[📊 PGVector Similarity]
    D --> E[📄 Document Assembly]
    E --> F[✅ Structured Response]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#fff3e0
    style D fill:#e8f5e8
    style E fill:#fce4ec
    style F fill:#e3f2fd

graph TB
    subgraph "🌐 Client Layer"
        MC[MCP Client<br/>📱 Chat Interface]
    end
    
    subgraph "🎯 MCP Server"
        MT[McpToolService<br/>🛠️ @McpTool]
        RS[RagService<br/>🧠 Query Processing]
        QT[Query Transformers<br/>✨ AI Enhancement]
    end
    
    subgraph "💾 Data Layer"
        VS[VectorStore<br/>📊 PGVector]
        PG[(PostgreSQL<br/>🐘 + pgvector)]
    end
    
    subgraph "🤖 AI Services"
        OAI[OpenAI<br/>🎨 Embeddings + Chat]
        CF[Cloud Foundry<br/>☁️ Bound Services]
    end
    
    MC -->|MCP Protocol| MT
    MT --> RS
    RS --> QT
    RS --> VS
    VS --> PG
    RS -.->|Query Rewrite| OAI
    QT -.->|Multi-Query| OAI
    
    style MC fill:#e3f2fd
    style MT fill:#f3e5f5
    style RS fill:#e8f5e8
    style VS fill:#fff3e0
    style OAI fill:#fce4ec

# Required Software
☑️ Java 21+
☑️ Docker & Docker Compose
☑️ Maven 3.8+
☑️ PostgreSQL 15+ (with pgvector extension)

# 1️⃣ Clone and navigate
git clone https://github.com/dbbaskette/imc-policy-mcp-server
cd imc-policy-mcp-server

# 2️⃣ Configure environment
cp .env.example .env
# Edit .env with your OpenAI API key and ensure OPENAI_TEMPERATURE=1.0 for gpt-5-nano

# 3️⃣ Start everything with one command! 🎉
./mcp-server.sh --build --local --docker

# 🧠 RAG Configuration
app.rag.top-k: 5                    # Number of documents to retrieve
app.rag.similarity-threshold: 0.7   # Minimum similarity score
app.rag.query-rewrite: true         # Enable AI query enhancement
app.rag.multi-query: false          # Enable query expansion
app.rag.multi-query-count: 3        # Number of query variations

# 📊 Vector Store Configuration  
spring.ai.vectorstore.pgvector.dimensions: 768
spring.ai.vectorstore.pgvector.distance-type: COSINE_DISTANCE
spring.ai.vectorstore.pgvector.index-type: HNSW

# 🔧 Data Loading
app.data.load-sample-data: true     # Load CSV data on startup

# 🤖 OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-5-nano
OPENAI_TEMPERATURE=1.0
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

# 💾 Database Configuration  
DB_HOST=localhost
DB_PORT=5432
DB_NAME=imc_policy
DB_USER=imc_user
DB_PASSWORD=imc_password

# 🎯 RAG Tuning
RAG_TOP_K=5
RAG_SIMILARITY_THRESHOLD=0.7
RAG_QUERY_REWRITE=true

# Enable/disable PDF ETL on startup
app.etl.enabled: false
app.etl.source-directory: local_data/source

# 🔨 Build and test
./mcp-server.sh --build --skip-tests

# 🧪 Run with test database
./mcp-server.sh --local --docker

# 🚀 Build and run everything
./mcp-server.sh --build --local --docker

# 🧹 Stop Docker services
./mcp-server.sh --stop-docker

# ☁️ Deploy to Cloud Foundry
./mcp-server.sh --build --cf

# 🏥 Health check
curl http://localhost:8080/actuator/health

# 🧪 Test RAG functionality (local profile only)
curl "http://localhost:8080/api/test/rag?query=What is covered?&customerId=100001"

# 📋 Get service info
curl http://localhost:8080/api/test/rag/info

# 📝 Sample queries
curl http://localhost:8080/api/test/samples

{
  "tool": "answerQuery",
  "parameters": {
    "query": "What does my auto insurance policy cover?",
    "customerId": 100001
  }
}

{
  "success": true,
  "query": "What does my auto insurance policy cover?",
  "customerId": 100001,
  "context": "Document 1:\nAuto insurance policy coverage details...",
  "processingTimeMs": 1250,
  "timestamp": 1699123456789
}

# Quick development setup
docker-compose up -d              # Start PostgreSQL
./mcp-server.sh --local --docker  # Run application

# Deploy to Cloud Foundry
./mcp-server.sh --build --cf

# Monitor deployment
cf apps
cf logs imc-policy-mcp-server --recent

# Debug logging for development
logging.level.com.insurancemegacorp.policymcpserver: DEBUG
logging.level.org.springframework.ai.vectorstore: DEBUG

# Production logging
logging.level.com.insurancemegacorp.policymcpserver: INFO
logging.level.org.springframework.ai: WARN

# Run all tests (currently skipped due to JDK compatibility)
mvn test

# Run specific test suites
mvn test -Dtest=*Service*
mvn test -Dtest=*Controller*

# Test with different customer IDs
curl "http://localhost:8080/api/test/rag?query=What is my deductible?&customerId=100001"
curl "http://localhost:8080/api/test/rag?query=Claims process&customerId=100002"
curl "http://localhost:8080/api/test/rag?query=Coverage details&customerId=100003"

{
  "success": true,
  "query": "What is covered under my policy?",
  "customerId": 100001,
  "context": "Document 1:\nYour auto insurance policy covers...",
  "processingTimeMs": 1250,
  "timestamp": 1699123456789
}

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "content": "Auto insurance policy coverage details...",
  "metadata": {
    "customerId": 100001,
    "policyType": "auto", 
    "policyNumber": "POL-2024-001",
    "documentType": "coverage",
    "effectiveDate": "2024-01-15"
  },
  "embedding": [0.1, 0.2, ...] // 768-dimensional vector
}