Asistente de Soporte al Cliente con MCP

Un proyecto Model Context Protocol (MCP) orientado a la producción, creado con Node.js, TypeScript, MongoDB y un LLM.

Este proyecto demuestra cómo una aplicación de IA puede interactuar con sistemas externos a través de herramientas MCP de forma estructurada, segura y escalable.

El proyecto se desarrolla de forma incremental, desde un servidor y una herramienta MCP básicos hasta un sistema de soporte al cliente impulsado por IA con estilo y estructura de producción.

Visión General del Proyecto

El objetivo de este proyecto es construir un asistente de soporte al cliente impulsado por IA que pueda entender las solicitudes de los usuarios y usar herramientas MCP para realizar operaciones en el mundo real.

Ejemplo

Un usuario puede preguntar:

"Consulta mi último pedido y crea un ticket de soporte si está retrasado".

La IA puede determinar que necesita:

1. Encontrar al cliente.

2. Obtener los pedidos del cliente.

3. Identificar el pedido retrasado.

4. Crear un ticket de soporte.

La IA no accede directamente a la base de datos.

En su lugar, interactúa con la aplicación a través de herramientas MCP.

                         User
                           │
                           ▼
                      AI / LLM
                           │
                           ▼
                      MCP Client
                           │
                           ▼
                    ┌─────────────┐
                    │ MCP Server  │
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
       Customer Tool   Order Tool   Ticket Tool
              │            │            │
              └────────────┼────────────┘
                           ▼
                       Services
                           │
                           ▼
                        MongoDB

🎯 Objetivos del Proyecto

Este proyecto demuestra:

• Desarrollo de servidores MCP

• Creación de herramientas MCP

• Comunicación con clientes MCP

• Llamada a herramientas con IA

• Arquitectura TypeScript

• Integración con MongoDB

• Arquitectura de capa de servicios

• Validación de entradas

• Manejo de errores

• Autenticación y autorización

• Registro y monitorización de logs

• Registro de auditoría

• Arquitectura MCP orientada a producción

• Flujos de trabajo de agentes de IA

🛠️ Stack Tecnológico

Backend

• Node.js

• TypeScript

• SDK de MCP

• Zod

• MongoDB

• Mongoose

IA

• Integración con LLM

• Llamada de herramientas

• Flujo de trabajo de agente de IA

Desarrollo

• MCP Inspector

• Git

• GitHub

• npm

Infraestructura de producción planificada

• Docker

• Redis

• Autenticación

• Limitación de peticiones (rate limiting)

• Registro de logs

• Monitorización

• CI/CD

📁 Estructura del Proyecto

mcp-customer-support/
│
├── src/
│   │
│   ├── index.ts
│   │
│   ├── tools/
│   │   ├── customer.tools.ts
│   │   ├── order.tools.ts
│   │   └── ticket.tools.ts
│   │
│   ├── services/
│   │   ├── customer.service.ts
│   │   ├── order.service.ts
│   │   └── ticket.service.ts
│   │
│   ├── models/
│   │   ├── customer.model.ts
│   │   ├── order.model.ts
│   │   └── ticket.model.ts
│   │
│   ├── db/
│   │   └── database.ts
│   │
│   ├── middleware/
│   │   └── auth.ts
│   │
│   └── utils/
│       ├── logger.ts
│       └── errors.ts
│
├── tests/
│
├── .env.example
├── .gitignore
├── package.json
├── package-lock.json
├── tsconfig.json
└── README.md

🏗️ Fases de Desarrollo

El proyecto está dividido intencionadamente en fases para que cada una introduzca un concepto importante de MCP o de producción.

Fase 1 — Fundamentos del Servidor MCP

Objetivo

Crear un servidor MCP básico y exponer la primera herramienta.

Implementado

• Proyecto Node.js

• Configuración de TypeScript

• SDK de MCP

• Servidor MCP

• Transporte STDIO

• Validación de entrada con Zod

• Primera herramienta MCP

• Integración con MCP Inspector

Primera Herramienta

find_customer

Entrada:

{
  "email": "ashwani@example.com"
}

Salida:

{
  "id": "customer_123",
  "name": "Ashwani Yadav",
  "email": "ashwani@example.com"
}

Arquitectura

MCP Inspector
      │
      ▼
MCP Client
      │
      │ STDIO
      ▼
MCP Server
      │
      ▼
find_customer()
      │
      ▼
Dummy Data

Estado

Completado ✅

Fase 2 — Múltiples Herramientas MCP

Objetivo

Crear múltiples herramientas que representen operaciones reales de soporte al cliente.

Herramientas

find_customer
get_customer_orders
create_support_ticket

Ejemplo

find_customer (encontrar_cliente)

find_customer(email)

get_customer_orders (obtener_pedidos_de_cliente)

get_customer_orders(customerId)

create_support_ticket (crear_ticket_de_soporte)

create_support_ticket(
    customerId,
    orderId,
    issue
)

Arquitectura Esperada

                    MCP Server
                        │
        ┌───────────────┼───────────────┐
        ▼               ▼               ▼
find_customer()   get_orders()   create_ticket()

Estado

Planificado 🚧

Fase 3 — Integración con MongoDB

Objetivo

Reemplazar los datos simulados por datos reales y persistentes.

Base de Datos

MongoDB

Colecciones

customers
orders
support_tickets

Arquitectura

MCP Tool
   │
   ▼
Service Layer
   │
   ▼
Mongoose
   │
   ▼
MongoDB

Ejemplo

find_customer()
      │
      ▼
customer.service.ts
      │
      ▼
Customer Model
      │
      ▼
MongoDB

Beneficios

• Datos persistentes

• Consultas de base de datos adecuadas

• Indexación

• Validación de esquema

• Acceso escalable a los datos

Índice Planificado

customers.email

Esto permite que la búsqueda de clientes por correo electrónico siga siendo eficiente a medida que el conjunto de datos crezca.

Estado

Planificado 🚧

Fase 4 — Capa de servicios y Arquitectura Limpia

Objetivo

Mantener las herramientas MCP separadas de la lógica de negocio.

En lugar de poner la lógica de la base de datos directamente dentro de la herramienta MCP:

Tool
 ↓
Service
 ↓
Database

Ejemplo

customer.tools.ts
        │
        ▼
customer.service.ts
        │
        ▼
customer.model.ts
        │
        ▼
MongoDB

¿Por qué?

Esto nos proporciona:

• Separación de responsabilidades: separación de responsabilidades

• Capacidad de prueba

• Reutilización

• Mantenibilidad

• Migración más fácil a REST/GraphQL/servicios internos

Estado

Planificado 🚧

Fase 5 — Cliente MCP

Objetivo

Desarrollar un cliente MCP dedicado que se conecte al servidor MCP.

┌──────────────┐
│ MCP Client   │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ MCP Server   │
└──────────────┘

El cliente podrá:

Descubrir herramientas

listTools()

Ejecutar herramientas

callTool()

Por ejemplo:

callTool(
    "find_customer",
    {
        email: "ashwani@example.com"
    }
)

Estado

Planificado 🚧

Fase 6 — Integración con LLM

Objetivo

Conectar un LLM al cliente MCP.

La arquitectura queda así:

User
 │
 ▼
LLM
 │
 ▼
MCP Client
 │
 ▼
MCP Server
 │
 ▼
Tools
 │
 ▼
MongoDB

El LLM decidirá qué herramienta se debe llamar en función de la solicitud del usuario.

Ejemplo

Usuario:

Check my latest order.

IA:

I need the customer's orders.

Herramienta:

get_customer_orders()

La herramienta devuelve los datos del pedido.

La IA genera entonces una respuesta en lenguaje natural.

Estado

Planificado 🚧

Fase 7 — Flujo de Trabajo de Agente de IA

Objetivo

Permitir que el LLM realice flujos de trabajo de varios pasos.

Ejemplo de solicitud:

Check my latest order and create a support
ticket if it is delayed.

Flujo de trabajo de la IA:

             User Request
                   │
                   ▼
                 LLM
                   │
                   ▼
           find_customer()
                   │
                   ▼
        get_customer_orders()
                   │
                   ▼
           Analyze orders
                   │
                   ▼
        Is order delayed?
              /          \
            Yes           No
             │             │
             ▼             ▼
 create_support_ticket   Response
             │
             ▼
          Response

Esto demuestra la diferencia entre simplemente exponer herramientas y construir un agente de IA capaz de orquestar herramientas de orquestación.

Estado

Planificado 🚧

8 — Autenticación y Autorización

Objetivo

Proteger las operaciones MCP.

La autenticación verifica:

¿Quién es el usuario?

La autorización verifica:

¿Qué se le permite hacer al usuario?

Ejemplo de permisos:

customer.read
order.read
ticket.create
ticket.update
admin.refund

Ejemplo permisos:

Customer
 ├── find_customer       ✅
 ├── get_orders          ✅
 ├── create_ticket       ✅
 └── refund_order        ❌

Admin
 ├── find_customer       ✅
 ├── get_orders          ✅
 ├── create_ticket       ✅
 └── refund_order        ✅

Estado

Planificado 🚧

🌐 Manejo de Errores

Objetivo

Crear un manejo de errores coherente en todas las herramientas.

Ejemplo ejemplo:

CustomerNotFoundError
OrderNotFoundError
UnauthorizedError
ValidationError
DatabaseError
ToolExecutionError

Las respuestas de las herramientas MCP comunicarán claramente los fallos.

Ejemplo errores:

{
  "isError": true,
  "message": "Customer not found"
}

Estado

Planificado 🚧

10 — Registro de Logs y Observabilidad

Objetivo

Realizar un seguimiento de las operaciones del MCP en producción.

Cada ejecución de una herramienta debe proporcionar información como:

Request ID
User ID
Tool name
Arguments
Execution time
Status
Error
Timestamp

Ejemplo registro:

INFO Tool Execution

tool: get_customer_orders
customerId: customer_123
duration: 85ms
status: success

Objetivos de Monitorización

• Latencia de herramientas

• Tasa de errores

• Latencia de la base de datos

• Latencia de la respuesta de la IA

• Frecuencia de uso de herramientas

• Llamadas de herramientas fallidas

Estado

Planificado 🚧

11 — Limitación de Peticiones

Objetivo

Proteger el servidor MCP de solicitudes excesivas o abusivas.

Estrategia potencial:

User
 │
 ▼
Rate Limiter
 │
 ├── Allowed ──→ MCP Tool
 │
 └── Blocked ──→ Rate Limit Error

Se puede introducir Redis para la limitación de peticiones distribuida.

Ejemplo ejemplo:

100 requests / minute / user

Estado

Planificado 🚧

12 — Registro de Auditoría

Objetivo

Registrar las operaciones sensibles impulsadas por la IA.

Por ejemplo:

User:
customer_123

AI requested:
create_support_ticket

Order:
order_123

Action:
Support ticket created

Timestamp:
2026-08-23T10:30:00Z

Esto es particularmente importante cuando los agentes de IA pueden realizar acciones que modifiquen datos empresariales.

Estado

Planificado 🚧

13 — Pruebas

Pruebas unitarias

Probar:

• Servicios

• Módulos de validación

• Lógica de negocio

• Manejo de errores

Pruebas de integración

Probar:

MCP Tool
   ↓
Service
   ↓
MongoDB

Pruebas MCP

Probar:

MCP Client
   ↓
MCP Server
   ↓
Tool

Ejemplo

find_customer
    ↓
valid email
    ↓
customer returned

y:

find_customer
    ↓
invalid email
    ↓
validation error

Estado

Planificado 🚧

14 — Dockerización

Objetivo

Contener la aplicación.

Docker
│
├── MCP Server
│
├── MongoDB
│
└── Redis

Ejemplo de arquitectura de producción:

                 ┌─────────────┐
                 │   AI App    │
                 └──────┬──────┘
                        │
                        ▼
                 ┌─────────────┐
                 │ MCP Server  │
                 └──────┬──────┘
                        │
             ┌──────────┼──────────┐
             ▼          ▼          ▼
          MongoDB     Redis      Logs

Estado

Planificado 🚧

Fase 15 — CI/CD

Objetivo

Automatizar las pruebas y el despliegue.

Pipeline:

Developer
    │
    ▼
Git Push
    │
    ▼
GitHub Actions
    │
    ├── Install dependencies
    ├── Lint
    ├── Type check
    ├── Run tests
    ├── Build
    └── Deploy

Estado

Planificado 🚧

🔐 Variables de Entorno

Nunca confirmes .env en GitHub.

Utiliza:

.env

para el desarrollo local.

Ejemplo:

MONGODB_URI=mongodb://localhost:27017/mcp-support
OPENAI_API_KEY=your_api_key
JWT_SECRET=your_secret

Proporciona:

.env.example

en su lugar:

MONGODB_URI=
OPENAI_API_KEY=
JWT_SECRET=

🧪 Desarrollo

Instalar dependencias:

npm install

Ejecutar el servidor de desarrollo:

npm run dev

Compilar:

npm run build

Ejecutar la compilación para producción:

npm start

🔍 MCP Inspector

El MCP Inspector se utiliza para probar el servidor MCP e inspeccionar las herramientas disponibles durante el desarrollo.

Ejemplo:

npx @modelcontextprotocol/inspector npx tsx src/index.ts

El Inspector nos permite: Inspector nos permite:

• Conectarnos al servidor MCP

• Descubrir herramientas

• Inspeccionar los esquemas de las herramientas

• Ejecutar herramientas

• Inspeccionar las respuestas

• Depurar la comunicación MCP

🧠 Conceptos MCP Demostrados

Este proyecto demuestra los siguientes conceptos de MCP:

Servidor MCP

Proporciona capacidades a los clientes MCP.

Cliente MCP

Se conecta a los servidores MCP e invoca sus capacidades.

Herramientas

Operaciones ejecutables expuestas a los sistemas de IA.

Ejemplos:

find_customer
get_customer_orders
create_support_ticket

Recursos

Datos contextuales de solo lectura que se pueden exponer a un cliente MCP.

Posibles recursos futuros:

customer://customer_123
order://order_123

Prompts

Plantillas o flujos de trabajo de prompt reutilizables que se exponen a través de MCP.

Posibles ejemplos:

Ejemplos potenciales:

customer_support_resolution

🏆 Arquitectura de Producción

La arquitectura final está prevista que tenga el siguiente aspecto:

                         ┌───────────────┐
                         │     User      │
                         └───────┬───────┘
                                 │
                                 ▼
                         ┌───────────────┐
                         │    LLM / AI   │
                         └───────┬───────┘
                                 │
                                 ▼
                         ┌───────────────┐
                         │  MCP Client   │
                         └───────┬───────┘
                                 │
                                 ▼
                    ┌────────────────────────┐
                    │       MCP Server       │
                    │                        │
                    │ Authentication         │
                    │ Authorization          │
                    │ Validation             │
                    │ Rate Limiting          │
                    │ Logging                │
                    └───────────┬────────────┘
                                │
               ┌────────────────┼────────────────┐
               ▼                ▼                ▼
        Customer Tool      Order Tool       Ticket Tool
               │                │                │
               └────────────────┼────────────────┘
                                ▼
                         Service Layer
                                │
                ┌───────────────┼───────────────┐
                ▼               ▼               ▼
             MongoDB          Redis          Logging

📌 Progreso Actual

💡 Ejemplo de Conversación Futura

Una vez completadas todas las fases, el sistema debería admitir conversaciones como:

Usuario

Mi último pedido no ha llegado. ¿Puedes comprobarlo y crear un ticket de soporte?

IA

1. Find customer
2. Retrieve orders
3. Identify delayed order
4. Create support ticket
5. Return ticket information

Respuesta del companero AI

Su pedido ORD-123 está retrasado. He creado el ticket de soporte TICKET-456 para usted.

🎓 Temas de Entrevistas Cubiertos

Este proyecto se puede utilizar para demostrar conocimientos sobre:

• Model Context Protocol

• Agentes de IA

• Llamadas de herramientas LLM

• Llamada de funciones (function calling)

• Servidores MCP

• Clientes MCP

• Descubrimiento de herramientas

• Ejecución de herramientas

• TypeScript

• Node.js

• MongoDB

• Mongoose

• Arquitectura limpia

• Arquitectura de capa de servicios

• Autenticación

• Autorización

• RBAC

• Limitación de peticiones

• Redis

• Registro de logs

• Observabilidad

• Docker

• CI/CD

• GitHub Actions

• Pruebas de software

• Arquitectura backend escalable

📈 Mejoras Futuras

Las posibles mejoras futuras incluyen:

• Múltiples servidores MCP

• Herramientas MCP de pagos

• Herramientas MCP de correo electrónico

• Integración con CRM

• Integración con Slack

• Integración con GitHub

• Base de datos vectorial

• RAG

• Búsqueda semántica

• Aprobación de humano-en-el-bucle (human-in-the-loop)

• Políticas de permisos de herramientas

• Trazabilidad de ejecución de herramientas

• Despliegue MCP distribuido

• Despliegue en Kubernetes

👨💻 Filosofía de Desarrollo

El proyecto sigue estos principios:

• Separación de responsabilidades

• Tipado fuerte

• Validación de entrada

• Gestión segura de secretos

• Lógica de negocio bajo pruebas

• Ejecución de herramientas observable

• Acceso a herramientas con el menor privilegio

• Arquitectura escalable

• Límites MCP claros

📜 Licencia

Este proyecto está pensado para el aprendizaje, la experimentación y demostración de conceptos de ingeniería MCP/IA.

Añade una licencia de código abierto adecuada antes de distribuirlo públicamente.