Customer MCP Server

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

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

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

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

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

สถาปัตยกรรม

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

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

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

py -3.12 -m venv venv

บน Windows:

venv\Scripts\activate

2. ติดตั้ง dependency

pip install -r requirements.txt

3. ตั้งค่า environment variables

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

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

GEMINI_API_KEY=your_gemini_api_key_here

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

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

docker ps

5. Run MCP Server

python -m app.mcp_server

MCP Inspector

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

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:

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

search_customer_interactions

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

ตัวอย่าง input:

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

get_customer_purchase_summary

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

ตัวอย่าง input:

{
  "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

การทดสอบ

สามารถรันไฟล์ทดสอบต่อไปนี้จาก repository root:

python test_embedding.py
python test_search.py
python test_financial.py
python test_security.py
python test_customer.py

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

• 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