Customer MCP Server

Customer MCP Server — это проект для подключения LLM к данным о клиентах с использованием Model Context Protocol (MCP), который позволяет AI-клиентам безопасно и в рамках четко заданных правил получать доступ к информации о клиентах.

Обзор системы

Система спроектирована так, чтобы LLM мог запрашивать данные о клиентах только через заданные инструменты, без прямого доступа к базе данных.

Возможности

• Получение базовой информации о клиентах.

• Семантический поиск истории общения с клиентом с помощью векторных эмбеддингов.

• Формирование сводки по покупкам и финансовым операциям с точными значениями.

• Ведение журнала аудита операций.

• Защита от prompt-инъекций и несанкционированного доступа к данным.

Архитектура

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

Основные функции

1. Профиль клиента

• Получение базовой информации о клиенте, такой как customer_id, name, email, phone, created_at.

2. Семантический поиск по взаимодействиям

• Поиск истории разговоров/взаимодействий с клиентом с помощью вектора эмбеддингов.

• Подходит для смыслового поиска по общим вопросам, например: refund issue, complaint, billing concern.

3. Финансовая сводка

• Вычисляет количество заказов и общую сумму покупок из базы данных.

• Использует SQL-агрегацию для получения точных и надежных значений.

• Возвращает журнал аудита операций со ссылкой на хэш.

Пример гибридного запроса

Пример вопроса:

«С какими проблемами обращался клиент и какова общая сумма его покупок?»

Поток:

search_customer_interactions()

    |
    v

поиск по сходству pgvector

    +

get_customer_purchase_summary()

    |
    v

SQL-агрегация

    |
    v

Объединенный проверенный ответ

Процесс:

1. MCP-сервер выполняет семантический поиск по interaction_history с помощью pgvector.

2. MCP-сервер получает финансовую сводку из purchase_orders с помощью SQL-агрегации.

3. Объединяет результаты:

• Контекст клиента

• Релевантное взаимодействие

• Точная финансовая сумма

и отправляет обратно в LLM.

4. Защитные ограничения

• Обнаруживает паттерны prompt injection.

• Проверяет 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/.

Примечание: SQL-скрипты в docker-entrypoint-initdb.d выполняются только при первом создании тома PostgreSQL.

Если нужно переинициализировать всё:

docker compose down -v

docker compose up -d

Порядок инициализации

sql/01_extensions.sql Включение расширений PostgreSQL Включение pgvector sql/02_schema.sql Создание таблиц клиентов Создание таблицы истории взаимодействий Создание таблиц покупок Создание неизменяемой структуры аудита sql/03_indexes.sql Создание индексов базы данных Создание HNSW-индекса pgvector для семантического поиска sql/04_seed.sql Вставка демонстрационных данных клиентов Вставка истории взаимодействий Вставка записей о покупках Вставка записей аудита sql/05_security.sql Создание пользователя базы данных только для чтения Предоставление разрешения SELECT

Проверьте контейнер

docker ps

5. Запуск MCP-сервера

python -m app.mcp_server

MCP Inspector

MCP-инструменты можно просмотреть через UI.

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.

Пример ввода:

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

get_customer_purchase_summary

Получение точной суммы покупок с помощью SQL-агрегации.

Пример ввода:

{
  "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-инструменты.

• Используется проверка входных данных (Input Validation) для customer_id.

• Обнаружение паттернов prompt injection.

• Финансовые данные используют SQL-агрегацию для возврата точных значений.

• Журнал аудита является неизменяемой структурой с добавлением только записей.

• Пользователь базы данных для MCP имеет минимально необходимые привилегии.

• Операции UPDATE / DELETE / DDL не разрешены.