Customer MCP Server

Customer MCP Server es un proyecto para conectar LLM con los datos de los clientes, utilizando el Model Context Protocol (MCP) para que el cliente de IA pueda acceder a los datos de los clientes de forma segura y con un marco de control claro.

Descripción general del sistema

Este sistema está diseñado para que el LLM pueda consultar información de los clientes únicamente a través de las herramientas definidas, sin necesidad de acceder directamente a la base de datos.

Funcionalidades

• Recuperar información básica del cliente.

• Buscar en el historial de comunicaciones del cliente mediante búsqueda semántica con embeddings vectoriales.

• Resumir las compras y transacciones financieras con valor exacto.

• Registrar un audit log de las transacciones.

• Prevenir la inyección de prompts y el acceso no autorizado a los datos.

Arquitectura

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

Características principales

1. Perfil del cliente

• Recupera la información básica del cliente, como customer_id, name, email, phone, created_at.

2. Búsqueda semántica de interacciones

• Busca el historial de conversaciones/interacciones del cliente mediante vectores de embedding.

• Ideal para buscar significado en preguntas amplias, como refund issue, complaint, billing concern.

3. Resumen financiero

• Calcula el número de pedidos y el importe total de compras a partir de la base de datos.

• Utiliza agregación SQL para obtener valores precisos y fiables.

• Devuelve el audit log de la transacción junto con una referencia hash.

Ejemplo de consulta híbrida

Ejemplo de pregunta:

"¿Qué problemas ha reportado el cliente y cuál es el importe total de sus compras?"

Flujo:

search_customer_interactions()

    |
    v

Búsqueda de similitud pgvector

    +

get_customer_purchase_summary()

    |
    v

Agregación SQL

    |
    v

Respuesta combinada verificada

Proceso:

1. El servidor MCP realiza una búsqueda semántica en interaction_history mediante pgvector.

2. El servidor MCP obtiene el resumen financiero de purchase_orders mediante agregación SQL.

3. Combina los resultados:

• Contexto del cliente

• Interacción relevante

• Importe financiero exacto

Los envía de vuelta al LLM.

4. Medidas de seguridad

• Detecta patrones de inyección de prompts.

• Valida customer_id antes de acceder a los datos.

• Limita el acceso a los datos únicamente a través de las herramientas MCP.

Tecnologías utilizadas

• Python 3.12+

• FastMCP

• asyncpg

• pydantic

• openai

• google-genai

• PostgreSQL 17 + pgvector

• Docker Compose

Estructura del proyecto

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

Requisitos previos

• Python 3.12 o superior.

• Docker Desktop.

• Acceso a la red para instalar paquetes desde PyPI.

Instalación y configuración

1. Crear un entorno virtual

py -3.12 -m venv venv

En Windows:

venv\Scripts\activate

2. Instalar dependencias

pip install -r requirements.txt

3. Configurar las variables de entorno

Crea un archivo .env con el siguiente ejemplo:

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

GEMINI_API_KEY=your_gemini_api_key_here

4. Iniciar la base de datos PostgreSQL

docker compose up -d

Docker Compose creará el contenedor PostgreSQL + pgvector e inicializará la base de datos automáticamente desde los scripts SQL de la carpeta sql/.

Nota: Los scripts SQL en docker-entrypoint-initdb.d solo se ejecutan la primera vez que se crea el volumen de PostgreSQL.

Si deseas volver a inicializar todo:

docker compose down -v

docker compose up -d

Orden de inicialización

sql/01_extensions.sql Habilitar extensiones de PostgreSQL Habilitar pgvector sql/02_schema.sql Crear tablas de clientes Crear tabla de historial de interacciones Crear tablas de compras Crear estructura de auditoría inmutable sql/03_indexes.sql Crear índices de base de datos Crear índice pgvector HNSW para búsqueda semántica sql/04_seed.sql Insertar datos de clientes de demostración Insertar historial de interacciones Insertar registros de compras Insertar registros de auditoría sql/05_security.sql Crear usuario de base de datos de solo lectura Otorgar permiso SELECT

Comprobar el contenedor

docker ps

5. Ejecutar MCP Server

python -m app.mcp_server

MCP Inspector

También puedes inspeccionar las herramientas MCP a través de la interfaz de usuario.

mcp-inspector python -m app.mcp_server

Herramientas MCP disponibles

get_customer_profile

Recupera el perfil del cliente.

Fuente de datos:

• tabla customers

Devuelve:

• customer_id

• first_name

• last_name

• email

• phone

• created_at

Ejemplo de entrada:

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

search_customer_interactions

Búsqueda semántica para consultar el historial de interacciones mediante pgvector.

Ejemplo de entrada:

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

get_customer_purchase_summary

Recupera el resumen de compras con valor exacto mediante agregación SQL.

Ejemplo de entrada:

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

Herramientas MCP disponibles

Pruebas

Puedes ejecutar los siguientes archivos de prueba desde la raíz del repositorio:

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

Notas de seguridad

• El LLM no puede acceder directamente a la base de datos.

• El acceso a los datos debe realizarse únicamente a través de las herramientas MCP.

• Se aplica validación de entrada para customer_id.

• Se detectan patrones de inyección de prompts.

• Los datos financieros utilizan agregación SQL para devolver valores exactos.

• El audit log es una estructura inmutable de solo añadir.

• El usuario de base de datos para MCP utiliza permisos de privilegio mínimo.

• No se permiten operaciones UPDATE / DELETE / DDL.