[![M8ven Live Monitored](https://m8ven.ai/badge/mcp/sukkamit-customer-mcp-server-1wm9u7)](https://m8ven.ai/mcp/sukkamit-customer-mcp-server-1wm9u7)
 # Customer MCP Server

Customer MCP Server เป็นโปรเจกต์สำหรับเชื่อมต่อ LLM กับข้อมูลลูกค้า โดยใช้ Model Context Protocol (MCP) เพื่อให้ AI Client สามารถเข้าถึงข้อมูลลูกค้าอย่างปลอดภัยและมีกรอบควบคุมที่ชัดเจน

## ภาพรวมของระบบ

ระบบนี้ออกแบบมาเพื่อให้ LLM สามารถถามข้อมูลลูกค้าได้ผ่านเครื่องมือที่กำหนดไว้เท่านั้น ไม่ต้องเข้าถึงฐานข้อมูลโดยตรง

### สิ่งที่รองรับ

- ดึงข้อมูลลูกค้าเบื้องต้น
- ค้นหาประวัติการสื่อสารลูกค้าแบบ semantic search ด้วย vector embedding
- สรุปข้อมูลการซื้อและธุรกรรมทางการเงินแบบ exact value
- บันทึก audit log ของธุรกรรม
- ป้องกัน prompt injection และการเข้าถึงข้อมูลที่ไม่ได้รับอนุญาต

## สถาปัตยกรรม

```text
LLM Client
    |
    | MCP Protocol
    v
MCP Server (Python)
    |
    +-------------------+
    |                   |
    v                   v
Semantic Search      SQL / Financial
PostgreSQL + pgvector PostgreSQL
```

## ฟีเจอร์หลัก

### 1. Customer Profile

- ดึงข้อมูลพื้นฐานของลูกค้า เช่น customer_id, name, email, phone, created_at

### 2. Interaction Semantic Search

- ค้นหาประวัติการสนทนา/interaction ของลูกค้าโดยใช้ embedding vector
- เหมาะสำหรับการค้นหาความหมายในคำถามที่เป็นคำกว้าง เช่น refund issue, complaint, billing concern

### 3. Financial Summary

- คำนวณจำนวนคำสั่งซื้อและยอดซื้อรวมจากฐานข้อมูล
- ใช้ SQL aggregation เพื่อให้ได้ค่าที่ถูกต้องและเชื่อถือได้
- คืน audit log ของธุรกรรมพร้อม hash reference

## Hybrid Query Example

ตัวอย่างคำถาม:

"ลูกค้าเคยแจ้งปัญหาอะไร และมียอดซื้อทั้งหมดเท่าไร"

Flow:

search_customer_interactions()

        |
        v

pgvector similarity search

        +

get_customer_purchase_summary()

        |
        v

SQL aggregation

        |
        v

Combined verified response

Process:

1. MCP Server เรียก semantic search
   จาก interaction_history ด้วย pgvector


2. MCP Server เรียก financial summary
   จาก purchase_orders ด้วย SQL aggregation


3. รวมผลลัพธ์:

- Customer Context
- Relevant Interaction
- Exact Financial Amount


ส่งกลับไปยัง LLM

### 4. Security Guardrails

- ตรวจจับ prompt injection patterns
- ตรวจสอบ customer_id ก่อนเข้าถึงข้อมูล
- จำกัดให้เข้าถึงข้อมูลผ่าน MCP tools เท่านั้น

## เทคโนโลยีที่ใช้

- Python 3.12+
- FastMCP
- asyncpg
- pydantic
- openai
- google-genai
- PostgreSQL 17 + pgvector
- Docker Compose

## โครงสร้างโปรเจกต์

```text
customer-mcp/
├── app/
│   ├── config.py
│   ├── database.py
│   ├── embeddings.py
│   ├── mcp_server.py
│   ├── security.py
│   └── tools/
│       ├── customer.py
│       ├── financial.py
│       └── semantic_search.py
├── docs/
│   └── ARCHITECTURE.md
├── sql/
│   ├── 01_extensions.sql
│   ├── 02_schema.sql
│   ├── 03_indexes.sql
│   ├── 04_seed.sql
│   └── 05_security.sql
├── docker-compose.yml
├── requirements.txt
├── test_customer.py
├── test_embedding.py
├── test_financial.py
├── test_search.py
├── test_security.py
└── README.md
```

## ข้อกำหนดเบื้องต้น

- Python 3.12 หรือใหม่กว่า
- Docker Desktop
- Network access สำหรับติดตั้ง package จาก PyPI

## การติดตั้งและตั้งค่า

### 1. สร้าง virtual environment

```bash
py -3.12 -m venv venv
```

บน Windows:

```bash
venv\Scripts\activate
```

### 2. ติดตั้ง dependency

```bash
pip install -r requirements.txt
```

### 3. ตั้งค่า environment variables

สร้างไฟล์ `.env` โดยมีตัวอย่างดังนี้

```env
DATABASE_URL=postgresql://mcp_readonly_user:CHANGE_ME@localhost:5432/customer_mcp

GEMINI_API_KEY=your_gemini_api_key_here
```

### 4. เริ่มฐานข้อมูล PostgreSQL

```bash
docker compose up -d
```
Docker Compose จะสร้าง PostgreSQL + pgvector container และ initialize database อัตโนมัติจาก SQL scripts ใน folder sql/

หมายเหตุ:
SQL scripts ใน docker-entrypoint-initdb.d จะทำงานเฉพาะครั้งแรกที่สร้าง PostgreSQL volume เท่านั้น

หากต้องการ initialize ใหม่ทั้งหมด:

docker compose down -v

docker compose up -d

### Initialization order

sql/01_extensions.sql
    Enable PostgreSQL extensions
    Enable pgvector
sql/02_schema.sql
    Create customer tables
    Create interaction history table
    Create purchase tables
    Create immutable audit structure
sql/03_indexes.sql
    Create database indexes
    Create pgvector HNSW index สำหรับ semantic search
sql/04_seed.sql
    Insert demo customer data
    Insert interaction history
    Insert purchase records
    Insert audit records
sql/05_security.sql
    Create read-only database user
    Grant SELECT permission

ตรวจสอบ container
```bash
docker ps
```
### 5. Run MCP Server

```bash
python -m app.mcp_server
```

### MCP Inspector

สามารถตรวจสอบ MCP Tools ผ่าน UI ได้ด้วย

```bash
mcp-inspector python -m app.mcp_server
```

## MCP Tools ที่มีอยู่

### get_customer_profile

ดึงข้อมูลโปรไฟล์ของ customer

Data source:

- customers table

คืนค่า:

- customer_id
- first_name
- last_name
- email
- phone
- created_at


ตัวอย่าง input:

```json
{
  "customer_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

### search_customer_interactions

Semantic search สำหรับค้นหา Interaction History ผ่าน pgvector

ตัวอย่าง input:

```json
{
  "customer_id": "550e8400-e29b-41d4-a716-446655440000",
  "query": "refund issue",
  "limit": 3
}
```

### get_customer_purchase_summary

ดึงข้อมูลยอดซื้อแบบ Exact Value จาก SQL Aggregation

ตัวอย่าง input:

```json
{
  "customer_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

## Available MCP Tools

| Tool | Purpose |
|---|---|
| get_customer_profile | Retrieve customer profile information |
| search_customer_interactions | Semantic search customer conversation history |
| get_customer_purchase_summary | Retrieve exact financial summary and audit log |



## การทดสอบ (Testing)

โปรเจกต์นี้ใช้ `pytest` สำหรับการทดสอบ (Unit & Integration Tests) เพื่อความมั่นใจในความถูกต้องของข้อมูลและความปลอดภัย

## หมายเหตุด้านความปลอดภัย

- LLM ไม่สามารถเข้าถึง Database โดยตรง
- การเข้าถึงข้อมูลต้องผ่าน MCP Tools เท่านั้น
- ใช้ Input Validation สำหรับ customer_id
- ตรวจจับ Prompt Injection Pattern
- Financial Data ใช้ SQL Aggregation เพื่อคืนค่า Exact Value
- Audit Log เป็น Immutable Append Only Structure
- Database User สำหรับ MCP ใช้ Least Privilege Permission
- ไม่อนุญาต UPDATE / DELETE / DDL Operation