Customer MCP Server

Customer MCP Server는 Model Context Protocol(MCP)을 사용하여 LLM과 고객 데이터를 연결하는 프로젝트로, AI Client가 명확한 통제 프레임워크 안에서 안전하게 고객 데이터에 접근할 수 있게 합니다.

시스템 개요

이 시스템은 LLM이 데이터베이스에 직접 접근하지 않고 정의된 도구를 통해서만 고객 데이터를 조회할 수 있도록 설계되었습니다.

지원 기능

• 기본 고객 데이터 조회

• vector embedding을 사용한 고객 커뮤니케이션 기록 의미 검색(semantic search)

• 구매 및 금융 거래를 정확한 값(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

• embedding vector를 사용하여 고객 대화/상호작용 기록 검색

• refund issue, complaint, billing concern 같은 광범위한 질문에 대한 의미 검색에 적합

3. Financial Summary

• 데이터베이스에서 주문 수 및 총 구매 금액 계산

• 정확하고 신뢰할 수 있는 값을 얻기 위해 SQL aggregation 사용

• hash reference와 함께 거래 감사 로그 반환

하이브리드 쿼리 예시

예시 질문:

"고객이 어떤 문제를 보고했으며 총 구매 금액은 얼마인가요?"

흐름:

search_customer_interactions()

    |
    v

pgvector 유사도 검색

    +

get_customer_purchase_summary()

    |
    v

SQL 집계

    |
    v

결합된 검증 응답

프로세스:

1. MCP Server는 pgvector를 사용하여 interaction_history에서 semantic search를 호출합니다.

2. MCP Server는 SQL 집계를 사용하여 purchase_orders에서 financial summary를 호출합니다.

3. 결과 결합:

• Customer Context

• Relevant Interaction

• Exact Financial Amount

LLM으로 다시 전송합니다.

4. Security Guardrails

• 프롬프트 인젝션 패턴 감지

• 데이터 접근 전에 customer_id 확인

• MCP 도구를 통해서만 데이터에 접근하도록 제한

사용 기술

• 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

• PyPI에서 패키지를 설치하기 위한 네트워크 액세스

설치 및 설정

1. 가상 환경 생성

py -3.12 -m venv venv

Windows의 경우:

venv\Scripts\activate

2. 종속성 설치

pip install -r requirements.txt

3. 환경 변수 설정

.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 컨테이너를 생성하고 sql/ 폴더의 SQL 스크립트로 데이터베이스를 자동으로 초기화합니다.

참고:

docker-entrypoint-initdb.d의 SQL 스크립트는 PostgreSQL 볼륨이 처음 생성될 때만 실행됩니다.

전체 재초기화가 필요한 경우:

docker compose down -v

docker compose up -d

초기화 순서

sql/01_extensions.sql PostgreSQL 확장 활성화 pgvector 활성화 sql/02_schema.sql 고객 테이블 생성 상호작용 기록 테이블 생성 구매 테이블 생성 불변 감사 구조 생성 sql/03_indexes.sql 데이터베이스 인덱스 생성 semantic search용 pgvector HNSW 인덱스 생성 sql/04_seed.sql 데모 고객 데이터 삽입 상호작용 기록 삽입 구매 기록 삽입 감사 기록 삽입 sql/05_security.sql 읽기 전용 데이터베이스 사용자 생성 SELECT 권한 부여

컨테이너 확인

docker ps

5. MCP 서버 실행

python -m app.mcp_server

MCP Inspector

UI를 통해 MCP 도구를 검사할 수 있습니다.

mcp-inspector python -m app.mcp_server

사용 가능한 MCP 도구

get_customer_profile

고객의 프로필 정보를 조회합니다.

데이터 소스:

• customers 테이블

반환 값:

• customer_id

• first_name

• last_name

• email

• phone

• created_at

입력 예시:

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

search_customer_interactions

pgvector를 통한 Interaction History 의미 검색(semantic search)입니다.

입력 예시:

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

get_customer_purchase_summary

SQL 집계에서 정확한 값(Exact Value)으로 구매 요약을 조회합니다.

입력 예시:

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

사용 가능한 MCP 도구

테스트

저장소 루트에서 다음 테스트 파일을 실행할 수 있습니다.

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

보안 참고 사항

• LLM은 데이터베이스에 직접 접근할 수 없습니다.

• 데이터 접근은 MCP 도구를 통해서만 허용됩니다.

• customer_id에 대한 입력 검증(Input Validation) 사용

• 프롬프트 인젝션 패턴 감지

• 금융 데이터는 SQL 집계를 사용하여 정확한 값(Exact Value)을 반환합니다.

• 감사 로그는 불변(Immutable) 추가 전용(Append Only) 구조입니다.

• MCP용 데이터베이스 사용자는 최소 권한(Least Privilege)으로 설정됩니다.

• UPDATE / DELETE / DDL 작업은 허용되지 않습니다.